miaoda-game-platformer-core

Use this engine-independent package for platformer movement feel: acceleration, variable jump height, coyote time, jump buffering, apex hang, wall slide/jump, extra jumps, and dash. It never queries collisions or moves a body. Your engine supplies input and contact facts; the core returns velocity and animation flags.

Coordinates use +Y up and time is measured in seconds.

Install

pnpm add miaoda-game-platformer-core

Modern movement

import { PlatformerBody } from 'miaoda-game-platformer-core';

const body = new PlatformerBody({
  maxSpeed: 240,
  jumpSpeed: 620,
  coyoteTime: 0.1,
  jumpBufferTime: 0.12,
  extraJumps: 1,
  dashSpeed: 700,
  dashDuration: 0.15,
});

const frame = body.step(1 / 60,
  { moveX: inputX, jumpPressed, jumpHeld, dashPressed },
  { grounded, wall, bumpedHead },
);
applyVelocity(frame.vx, frame.vy);
animate(frame.state, frame.facing);

jumpPressed and dashPressed are edge-triggered; jumpHeld controls variable height. GroundContact is the result of your raycasts or physics contacts (wall is -1, 0, or 1). The returned snapshot includes jumped, wallJumped, dashed, dashing, and grounded for effects and UI.

Committed movement

Use CommittedPlatformerBody when airborne horizontal control should be locked or action constraints must preserve/stop movement. It uses the same +Y-up, seconds-based step API and adds applyImpulse(x, y, { lockControlUntilGrounded: true }) for knockback or scripted launches.

Game loop boundary

The core owns movement rules, not collision resolution or position integration. Apply returned velocity through your physics body or pass it to miaoda-game-kinematic2d-core for deterministic swept AABB movement. Use one fixed-tick owner and do not also apply a second gravity or movement model.

Public API

PlatformerBody, CommittedPlatformerBody, PlatformerConfig, PlatformerInput, GroundContact, PlatformerSnapshot, and committed-movement types are exported. The core does not render, read devices, or choose animation assets.