miaoda-game-wave-cocos

Use this Cocos Creator component to drive either a discrete WaveRunner or continuous Director, resolve spawn-point IDs to scene nodes, and hand spawn requests to your prefab code.

Install

pnpm add miaoda-game-wave-cocos miaoda-game-wave-core

cc is an optional peer dependency supplied by your Cocos project.

Minimal wave spawner

import { instantiate } from 'cc';
import { WaveDirectorComponent } from 'miaoda-game-wave-cocos';

const spawner = level.addComponent(WaveDirectorComponent)
  .registerSpawnPoint('left', leftMarker)
  .onSpawn((type, point) => {
    const enemy = instantiate(enemyPrefabs[type]);
    if (point) enemy.setWorldPosition(point.worldPosition);
    enemy.parent = enemyLayer;
    enemy.on('died', () => spawner.reportKilled());
  })
  .setupWaves({
    waves: [{ groups: [{ type: 'goblin', count: 5, interval: 0.5, spawnPointId: 'left' }] }],
  })
  .start();

Register every referenced spawn point before start(). An unknown or omitted ID produces undefined, so the spawn handler must choose a fallback position if that is allowed.

Cocos update(dt) supplies seconds automatically. Use setTicking(false) to pause spawning without disabling the node. Call reportKilled yourself; the component cannot infer when a spawned entity dies.

For a game-owned fixed tick, select manual ownership while installing the current model:

spawner.setupWaves(config, { tickSource: 'manual' });

fixedStepper.advance(frameDeltaSeconds, ({ dt, index }) => {
  const from = pendingSpawns.length;
  spawner.stepSimulation(dt);
  commitSpawnBatch(index, pendingSpawns.slice(from));
});

The default source is host. Manual mode makes Component update(dt) inert and exposes only the seconds-based stepSimulation. Calling it in host mode fails before Core state or callbacks change. setTicking is a separate local pause. Synchronous spawn callbacks are grouped by the game around each manual call; the adapter does not introduce a second event bus or discard catch-up ticks.

Use setupWaves or setupDirector on a component, not both at once; the latest valid setup replaces the previous model and selects its tick source. Invalid config/source leaves the active model and source intact. Access waveRunner or spawnDirector snapshots for deterministic observation. onDestroy is terminal; create a new component with a restarted Scene instead of reusing it.

Public API

WaveDirectorComponent exposes setup, source selection, manual stepping, spawn-point registration, onSpawn, start, reportKilled, ticking control, and core getters. WaveComponentOptions and WaveTickSource are exported with the existing core classes/types. The adapter does not instantiate or pool enemies for you.