miaoda-game-stats-cocos

Use this Cocos Creator adapter to attach a StatSet to a node and let Cocos update(dt) expire timed modifiers. All stat math and buff behavior comes from miaoda-game-stats-core.

Install and use

pnpm add miaoda-game-stats-core miaoda-game-stats-cocos

Cocos Creator provides the optional cc peer dependency at runtime.

import { StatsComponent } from 'miaoda-game-stats-cocos';

const stats = enemy.addComponent(StatsComponent).setup({
  maxHp: 100,
  attack: { base: 10, bounds: { min: 0 } },
  moveSpeed: 5,
});

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

update(dt) forwards Cocos seconds to StatSet.tick. Use setTicking(false) to pause timed expiry while leaving the node enabled. setup replaces the entire sheet; use define to add one stat at runtime.

stats exposes the underlying StatSet for JSON save/load, source removal, snapshots of active buffs, and standalone Stat operations. Destruction releases component-owned listeners and makes mutations inert.

For a game-owned fixed-tick loop, select manual ownership when replacing the sheet:

const stats = enemy.addComponent(StatsComponent).setup(
  { 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 Cocos lifecycle behavior. In manual mode, update(dt) is inert and stepSimulation(dtSeconds) is the only simulation entry. Calling the new method in host mode fails before mutation, so the Component and a coordinator cannot both expire timed buffs. setTicking remains a separate local pause and a paused manual step returns 0.

StatsComponentOptions and StatsTickSource are exported with the existing core types. The manual result reports the number of modifiers expired in that tick; toJSON() is the deterministic observation/save boundary. Invalid replacement options are rejected before the current sheet or source changes.