miaoda-game-platformer-cocos

Use these Cocos Creator components to connect miaoda-game-platformer-core to a player node. The adapter reads input and collision facts from providers, advances the core in seconds, and applies the returned +Y-up velocity.

Install

pnpm add miaoda-game-platformer-cocos miaoda-game-platformer-core

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

Minimal controller

const controller = player.addComponent(PlatformerController);
controller
  .setup({ jumpSpeed: 720, extraJumps: 1, dashSpeed: 900 })
  .setInput(() => ({ moveX: axisX(), jumpPressed: jumpEdge(), jumpHeld: jumpDown() }))
  .setContact(() => ({ grounded: raycastDown(), wall: raycastWall(), bumpedHead: hitCeiling() }))
  .onSnapshot((frame) => animator.play(frame.state));

The default applier integrates the Cocos node position and is the simple core-owned-position path. Use setVelocityApplier when a Cocos rigid body owns integration. Existing direct step(dt) integrations remain supported. For a new game-owned fixed-tick loop, select manual gameplay ownership:

controller.setup(
  { jumpSpeed: 720, extraJumps: 1 },
  { tickSource: 'manual' },
);

fixedStepper.advance(frameSeconds, (dt) => {
  const gameplay = controller.stepSimulation(dt);
  // With a RigidBody applier, next run physics substeps and commit contacts.
});

The default tickSource: 'host' preserves Component lifecycle behavior. In manual mode, update(dt) is inert and stepSimulation(dtSeconds) is the guarded gameplay entry. Calling it in host mode fails before input/contact providers, core state, Node/body velocity, or snapshot listeners can change. setTicking is a separate local pause. Invalid setup options are rejected before the live body or source changes. The same contract applies to CommittedPlatformerController.

With the default applier, the manual call also integrates the Node and no physics engine is involved. With a RigidBody applier, it only applies velocity and does not step Cocos Physics. A strict external-physics composition should read committed contacts, run the gameplay step, execute its configured 1..N physics substeps, capture contacts, and commit one stable batch.

CommittedPlatformerController is available for locked-air-control/action-constraint movement. Both controllers require input and contact providers before they produce a frame.

Public API

PlatformerController, CommittedPlatformerController, PlatformerComponentOptions, PlatformerTickSource, their provider types, and all core configuration/snapshot types are exported. Use snapshot/onSnapshot for animation and effects; the component does not provide collision queries, a physics-world clock, or game-specific attacks.