miaoda-game-stats-phaser

Use this Phaser 4 adapter to own a StatSet in a Scene, expire timed buffs from Phaser update events, and expose stat changes to HUDs and gameplay code.

Install and use

pnpm add miaoda-game-stats-core miaoda-game-stats-phaser

Register StatsPlugin and create one controller per actor or game scope:

const stats = this.statSets.create({
  hp: 100,
  attack: { base: 10, bounds: { min: 0 } },
  moveSpeed: 5,
});

stats.onChange('hp', (value) => updateHealthBar(value));
stats.applyBuff({
  id: 'slow', duration: 3,
  modifiers: [{ stat: 'moveSpeed', op: 'percentAdd', value: -0.5 }],
});

Phaser milliseconds are converted to core seconds automatically. setTicking(false) pauses expiry without clearing buffs. Use stats.stats for JSON persistence and direct core queries. Scene shutdown destroys the controller and detaches listeners; later mutations are inert.

For a game-owned fixed-tick loop, select manual ownership in the final optional argument:

const stats = this.statSets.create(
  { hp: 100, moveSpeed: 5 },
  { tickSource: 'manual' },
);

fixedStepper.advance(frameSeconds, (dt) => {
  const expiredModifierCount = stats.stepSimulation(dt);
  // Read stats.toJSON() or domain values after this committed tick.
});

The default tickSource: 'host' preserves Scene-driven behavior. Manual controllers do not register an update listener, but retain Scene shutdown cleanup. Calling stepSimulation(dtSeconds) on a host-owned controller fails before any modifier expires, preventing duplicate time authority. setTicking is a separate local pause and a paused manual step returns 0.

StatsControllerOptions, StatsTickSource, StatsController, and StatsPlugin are exported. The manual result is the number of modifiers that expired in that tick; toJSON() is the deterministic observation/save boundary. Input seconds must be finite and non-negative.