miaoda-game-kinematic2d-phaser

Use this Phaser 4 controller to connect miaoda-game-kinematic2d-core to a Game Object. Core coordinates use +Y up; Phaser objects normally use +Y down, so configure the coordinate origin once and let the adapter convert positions.

Install

pnpm add miaoda-game-kinematic2d-phaser miaoda-game-kinematic2d-core

Phaser >=4 <5 is required.

Minimal controller

const coordinates = { yDown: true, origin: { x: 0, y: level.height } };
const controller = new KinematicController(
  scene.events, player, levelWorld,
  { shape: { halfWidth: 12, halfHeight: 20 }, snapDistance: 3 },
  coordinates,
).setVelocityProvider(() => ({ x: inputX * 220, y: verticalVelocity }));

Phaser update deltas are milliseconds. The controller converts them to seconds for core stepping and writes the converted position exactly once. Existing autoUpdate: false plus step(deltaMs, velocity) integrations remain supported.

For a new game-owned fixed-tick loop, prefer the explicit seconds boundary:

const controller = new KinematicController(
  scene.events,
  player,
  levelWorld,
  { shape: { halfWidth: 12, halfHeight: 20 } },
  { tickSource: 'manual', origin: { x: 0, y: level.height } },
);

fixedStepper.advance(frameSeconds, (dt) => {
  const result = controller.stepSimulation(dt, requestedVelocity);
  // Read result or controller.core.snapshot after this committed tick.
});

The default tickSource: 'host' preserves Scene-driven behavior. autoUpdate is a legacy alias; when both fields are supplied they must agree. Manual controllers do not register Scene update but retain shutdown cleanup. Calling stepSimulation in host mode fails before providers, collision, core state, or Game Object position can change. setTicking is a separate local pause.

Configure collision bounds and authored platforms in core coordinates, or use the exported coordinate helpers to convert Phaser rectangles. Camera bounds only affect scrolling and do not replace movement bounds. For screen-authored levels, PhaserKinematicWorld requires all four edge policies (solid, open, or exit) and reports fully escaped configured exit edges. Use placeAtPhaserCenter or placeFeetAtPhaser for validated atomic placement instead of hand-written origin and half-height arithmetic.

For a platformer that also uses platformer-core, prefer miaoda-game-platformer-kinematic-phaser; it owns the ordered two-core tick, contact feedback, world exits, and duplicate-physics diagnostics.

Do not also enable Arcade or Matter movement on the same object: the kinematic controller must remain the position authority. Construction detects an enabled object.body and throws DUPLICATE_PHYSICS_AUTHORITY before listener registration. allowEngineBody: true is an advanced escape hatch only for a body whose integration an external coordinator has disabled.

Public API

KinematicController, Kinematic2dPlugin, PhaserKinematicWorld, placement helpers, coordinate helpers, KinematicTickSource, KinematicAuthorityError, and core collision types are exported. The preset fixed-step path is tickSource: 'manual' plus stepSimulation(dtSeconds, velocity). Use update or legacy step(deltaMs, velocity) only for lower-level or compatibility integrations.