Level-Up Animation System

Learn how the XP progress bar animates and displays level-ups during battle results.

Overview

The level-up system uses two main components:

• XPProgresBar.tsx - Animated XP bar with level-up detection

• PartyMemberReward.tsx - Battle results card showing XP gain and level-ups

How It Works

Animation Flow

1. Start with pre-battle XP
   ↓
2. Animate toward post-battle XP
   ↓
3. Detect when XP crosses level threshold
   ↓
4. Fill bar to 100% → Show level-up → Reset bar for next level
   ↓
5. Continue animating toward final XP
   ↓
6. Show "LEVEL UP!" notification with final level

XPProgresBar Component

File: menus/src/components/XPProgresBar.tsx

Key Features

• Animates from startExp to targetExp over 1 second

• Detects level-ups during animation

• Updates level display in real-time

• Supports skip functionality

• Exposes level-up events via ref handle

Props

interface XPProgressBarProps {
  partyMember: Game_Actor;
  className: string;
  onAnimationComplete?: () => void;
  startExp?: number; // Override starting exp
  targetExp?: number; // Override target exp
}

Usage

<XPProgresBar
  ref={handle}
  partyMember={actor}
  className="w-96 h-10"
  startExp={actor.currentExp() - rewardExp}
  targetExp={actor.currentExp()}
  onAnimationComplete={handleComplete}
/>

Level-Up Detection Logic

The component pre-calculates all level-up thresholds:

// Find starting level based on startExp
let startLevel = member.level;
for (let lv = 1; lv <= member.maxLevel(); lv++) {
  const expForThisLevel = member.expForLevel(lv);
  const expForNextLevel = member.expForLevel(lv + 1);
  if (startXp >= expForThisLevel && startXp < expForNextLevel) {
    startLevel = lv;
    break;
  }
}

// Calculate all level thresholds between start and target
const levelUpThresholds = [];
let checkLevel = startLevel;
while (checkLevel < member.maxLevel()) {
  const expForNextLevel = member.expForLevel(checkLevel + 1);
  if (expForNextLevel <= endXp) {
    levelUpThresholds.push({
      level: checkLevel + 1,
      expRequired: expForNextLevel
    });
    checkLevel++;
  } else {
    break;
  }
}

During animation, check if thresholds are crossed:

const animator = () => {
  const elapsed = Date.now() - startTime;
  const currentXp = startXp + (xpPerMs * elapsed);

  // Check for level-ups
  for (const threshold of levelUpThresholds) {
    if (currentXp >= threshold.expRequired &&
        displayLevel < threshold.level) {
      // Level up!
      setDisplayLevel(threshold.level);
      setDisplayNextXp(member.expForLevel(threshold.level + 1));
      setLevelUpEvents(prev => [...prev, threshold.level]);
    }
  }

  setDisplayXp(currentXp);

  if (elapsed < maxTime) {
    requestAnimationFrame(animator);
  } else {
    onComplete();
  }
};

Skip Functionality

The component exposes a ref handle for skipping:

export type SkipHandle = {
  skip: () => void;
  getLevelUpEvents: () => number[];
};

useImperativeHandle(ref, () => ({
  skip: () => {
    if (frameRef.current) {
      cancelAnimationFrame(frameRef.current);
      frameRef.current = 0;
    }
    // Jump to final state
    currentXp.current = targetXp.current;
    setDisplayXp(currentXp.current);
    setDisplayLevel(member.level);
    setDisplayNextXp(member.nextLevelExp());
    onComplete();
  },
  getLevelUpEvents: () => levelUpEvents,
}));

PartyMemberReward Component

File: menus/src/components/PartyMemberReward.tsx

Wraps XPProgresBar and shows level-up notification.

Structure

<div className="party-member-reward">
  <ActorPortrait />
  <div>
    <div>Name & Level</div>
    <XPProgresBar
      ref={handle}
      startExp={startExp}
      targetExp={targetExp}
      onAnimationComplete={onAnimationComplete}
    />
    {levelUps.length > 0 && (
      <div className="level-up-notification">
        LEVEL UP! → Lv. {levelUps[levelUps.length - 1]}
      </div>
    )}
  </div>
</div>

Capturing Level-Ups

const onAnimationComplete = () => {
  setAnimating(false);
  setComplete(true);

  // Get level-up events from XPProgresBar
  if (handle.current) {
    const events = handle.current.getLevelUpEvents();
    if (events && events.length > 0) {
      setLevelUps(events);
    }
  }
};

BattleResults Integration

File: menus/src/views/battle/BattleResults.tsx

Shows all party members' XP gains:

const BattleResults = (props) => {
  const members = props.pageData.runtime.gameParty.members();
  const rewardRef = useRef(new Map());

  const continuePressed = () => {
    const refs = [...rewardRef.current.values()];
    if (refs.some(value => value?.shouldSkip())) {
      // Skip all animations
      refs.forEach(value => value?.skip());
    } else {
      // All complete, continue
      props.onContinue();
    }
  };

  return (
    <div>
      {members.map((m) => (
        <PartyMemberReward
          ref={(el) => rewardRef.current.set(m.actorId(), el)}
          key={m._actorId}
          member={m}
          rewardExp={rewards.exp}
        />
      ))}
      <button onClick={continuePressed}>Next</button>
    </div>
  );
};

Customization Examples

Custom Level-Up Animation

const AnimatedLevelUp = ({ level }) => {
  return (
    <div className="level-up animate-bounce">
      <div className="text-6xl">★</div>
      <div className="text-4xl text-yellow-400">
        LEVEL UP!
      </div>
      <div className="text-3xl">
        Lv. {level}
      </div>
    </div>
  );
};

// In PartyMemberReward
{levelUps.length > 0 && (
  <AnimatedLevelUp level={levelUps[levelUps.length - 1]} />
)}

Custom XP Bar Styling

<ProgressBar
  outerClassName="xp-bar-outer"
  outerStyle={{
    borderImageSource: 'url(/custom-border.png)',
    borderImageSlice: "5 20 fill"
  }}
  innerClassName="xp-bar-inner"
  innerStyle={{
    backgroundImage: 'linear-gradient(90deg, #4ade80, #22c55e)',
    boxShadow: '0 0 10px #4ade80'
  }}
  percent={(displayXp / displayNextXp) * 100}
>
  <div className="xp-text">
    Lv.{displayLevel} XP: {Math.floor(displayXp)}/{displayNextXp}
  </div>
</ProgressBar>

Sound Effects

// In XPProgresBar, when level-up detected
useEffect(() => {
  if (levelUpEvents.length > 0) {
    AudioManager.playSe({ name: 'LevelUp', volume: 90, pitch: 100, pan: 0 });
  }
}, [levelUpEvents]);

Multiple Level-Ups

If actor gains multiple levels:

{levelUps.map((level, i) => (
  <div key={i} className="level-up-badge">
    Lv. {level}!
  </div>
))}

Common Issues

Level doesn't update during animation

Cause: Not updating displayLevel state when threshold crossed

Fix: Ensure setDisplayLevel() called in animator loop

Bar shows wrong progress after level-up

Cause: Not updating displayNextXp when leveling up

Fix:

if (currentXp >= nextLevelThreshold) {
  setDisplayNextXp(member.expForLevel(newLevel + 1));
}

Skip jumps to wrong level

Cause: Not setting final level state in skip function

Fix:

skip: () => {
  setDisplayLevel(member.level); // Use actor's final level
  setDisplayNextXp(member.nextLevelExp());
}

Performance Tips

• Use refs for animation state to avoid re-renders

• Only update display state when actually needed

• Cancel animation frames on unmount

• Throttle display updates if animating many actors

See Also

• Battle System Architecture

• State Management

• Components Reference