miaoda-game-kinematic2d-core

Use this engine-independent core when an actor needs swept AABB movement, collide-and-slide, floor detection, one-way platforms, moving-platform carry, or deterministic collision results. Coordinates use world units with +Y up; step receives seconds and a requested velocity, then returns the resolved position and contacts.

Install

pnpm add miaoda-game-kinematic2d-core

Minimal world and body

import { AabbKinematicWorld, KinematicBody2D } from 'miaoda-game-kinematic2d-core';

const world = new AabbKinematicWorld()
  .setBounds({ min: { x: -400, y: 0 }, max: { x: 400, y: 240 } }, { top: false })
  .addCollider({ id: 'floor', min: { x: -400, y: -16 }, max: { x: 400, y: 0 } });

const body = new KinematicBody2D(
  { shape: { halfWidth: 12, halfHeight: 20 }, snapDistance: 4 },
  { x: 0, y: 80 },
);
const frame = body.step(1 / 60, { x: 180, y: -30 }, world);
console.log(frame.position, frame.grounded, frame.collisions);

step(dtSeconds, requestedVelocity, world) moves the body, removes velocity into contacts, slides along surfaces, and reports wall, bumpedHead, groundNormal, and ordered collision records. The world does not apply gravity; calculate gravity or jump velocity in your game and pass the result in.

World authoring

AabbKinematicWorld supports static or moving axis-aligned colliders, collision categories/masks, one-way normals, and optional solid world sides. Implement KinematicWorld2D when your level uses polygons, capsules, or an existing physics query system. A custom world must return deterministic earliest hits for the same query.

Camera limits do not constrain bodies. Configure movement bounds in the collision world separately from camera bounds.

Saving and composition

const saved = body.snapshot;
// Store as part of your save game.
body.restore(saved);

Snapshots are detached JSON-safe state. Restore into a body with the same movement configuration and a world containing the referenced ground collider. Invalid snapshots are rejected without changing the live body.

For a platformer, let miaoda-game-platformer-core calculate gravity, jump feel, and intent, then pass its returned { vx, vy } to this body. Use one owner for position integration; do not move the same object through a second physics controller.

Public API

KinematicBody2D, AabbKinematicWorld, KinematicWorld2D, KinematicBodyConfig, KinematicStepResult, KinematicCollider, and Vec2 are the main entry points. The core does not render sprites, read input, or choose game-specific abilities.