@forgeax/engine-physics 0.0.0-dev.8d955ade1c79

package/src/__tests__/physics.unit.test.ts

@@ -0,0 +1,364 @@
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: scope isolation between merged source files
+//
+// Source files (N=2):
+//   - packages/physics/__tests__/component-schema.test.ts
+//   - packages/physics/__tests__/enum-helpers.test.ts
+//
+// Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
+// source as ancestorTitles[0]. Top-level imports merged + deduped.
+//
+// Note: merged from __tests__/ into src/__tests__/; import paths adjusted (../src/index → ../index).
+
+import { World } from '@forgeax/engine-ecs';
+import { componentDefinition, componentSchema } from '@forgeax/engine-ecs/internal';
+import { describe, expect, it } from 'vitest';
+import type { PhysicsErrorCode } from '../index';
+import {
+  COLLIDER_SHAPE_CAPSULE,
+  COLLIDER_SHAPE_CUBOID,
+  COLLIDER_SHAPE_SPHERE,
+  Collider,
+  ColliderShapeValue,
+  CollidingEntities,
+  CollisionEvent,
+  colliderShapeFromF32,
+  PHYSICS_ERROR_HINTS,
+  PhysicsError,
+  RIGID_BODY_TYPE_DYNAMIC,
+  RIGID_BODY_TYPE_KINEMATIC,
+  RIGID_BODY_TYPE_STATIC,
+  RigidBody,
+  RigidBodyTypeValue,
+  rigidBodyTypeFromF32,
+} from '../index';
+
+{
+  // ─── from component-schema.test.ts ───
+
+  describe('component-schema.test.ts', () => {
+    describe('feat-20260528 M1 t7 physics component schema definitions', () => {
+      it('RigidBody is a valid Component token with expected fields', () => {
+        expect(RigidBody).toBeDefined();
+        expect(RigidBody.name).toBe('RigidBody');
+        const schema = componentSchema(RigidBody);
+        expect(schema).toHaveProperty('type');
+        expect(schema).toHaveProperty('mass');
+        expect(schema).toHaveProperty('linearDamping');
+        expect(schema).toHaveProperty('angularDamping');
+        expect(schema).toHaveProperty('gravityScale');
+        expect(schema).toHaveProperty('ccdEnabled');
+      });
+
+      it('Collider is a valid Component token with expected fields', () => {
+        expect(Collider).toBeDefined();
+        expect(Collider.name).toBe('Collider');
+        const schema = componentSchema(Collider);
+        expect(schema).toHaveProperty('shape');
+        // feat-20260709 M4: cuboid half-extents collapsed from 3 per-axis
+        // scalar columns into one inline array<f32,3> column (halfExtents).
+        // radius / halfHeight stay scalar (OOS-1: independent sphere/capsule
+        // params, not part of the cuboid vec).
+        expect(schema).toHaveProperty('halfExtents');
+        expect(schema.halfExtents).toBe('array<f32, 3>');
+        expect('halfExtentsX' in schema).toBe(false);
+        expect('halfExtentsY' in schema).toBe(false);
+        expect('halfExtentsZ' in schema).toBe(false);
+        expect(schema).toHaveProperty('radius');
+        expect(schema).toHaveProperty('halfHeight');
+        expect(schema).toHaveProperty('friction');
+        expect(schema).toHaveProperty('restitution');
+        expect(schema).toHaveProperty('density');
+        expect(schema).toHaveProperty('isSensor');
+        expect(schema).toHaveProperty('collisionGroups');
+        expect(schema).toHaveProperty('solverGroups');
+      });
+
+      it('CollidingEntities is a valid Component token with entities field', () => {
+        expect(CollidingEntities).toBeDefined();
+        expect(CollidingEntities.name).toBe('CollidingEntities');
+        const schema = componentSchema(CollidingEntities);
+        expect(schema).toHaveProperty('entities');
+      });
+
+      it('CollisionEvent is the expected constant value', () => {
+        expect(CollisionEvent).toBe('__CollisionEvent__');
+      });
+
+      it('PhysicsError is importable and constructable', () => {
+        const err = new PhysicsError({
+          code: 'backend-not-registered',
+          expected: 'PhysicsWorld resource to be registered',
+          hint: 'use createApp(canvas, { plugins: [physicsPlugin(...)] })',
+          detail: {
+            code: 'backend-not-registered',
+            attemptedBackend: 'rapier-3d',
+          },
+        });
+        expect(err.code).toBe('backend-not-registered');
+        expect(err.name).toBe('PhysicsError');
+        expect(err.hint).toContain('createApp');
+      });
+
+      it('PhysicsErrorCode literal union has all 8 members', () => {
+        const codes: Set<string> = new Set();
+        const all: PhysicsErrorCode[] = [
+          'wasm-load-failed',
+          'wasm-simd-unsupported',
+          'step-failed',
+          'invalid-body-config',
+          'body-not-found',
+          'collider-not-found',
+          'backend-not-registered',
+          'teleport-invalid-body-type',
+        ];
+        for (const c of all) {
+          codes.add(c);
+        }
+        expect(codes.size).toBe(8);
+      });
+
+      it('PHYSICS_ERROR_HINTS has all 8 code entries', () => {
+        const allCodes: PhysicsErrorCode[] = [
+          'wasm-load-failed',
+          'wasm-simd-unsupported',
+          'step-failed',
+          'invalid-body-config',
+          'body-not-found',
+          'collider-not-found',
+          'backend-not-registered',
+          'teleport-invalid-body-type',
+        ];
+        for (const code of allCodes) {
+          expect(PHYSICS_ERROR_HINTS[code]).toBeDefined();
+          expect(PHYSICS_ERROR_HINTS[code].length).toBeGreaterThan(0);
+        }
+      });
+
+      it('RigidBodyType literal union has 3 discriminants', () => {
+        const types = ['static', 'dynamic', 'kinematic'] as const;
+        expect(new Set(types).size).toBe(3);
+      });
+
+      it('ColliderShape literal union has 3 discriminants', () => {
+        const shapes = ['cuboid', 'sphere', 'capsule'] as const;
+        expect(new Set(shapes).size).toBe(3);
+      });
+
+      // solo round-24 (P7 residue): the enum fields project their label→value
+      // map through FieldReflection, sourced from the SAME `*Value` const map
+      // (Derive, don't Duplicate). This is what the editor's describeComponent
+      // surfaces so a docs-only AI learns static=0/dynamic=1/kinematic=2 without
+      // reading engine source. Revert-to-red: drop `labels:` from the descriptor.
+      it('RigidBody.type reflects labels === RigidBodyTypeValue', () => {
+        const reflection = RigidBody.fields.type as { readonly labels?: Record<string, number> };
+        expect(reflection.labels).toEqual({ ...RigidBodyTypeValue });
+        expect(reflection.labels).toEqual({ static: 0, dynamic: 1, kinematic: 2 });
+      });
+
+      it('Collider.shape reflects labels === ColliderShapeValue', () => {
+        const reflection = Collider.fields.shape as { readonly labels?: Record<string, number> };
+        expect(reflection.labels).toEqual({ ...ColliderShapeValue });
+        expect(reflection.labels).toEqual({ cuboid: 0, sphere: 1, capsule: 2 });
+      });
+
+      it('a non-enum field (RigidBody.mass) reflects no labels (control)', () => {
+        const reflection = RigidBody.fields.mass as { readonly labels?: Record<string, number> };
+        expect(reflection.labels).toBeUndefined();
+      });
+    });
+  });
+}
+
+{
+  // ─── from enum-helpers.test.ts ───
+
+  describe('enum-helpers.test.ts', () => {
+    describe('rigidBodyTypeFromF32', () => {
+      it('0 maps to static', () => {
+        expect(rigidBodyTypeFromF32(0)).toBe('static');
+      });
+
+      it('1 maps to dynamic', () => {
+        expect(rigidBodyTypeFromF32(1)).toBe('dynamic');
+      });
+
+      it('2 maps to kinematic', () => {
+        expect(rigidBodyTypeFromF32(2)).toBe('kinematic');
+      });
+
+      it('out-of-range values fall back to static', () => {
+        expect(rigidBodyTypeFromF32(-1)).toBe('static');
+        expect(rigidBodyTypeFromF32(3)).toBe('static');
+        expect(rigidBodyTypeFromF32(99)).toBe('static');
+      });
+
+      it('fractional values fall back to static', () => {
+        expect(rigidBodyTypeFromF32(0.5)).toBe('static');
+        expect(rigidBodyTypeFromF32(1.5)).toBe('static');
+        expect(rigidBodyTypeFromF32(2.9)).toBe('static');
+      });
+    });
+
+    describe('colliderShapeFromF32', () => {
+      it('0 maps to cuboid', () => {
+        expect(colliderShapeFromF32(0)).toBe('cuboid');
+      });
+
+      it('1 maps to sphere', () => {
+        expect(colliderShapeFromF32(1)).toBe('sphere');
+      });
+
+      it('2 maps to capsule', () => {
+        expect(colliderShapeFromF32(2)).toBe('capsule');
+      });
+
+      it('out-of-range values fall back to cuboid', () => {
+        expect(colliderShapeFromF32(-1)).toBe('cuboid');
+        expect(colliderShapeFromF32(3)).toBe('cuboid');
+        expect(colliderShapeFromF32(99)).toBe('cuboid');
+      });
+
+      it('fractional values fall back to cuboid', () => {
+        expect(colliderShapeFromF32(0.5)).toBe('cuboid');
+        expect(colliderShapeFromF32(1.5)).toBe('cuboid');
+        expect(colliderShapeFromF32(2.9)).toBe('cuboid');
+      });
+    });
+
+    describe('numeric enum constants', () => {
+      it('RigidBodyTypeValue has expected numeric values', () => {
+        expect(RigidBodyTypeValue.static).toBe(0);
+        expect(RigidBodyTypeValue.dynamic).toBe(1);
+        expect(RigidBodyTypeValue.kinematic).toBe(2);
+      });
+
+      it('ColliderShapeValue has expected numeric values', () => {
+        expect(ColliderShapeValue.cuboid).toBe(0);
+        expect(ColliderShapeValue.sphere).toBe(1);
+        expect(ColliderShapeValue.capsule).toBe(2);
+      });
+
+      it('individual RigidBody constants match RigidBodyTypeValue', () => {
+        expect(RIGID_BODY_TYPE_STATIC).toBe(0);
+        expect(RIGID_BODY_TYPE_DYNAMIC).toBe(1);
+        expect(RIGID_BODY_TYPE_KINEMATIC).toBe(2);
+      });
+
+      it('individual ColliderShape constants match ColliderShapeValue', () => {
+        expect(COLLIDER_SHAPE_CUBOID).toBe(0);
+        expect(COLLIDER_SHAPE_SPHERE).toBe(1);
+        expect(COLLIDER_SHAPE_CAPSULE).toBe(2);
+      });
+    });
+
+    describe('layer-2 defaults (m3-1e regression)', () => {
+      it('RigidBody defaults include gravityScale=1', () => {
+        expect(componentSchema(RigidBody)).toHaveProperty('gravityScale');
+        const defaults = componentDefinition(RigidBody).defaults;
+        expect(defaults).toBeDefined();
+        if (defaults) {
+          expect(defaults.gravityScale).toBe(1);
+        }
+      });
+
+      it('RigidBody defaults include mass=1', () => {
+        const defaults = componentDefinition(RigidBody).defaults;
+        expect(defaults).toBeDefined();
+        if (defaults) {
+          expect(defaults.mass).toBe(1);
+        }
+      });
+
+      it('RigidBody defaults include type=dynamic (1)', () => {
+        const defaults = componentDefinition(RigidBody).defaults;
+        expect(defaults).toBeDefined();
+        if (defaults) {
+          expect(defaults.type).toBe(1);
+        }
+      });
+
+      it('Collider defaults include density=1', () => {
+        expect(componentSchema(Collider)).toHaveProperty('density');
+        const defaults = componentDefinition(Collider).defaults;
+        expect(defaults).toBeDefined();
+        if (defaults) {
+          expect(defaults.density).toBe(1);
+        }
+      });
+
+      it('Collider defaults include friction=0.5', () => {
+        const defaults = componentDefinition(Collider).defaults;
+        expect(defaults).toBeDefined();
+        if (defaults) {
+          expect(defaults.friction).toBe(0.5);
+        }
+      });
+
+      it('Collider defaults include restitution=0', () => {
+        const defaults = componentDefinition(Collider).defaults;
+        expect(defaults).toBeDefined();
+        if (defaults) {
+          expect(defaults.restitution).toBe(0);
+        }
+      });
+    });
+  });
+}
+
+{
+  // ─── feat-20260709 M4 / w17: Collider halfExtents vec-collapse ───
+  //
+  // AC-01 / E1 / AC-04: halfExtents is array<f32,3> with explicit layer-2
+  // default [0.5,0.5,0.5] (the array layer-3 fallback is all-zero, so the
+  // non-zero default MUST be declared explicitly). Spawn-omit resolves to the
+  // same value the old per-axis scalar defaults produced. radius/halfHeight
+  // stay scalar (OOS-1). TDD red until w19 lands the schema collapse.
+
+  describe('collider-halfextents-vec.test.ts', () => {
+    it('Collider.halfExtents is array<f32,3> with explicit layer-2 default [0.5,0.5,0.5]', () => {
+      expect(componentSchema(Collider).halfExtents).toBe('array<f32, 3>');
+      expect(Array.from(Collider.fields.halfExtents.default as Float32Array)).toEqual([
+        0.5, 0.5, 0.5,
+      ]);
+    });
+
+    it('Collider per-axis scalar keys are gone; radius/halfHeight stay scalar (OOS-1)', () => {
+      expect('halfExtentsX' in componentSchema(Collider)).toBe(false);
+      expect('halfExtentsY' in componentSchema(Collider)).toBe(false);
+      expect('halfExtentsZ' in componentSchema(Collider)).toBe(false);
+      expect(componentSchema(Collider).radius).toBe('f32');
+      expect(componentSchema(Collider).halfHeight).toBe('f32');
+    });
+
+    it('E1: Collider spawned with halfExtents omitted resolves to [0.5,0.5,0.5]', () => {
+      const world = new World();
+      const e = world
+        .spawn({ component: Collider, data: { shape: ColliderShapeValue.cuboid } })
+        .unwrap();
+      const row = world.get(e, Collider).unwrap();
+      expect(Array.from(row.halfExtents)).toEqual([0.5, 0.5, 0.5]);
+    });
+
+    it('E1: Collider spawned with explicit halfExtents carries the array through', () => {
+      const world = new World();
+      const e = world
+        .spawn({
+          component: Collider,
+          data: { shape: ColliderShapeValue.cuboid, halfExtents: [1, 2, 3] },
+        })
+        .unwrap();
+      const row = world.get(e, Collider).unwrap();
+      expect(Array.from(row.halfExtents)).toEqual([1, 2, 3]);
+    });
+
+    it('AC-04: residual halfExtentsX at a spawn call-site is a compile error', () => {
+      const world = new World();
+      world.spawn({
+        component: Collider,
+        // @ts-expect-error halfExtentsX/Y/Z were collapsed into the halfExtents array.
+        data: { shape: ColliderShapeValue.cuboid, halfExtents: [1, 1, 1], halfExtentsX: 1 },
+      });
+    });
+  });
+}

package/src/collision-event.ts

@@ -0,0 +1,35 @@
+// @forgeax/engine-physics — CollisionEvent ECS Event token placeholder.
+//
+// Emitted by physics tick systems during the Writeback phase.
+// Two states only: 'started' (new contact) and 'stopped' (separated).
+// No 'continued' event — use CollidingEntities component for ongoing contacts
+// (plan-strategy D-3).
+
+import type { Vec3 } from '@forgeax/engine-math';
+
+/**
+ * Collision event payload — per-contact-pair event emitted during Writeback.
+ *
+ * `type: 'started'` — two colliders just began touching.
+ * `type: 'stopped'` — two colliders just separated.
+ */
+export interface CollisionEventPayload {
+  type: 'started' | 'stopped';
+  entityA: number;
+  entityB: number;
+  contactPoint: Vec3;
+  contactNormal: Vec3;
+}
+
+/**
+ * CollisionEvent constant — identifies the collision event type.
+ * Backend systems push CollisionEventPayload instances into the event queue
+ * during the Writeback phase; user systems drain via query.
+ *
+ * The backing ECS event infrastructure (Event<T> generic + world.drainEvent)
+ * is deferred to a future feat. For M1, this is a type-only contract.
+ */
+export const CollisionEvent = '__CollisionEvent__' as const;
+
+/** Type-level identifier for the CollisionEvent event channel. */
+export type CollisionEvent = typeof CollisionEvent;

package/src/components.ts

@@ -0,0 +1,225 @@
+// @forgeax/engine-physics — ECS Component schemas.
+//
+// RigidBody and Collider are the two user-facing entry points; AI users
+// spawn entities with these components to opt into physics simulation.
+// CollidingEntities is the runtime set-query component for continuous
+// collision status (started/stopped model, no 'continued' event).
+
+import { type Component, defineComponent, type World } from '@forgeax/engine-ecs';
+
+/**
+ * RigidBody motion type — 3-state discriminant mirroring Rapier's
+ * Dynamic / Fixed / KinematicPositionBased triplet.
+ *
+ * `'static'`: infinite mass, never moves (Rapier Fixed).
+ * `'dynamic'`: driven by forces, gravity, collisions (Rapier Dynamic).
+ * `'kinematic'`: user-controlled position, velocity derived by engine
+ *                (Rapier KinematicPositionBased).
+ */
+export type RigidBodyType = 'static' | 'dynamic' | 'kinematic';
+
+/**
+ * Collider shape discriminant — 3 AI-friendly shape names.
+ *
+ * `'cuboid'`: box shape defined by half-extents (x, y, z).
+ * `'sphere'`: sphere defined by radius.
+ * `'capsule'`: capsule defined by half-height + radius.
+ *
+ * Named `'sphere'` not `'ball'` per plan-strategy D-5: AI users see
+ * the familiar geometric term; backend maps to Rapier `ColliderDesc.ball()`.
+ */
+export type ColliderShape = 'cuboid' | 'sphere' | 'capsule';
+
+// ─── D-3: numeric enum constants + narrowing helpers ─────────────────────
+//
+// Aligned with `packages/runtime/src/components/camera.ts:41-53`
+// `cameraProjectionFromF32` pattern. The ECS `enum` field maps to `number`
+// (Uint32Array column); these constants let AI users write
+// `{ type: RigidBodyTypeValue.dynamic }` instead of bare magic numbers,
+// and the narrowing helpers let backends switch cleanly on the string union.
+//
+// Declared BEFORE the RigidBody / Collider components so each component's enum
+// field descriptor can reference the SAME `*Value` map as its `labels`
+// (Derive, don't Duplicate — one object is both the AI-facing const AND the
+// schema-projected label map that `describeComponent` surfaces).
+
+/** Numeric value for static rigid body (Rapier Fixed). */
+export const RIGID_BODY_TYPE_STATIC = 0;
+/** Numeric value for dynamic rigid body (Rapier Dynamic). */
+export const RIGID_BODY_TYPE_DYNAMIC = 1;
+/** Numeric value for kinematic rigid body (Rapier KinematicPositionBased). */
+export const RIGID_BODY_TYPE_KINEMATIC = 2;
+
+export const RigidBodyTypeValue = {
+  static: RIGID_BODY_TYPE_STATIC,
+  dynamic: RIGID_BODY_TYPE_DYNAMIC,
+  kinematic: RIGID_BODY_TYPE_KINEMATIC,
+} as const;
+
+export function rigidBodyTypeFromF32(n: number): RigidBodyType {
+  if (n === RIGID_BODY_TYPE_DYNAMIC) return 'dynamic';
+  if (n === RIGID_BODY_TYPE_KINEMATIC) return 'kinematic';
+  return 'static';
+}
+
+/** Numeric value for cuboid collider shape. */
+export const COLLIDER_SHAPE_CUBOID = 0;
+/** Numeric value for sphere collider shape. */
+export const COLLIDER_SHAPE_SPHERE = 1;
+/** Numeric value for capsule collider shape. */
+export const COLLIDER_SHAPE_CAPSULE = 2;
+
+export const ColliderShapeValue = {
+  cuboid: COLLIDER_SHAPE_CUBOID,
+  sphere: COLLIDER_SHAPE_SPHERE,
+  capsule: COLLIDER_SHAPE_CAPSULE,
+} as const;
+
+export function colliderShapeFromF32(n: number): ColliderShape {
+  if (n === COLLIDER_SHAPE_SPHERE) return 'sphere';
+  if (n === COLLIDER_SHAPE_CAPSULE) return 'capsule';
+  return 'cuboid';
+}
+
+/**
+ * ECS Component: rigid body physics properties.
+ *
+ * AI user entry point — spawn with `world.spawn(RigidBody({ type: 'dynamic' }))`
+ * to opt an entity into physics simulation.
+ *
+ * | Field | Type | Default | Purpose |
+ * |:--|:--|:--|:--|
+ * | `type` | `RigidBodyType` | `'dynamic'` | Motion type discriminant |
+ * | `mass` | `number` | `1.0` | Linear mass (> 0 for dynamic) |
+ * | `linearDamping` | `number` | `0.0` | Velocity damping factor [0, 1] |
+ * | `angularDamping` | `number` | `0.0` | Angular velocity damping [0, 1] |
+ * | `gravityScale` | `number` | `1.0` | Per-body gravity multiplier |
+ * | `ccdEnabled` | `boolean` | `false` | Continuous collision detection |
+ *
+ * `type` declares `labels: RigidBodyTypeValue` so `describeComponent` projects
+ * the `static=0 / dynamic=1 / kinematic=2` map through the front door — an AI
+ * learns the legal variants from the schema, not from engine source.
+ */
+export const RigidBody = defineComponent('RigidBody', {
+  type: { type: 'enum', default: RIGID_BODY_TYPE_DYNAMIC, labels: RigidBodyTypeValue },
+  mass: { type: 'f32', default: 1 },
+  linearDamping: { type: 'f32', default: 0 },
+  angularDamping: { type: 'f32', default: 0 },
+  gravityScale: { type: 'f32', default: 1 },
+  ccdEnabled: { type: 'bool', default: false },
+});
+
+/**
+ * ECS Component: collision geometry.
+ *
+ * Spawn alongside RigidBody to give an entity a collision shape. Entities
+ * with Collider but no RigidBody are treated as static colliders (Rapier
+ * native behavior — collider without parent body is fixed): `physicsSyncBackend`
+ * synthesizes an implicit static body for them, so a bare-Collider floor/wall is
+ * simulated as immovable level geometry — the natural way to author static
+ * scenery without a redundant `RigidBody{static}`.
+ *
+ * | Field | Type | Default | Purpose |
+ * |:--|:--|:--|:--|
+ * | `shape` | `ColliderShape` | — | Shape discriminant |
+ * | `halfExtents` | `[number, number, number]` | `[0.5, 0.5, 0.5]` | Cuboid half-width/height/depth |
+ * | `radius` | `number` | `0.5` | Sphere / capsule radius |
+ * | `halfHeight` | `number` | `0.5` | Capsule half-height |
+ * | `friction` | `number` | `0.5` | Coulomb friction coefficient |
+ * | `restitution` | `number` | `0.0` | Elasticity (1.0 = perfect bounce) |
+ * | `density` | `number` | `1.0` | Mass density (alternative to mass) |
+ * | `isSensor` | `bool` | `false` | Sensor mode (detect, no physical response) |
+ * | `collisionGroups` | `u32` | `0x0001_FFFF` | 32-bit packed membership/filter |
+ * | `solverGroups` | `u32` | `0xFFFF_FFFF` | 32-bit packed constraint groups |
+ */
+export const Collider = defineComponent('Collider', {
+  shape: { type: 'enum', default: COLLIDER_SHAPE_CUBOID, labels: ColliderShapeValue },
+  // feat-20260709 M4: cuboid half-extents collapsed from 3 per-axis scalar
+  // columns into one inline array<f32,3> column. Explicit layer-2 default
+  // (the array layer-3 fallback is all-zero, which would give a degenerate
+  // zero-size box). radius/halfHeight stay scalar (OOS-1: independent
+  // sphere/capsule params, not part of the cuboid vec).
+  halfExtents: { type: 'array<f32, 3>', default: new Float32Array([0.5, 0.5, 0.5]) },
+  radius: { type: 'f32', default: 0.5 },
+  halfHeight: { type: 'f32', default: 0.5 },
+  friction: { type: 'f32', default: 0.5 },
+  restitution: { type: 'f32', default: 0 },
+  density: { type: 'f32', default: 1 },
+  isSensor: { type: 'bool', default: false },
+  collisionGroups: { type: 'u32', default: 0x0001_ffff },
+  solverGroups: { type: 'u32', default: 0xffff_ffff },
+});
+
+/**
+ * ECS Component: kinematic character controller tuning + output state.
+ *
+ * Spawn alongside a `RigidBody({ type: 'kinematic' })` + `Collider` to opt an
+ * entity into collision-aware movement via `PhysicsWorld.moveAndSlide`. The
+ * tuning fields are stable character properties; `grounded` is written back by
+ * the engine after each `moveAndSlide` (game code reads it, never writes it).
+ *
+ * All fields are flat scalars in engine units (degrees, world-space distance) —
+ * no Rapier types leak through. Slope angles use the `Deg` suffix to make the
+ * unit explicit; the backend translates degrees to radians. A single field
+ * carries both the on/off switch and the value: `autoStepMaxHeight === 0`
+ * disables auto-step, `snapToGroundDist === 0` disables snap-to-ground.
+ *
+ * 2D and 3D reuse this same component (plan-strategy D-9): every field is a
+ * dimension-agnostic scalar, so no separate 2D component is needed.
+ *
+ * | Field | Type | Default | Purpose |
+ * |:--|:--|:--|:--|
+ * | `offset` | `f32` | `0.01` | Skin thickness, prevents penetration |
+ * | `maxSlopeClimbDeg` | `f32` | `45` | Max climbable slope angle (degrees) |
+ * | `minSlopeSlideDeg` | `f32` | `30` | Slope angle past which sliding starts (degrees) |
+ * | `autoStepMaxHeight` | `f32` | `0.3` | Max auto-step height (0 = off) |
+ * | `autoStepMinWidth` | `f32` | `0.2` | Min step width to be steppable |
+ * | `snapToGroundDist` | `f32` | `0.2` | Downhill ground-snap distance (0 = off) |
+ * | `grounded` | `bool` | `false` | Engine-written: grounded after last move |
+ */
+export const CharacterController = defineComponent('CharacterController', {
+  offset: { type: 'f32', default: 0.01 },
+  maxSlopeClimbDeg: { type: 'f32', default: 45 },
+  minSlopeSlideDeg: { type: 'f32', default: 30 },
+  autoStepMaxHeight: { type: 'f32', default: 0.3 },
+  autoStepMinWidth: { type: 'f32', default: 0.2 },
+  snapToGroundDist: { type: 'f32', default: 0.2 },
+  grounded: { type: 'bool', default: false, transient: true },
+});
+
+/**
+ * ECS Component: set of entities currently colliding with the holder entity.
+ *
+ * Maintained by the physics tick systems — entities are added on collision
+ * start (`CollisionEvent.started`) and removed on collision stop
+ * (`CollisionEvent.stopped`). AI users query this component to know whose
+ * colliders overlap right now without consuming per-frame events.
+ *
+ * This is the `'continued'` equivalent — no repeated per-frame events,
+ * one component query per frame exposes the full active contact set
+ * (plan-strategy D-3: CollidingEntities set-query mode).
+ */
+export const CollidingEntities = defineComponent(
+  'CollidingEntities',
+  {
+    entities: { type: 'array<entity>' },
+  },
+  { transient: true },
+);
+
+const PHYSICS_COMPONENTS: readonly Component[] = [
+  CharacterController,
+  Collider,
+  CollidingEntities,
+  RigidBody,
+];
+
+/** Install the physics component vocabulary in a World and release its leases on teardown. */
+export function registerPhysicsComponents(world: World): () => void {
+  const leases = PHYSICS_COMPONENTS.map((component) =>
+    world.components.register(component).unwrap(),
+  );
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}

package/src/errors.ts

@@ -0,0 +1,10 @@
+// @forgeax/engine-physics — PhysicsError wrapper + re-exports from engine-types.
+//
+// PhysicsError, PhysicsErrorCode, PhysicsErrorDetail, and PHYSICS_ERROR_HINTS
+// are registered in @forgeax/engine-types (SSOT, parallel to AssetError /
+// AudioError / GltfError). This module re-exports them under the physics
+// package namespace so AI users import from `@forgeax/engine-physics` without
+// tracing to engine-types.
+
+export type { PhysicsErrorCode, PhysicsErrorDetail } from '@forgeax/engine-types';
+export { PHYSICS_ERROR_HINTS, PhysicsError } from '@forgeax/engine-types';

package/src/index.ts

@@ -0,0 +1,36 @@
+// @forgeax/engine-physics — physics interface package barrel.
+//
+// ECS component schemas (RigidBody / Collider / CollisionEvent),
+// PhysicsWorld Resource interface, PhysicsErrorCode union.
+//
+// Dependencies: @forgeax/engine-ecs (Component / event token),
+// @forgeax/engine-math (Vec2 / Vec3 / Quat),
+// @forgeax/engine-types (type utilities).
+
+export type { CollisionEventPayload } from './collision-event';
+export { CollisionEvent } from './collision-event';
+export type { ColliderShape, RigidBodyType } from './components';
+export {
+  CharacterController,
+  COLLIDER_SHAPE_CAPSULE,
+  COLLIDER_SHAPE_CUBOID,
+  COLLIDER_SHAPE_SPHERE,
+  Collider,
+  ColliderShapeValue,
+  CollidingEntities,
+  colliderShapeFromF32,
+  RIGID_BODY_TYPE_DYNAMIC,
+  RIGID_BODY_TYPE_KINEMATIC,
+  RIGID_BODY_TYPE_STATIC,
+  RigidBody,
+  RigidBodyTypeValue,
+  registerPhysicsComponents,
+  rigidBodyTypeFromF32,
+} from './components';
+export type { PhysicsErrorCode, PhysicsErrorDetail } from './errors';
+
+export { PHYSICS_ERROR_HINTS, PhysicsError } from './errors';
+export type { PhysicsWorld, PhysicsWorld2D, RaycastHit, RaycastHit2D } from './physics-world';
+export type { PhysicsBackend } from './plugin-factory';
+export { physicsPlugin } from './plugin-factory';
+export { PhysicsSet } from './system-set';

package/src/load-rapier-backend.d.mts

@@ -0,0 +1,2 @@
+export function loadRapier3DBackend(): Promise<unknown>;
+export function loadRapier2DBackend(): Promise<unknown>;

package/src/load-rapier-backend.mjs

@@ -0,0 +1,8 @@
+// Keep literal specifiers visible to bundlers without pulling backend declarations into the physics TypeScript graph.
+export function loadRapier3DBackend() {
+  return import('@forgeax/engine-physics-rapier3d');
+}
+
+export function loadRapier2DBackend() {
+  return import('@forgeax/engine-physics-rapier2d');
+}