miaoda-game-behavior-cocos

Use this Cocos Creator component to run miaoda-game-behavior-core trees on a node-backed AI entity. It reads the node's position and angle, asks your hooks for target and obstacle data, advances the tree in seconds, and applies steering movement to the node.

Install

pnpm add miaoda-game-behavior-cocos miaoda-game-behavior-core

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

Minimal guard

const ai = enemy.addComponent(BehaviorComponent);
ai.setup(
  `root { selector {
    sequence { condition [CanSeeTarget] action [MoveToTarget] }
    action [Patrol]
  } }`,
  { speed: 80, sightRange: 400, fovDeg: 70 },
  {
    target: () => player.worldPosition,
    obstacles: () => visionLayer.obstacles,
  },
  { Patrol: (agent) => patrol(agent) },
);

Cocos update(dt) supplies seconds automatically. setTicking(false) pauses the tree without clearing state; reset() starts the tree from its root. The default movement writes the node's X/Y position and sets Z to 0, so use it with 2D nodes or provide a movement arrangement appropriate for your scene.

For a game-owned fixed tick, choose manual ownership in the existing final options object:

ai.setup(tree, { speed: 80 }, hooks, custom, { tickSource: 'manual' });

fixedStepper.advance(frameDeltaSeconds, ({ dt }) => {
  ai.stepSimulation(dt);
});

The default tickSource: 'host' preserves Cocos lifecycle behavior. In manual mode, Component update(dt) is inert and stepSimulation(dtSeconds) is the only simulation entry. Calling the new entry on a host-owned component throws before the runner or Node changes. setTicking remains a separate local pause. Repeated setup replaces the runner and explicitly selects the new source; invalid replacement construction leaves the active runner and its dt binding unchanged. Destruction is terminal: later setup or stepSimulation calls throw with a repair message.

When collision, a character controller, or another simulation owns position, provide applyPosition. Built-in movement then submits its next-position request only through that hook and does not also write the Node:

const hooks = {
  target: () => player.worldPosition,
  applyPosition: (next) => character.moveToward(next),
};

Return the same obstacle collection used by miaoda-game-vision2d-core or its Cocos rendering layer. For navigation, supply findPath; for collision ownership, supply applyPosition. Sight obstacles, navigation terrain, and physical collision remain explicit host concerns.

The final optional setup argument extends BehaviorRunnerOptions with tickSource; use the same object for deterministic RNG and bounded diagnostics. The adapter strips tickSource before constructing core. Read snapshots and traces through component.runner. The component does not duplicate or mutate core diagnostic state.

Public API

BehaviorComponent, BehaviorHooks, BehaviorComponentOptions, BehaviorTickSource, BehaviorRunner, State, and core behavior types are exported. Custom functions receive the agent as their first argument. The component does not instantiate targets, query physics, or implement attacks.