miaoda-game-platformer-phaser

Use this Phaser 4 adapter to connect miaoda-game-platformer-core to an Arcade-compatible body or a custom velocity applier. The core uses +Y up; the adapter converts vertical velocity for Phaser's +Y-down objects. This is the Arcade-compatible alternative. Do not stack it with miaoda-game-platformer-kinematic-phaser; choose exactly one movement path for an actor.

Install

pnpm add miaoda-game-platformer-phaser miaoda-game-platformer-core

Phaser >=4 <5 is required.

Minimal controller

const controller = scene.platformers.create(player.body, {
  jumpSpeed: 520,
  coyoteTime: 0.1,
  jumpBufferTime: 0.12,
})
  .setInput(() => ({
    moveX: cursors.left.isDown ? -1 : cursors.right.isDown ? 1 : 0,
    jumpPressed: Phaser.Input.Keyboard.JustDown(jumpKey),
    jumpHeld: jumpKey.isDown,
  }))
  .setContacts(() => ({
    grounded: player.body.blocked.down,
    wall: player.body.blocked.left ? -1 : player.body.blocked.right ? 1 : 0,
    bumpedHead: player.body.blocked.up,
  }));

Phaser supplies milliseconds and the adapter converts them to core seconds. Existing autoUpdate: false plus update(deltaMs) integrations remain supported. For a new game-owned fixed-tick loop, prefer explicit gameplay ownership and the seconds boundary:

const controller = scene.platformers.create(
  player.body,
  { jumpSpeed: 520, coyoteTime: 0.1 },
  { tickSource: 'manual' },
).setInput(readLogicalInput).setContacts(readCommittedContacts);

fixedStepper.advance(frameSeconds, (dt) => {
  const gameplay = controller.stepSimulation(dt);
  // Then run the configured Arcade/Matter physics substeps and commit contacts.
});

The default tickSource: 'host' preserves Scene-driven behavior. autoUpdate is a legacy alias; if both options are supplied they must agree. Manual controllers do not register update but retain shutdown cleanup. Calling stepSimulation(dtSeconds) in host mode fails before input/contact providers, core state, body velocity, or snapshot listeners can change. setTicking remains a separate local pause. The same contract applies to createCommitted.

stepSimulation advances platformer gameplay and applies the resulting velocity; it does not step Arcade or Matter. A strict external-physics coordinator should read contact facts committed at the tick boundary, run this gameplay step, execute its configured 1..N physics substeps, capture contacts, and commit one stable contact batch. Do not also leave the Scene physics world on an uncoordinated automatic clock.

Use createCommitted/CommittedPlatformerController for locked-air-control movement and action constraints. Use setVelocityApplier for a deliberately custom integration. For the supported deterministic swept-AABB path, use miaoda-game-platformer-kinematic-phaser rather than connecting this velocity adapter to a second position-owning controller. Do not apply Arcade/Matter movement a second time to the same object.

Public API

PlatformerController, CommittedPlatformerController, PlatformerPlugin, PlatformerControllerOptions, PlatformerTickSource, their input/contact providers, and all core types are exported. Subscribe to snapshots for animation and effects; this package does not resolve custom collision shapes or own the engine physics clock.