@sakia/physics

Optional 2D rigid-body physics for Sakia scene-graph nodes (TransformNode). First backend: Planck.js (planck npm package).

CAD documents / pickers are out of scope — see ADR-024 and PHYSICS_SYSTEM_PLAN.md.

Install

yarn workspace @sakia/physics add # already in monorepo
# peer: @sakia/core

Quick start

import { Vec2 } from "@sakia/core";
import {
  enablePhysics,
  PlanckPlugin,
  PhysicsAggregate,
  PhysicsShapeType,
  PhysicsMotionType,
} from "@sakia/physics";

enablePhysics(scene, new Vec2(0, 10), new PlanckPlugin());

new PhysicsAggregate(ground, PhysicsShapeType.Box, {
  motionType: PhysicsMotionType.Static,
  width: 20,
  height: 1,
}, scene);

new PhysicsAggregate(ball, PhysicsShapeType.Circle, {
  mass: 1,
  radius: 0.5,
}, scene);

Use Continuous render mode so PhysicsSystem can step each frame.

Public surface

| API | Role | |-----|------| | enablePhysics / disablePhysics / getPhysicsEngine | Scene bind | | PlanckPlugin | First backend | | PhysicsBody / PhysicsShape / PhysicsAggregate | Facades | | PhysicsSystem | ISceneComponent steeper | | PhysicsRaycastResult | Raycast hit | | Collision Observables on PhysicsSystem | begin / end |

Planck types are not re-exported.

Note: planck lists an optional stage-js peer (testbed only). It is not required for @sakia/physics. Root .yarnrc sets --ignore-engines true because newer planck releases may declare engines.node >= 24 while the repo still builds on Node 22; this package pins [email protected].