miaoda-game-progression-react

Use this React DOM adapter for XP bars, level labels, level-up result lists, and level-gated unlocks. The progression core remains the authority for curve math and awards; this package exposes a subscribed view for React components.

Install

pnpm add miaoda-game-progression-react miaoda-game-progression-core

Minimal component

import {
  useProgressionController,
  useProgressionView,
} from 'miaoda-game-progression-react';

export function HeroProgression() {
  const game = useProgressionController({
    curve: { costs: [100, 200, 400] },
    gates: [{ level: 2, value: 'shop' }, { level: 3, value: 'fireball' }],
  });
  const view = useProgressionView(game);

  return (
    <section>
      <strong>Level {view.level}</strong>
      <progress value={view.progress} max={1} />
      <button onClick={() => game.addXp(50)}>Award XP</button>
      {view.newlyUnlocked.map((item) => <p key={item}>Unlocked: {item}</p>)}
    </section>
  );
}

Use view.lastGain.levelsReached when one award can cross multiple levels. Use view.unlocked, view.locked, and view.newlyUnlocked for gate UI. view.isMaxLevel is true at the configured cap.

Do not call addXp or setTotalXp synchronously from onChange; defer the operation until the callback returns.

Restore progress

Persist view.totalXp with your game save and restore it with game.setTotalXp(totalXp). Restoration updates the view without firing level-up rewards; grant rewards only from a live addXp result.

Public API

• useProgressionController(options): creates one controller for the component lifetime.
• useProgressionView(controller): subscribes to XP and unlock changes.
• ProgressionController: addXp, setTotalXp, view, and onChange.
• Core exports such as LevelCurve, Progression, and UnlockTable are re-exported.

React 18.2+ is required. The adapter targets React DOM and does not render a particular visual style.