@ignifx/physics-2d 0.0.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,3881 @@
+import { Component, IgnifxError, Phase, Signal, Vec2, Vec3, array, asset, bool, createDefaults, createServiceKey, defineExtension, defineSchema, describeSchema, enumOf, f32, lerp, map, optional, record, str, u32, vec2 } from "@ignifx/core";
+import { ActiveCollisionTypes, ActiveEvents, Ball, Capsule, CoefficientCombineRule, ColliderDesc, ConvexPolygon, Cuboid, EventQueue, Polyline, QueryFilterFlags, Ray, RigidBodyDesc, World, init } from "@dimforge/rapier2d-compat";
+//#region src/runtime/runtime-key.ts
+/**
+* The key the extension registers its runtime holder under, so that `Rigidbody2D`, the 2D
+* colliders, and `CharacterController2D` can reach the runtime through `this.app.services` without
+* a module-level singleton (`CONSTITUTION.md` §3.6: no globals, two apps in one process).
+*
+* The **holder** is registered rather than the runtime itself, because everything an extension
+* contributes is declared in `register` (`docs/architecture/04-extensions.md` §1) and the runtime
+* does not exist until `onStart`.
+*
+* @internal
+*/
+const Physics2DHostKey = createServiceKey("@ignifx/physics-2d:host");
+//#endregion
+//#region src/components/rigidbody.ts
+/**
+* The `Rigidbody2D` component (`docs/architecture/11-2d-toolkit.md` §8): what makes an entity's 2D
+* colliders a simulated, kinematic, or explicitly static Rapier body.
+*
+* ## Decisions §8 leaves open
+*
+* - **`mass` is exact, and `0` means "weigh the colliders".** Rapier derives a body's mass and
+*   angular inertia from each collider's *density* and area (`geometry/collider.d.ts`,
+*   `setDensity`), and `setAdditionalMass` adds mass without inertia. So a non-zero `mass` is
+*   applied by scaling every collider's density until the body weighs exactly that, which keeps the
+*   inertia distribution the shapes imply; `mass: 0` leaves Rapier's own density of 1 kg/m² alone.
+* - **`freezeRotation` is one boolean, not three.** A 2D body has one rotational degree of freedom
+*   (`dynamics/rigid_body.d.ts`, `lockRotations`).
+* - **Damping is per body here, unlike 3D.** Havok has no per-body damping; Rapier does
+*   (`setLinearDamping`, `setAngularDamping`), so `linearDamping` and `angularDamping` are real
+*   fields rather than upstream requests.
+* - **`collisionEvents` is a three-valued enum**, exactly as in `@ignifx/physics`: a schema field
+*   has one kind (ADR-0004), and `"auto"` recomputes from `ctx.entityImplements` whenever a
+*   component joins or leaves the entity.
+*/
+/**
+* How a 2D body moves.
+*
+* @public
+*/
+const BODY_TYPES_2D = [
+	"dynamic",
+	"kinematic",
+	"static"
+];
+/**
+* Whether a body's display pose is interpolated between fixed steps.
+*
+* @public
+*/
+const INTERPOLATION_MODES_2D = ["none", "interpolate"];
+/**
+* Whether collision callbacks are delivered for this body.
+*
+* @public
+*/
+const COLLISION_EVENT_MODES_2D = [
+	"auto",
+	"on",
+	"off"
+];
+/**
+* Makes an entity's 2D colliders a Rapier body.
+*
+* @example
+* ```ts
+* const crate = world.createEntity("Crate");
+* crate.transform.position2D = new Vec2(0, 5);
+* crate.addComponent(BoxCollider2D, { size: { x: 1, y: 1 } });
+* crate.addComponent(Rigidbody2D, { mass: 2 });
+* ```
+*
+* @public
+*/
+var Rigidbody2D = class Rigidbody2D extends Component {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/Rigidbody2D";
+	/** One body per entity. */
+	static allowMultiple = false;
+	/** The serialized field declarations (ADR-0004). */
+	static schema = rigidbody2DSchema();
+	/** Applies the schema defaults, exactly as `Component.define` would. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(Rigidbody2D.schema));
+	}
+	/** Marks the entity's body for a rebuild at the start of the next fixed step. */
+	onAttach() {
+		this.rebuild();
+	}
+	/** Marks the entity's body for a rebuild, which turns it back into an implicit static body. */
+	onDetach() {
+		this.rebuild();
+	}
+	/**
+	* Rebuilds the body at the start of the next fixed step. Call it after changing `bodyType`,
+	* `mass`, `freezeRotation`, damping, or the entity's scale.
+	*/
+	rebuild() {
+		this.#runtime()?.markDirty(this.entity);
+	}
+	/**
+	* The Rapier handles this component owns.
+	*
+	* @returns The body, or `null` before the first fixed step built it.
+	*/
+	get rapier() {
+		return { body: this.#runtime()?.bodyHandleOf(this.entity) ?? null };
+	}
+	/**
+	* The body's linear velocity in metres per second.
+	*
+	* @returns A freshly allocated vector; use {@link Rigidbody2D.linearVelocityToRef} in hot code.
+	*/
+	get linearVelocity() {
+		const out = new Vec2();
+		this.linearVelocityToRef(out);
+		return out;
+	}
+	/**
+	* Replaces the body's linear velocity.
+	*
+	* @param value - Metres per second, world space.
+	*/
+	set linearVelocity(value) {
+		this.#runtime()?.setLinearVelocity(this.entity, value);
+	}
+	/**
+	* Reads the linear velocity without allocating.
+	*
+	* @param out - The vector to write.
+	* @returns `out`.
+	*/
+	linearVelocityToRef(out) {
+		this.#runtime()?.readLinear(this.entity, out);
+		return out;
+	}
+	/**
+	* The body's angular velocity.
+	*
+	* @returns Degrees per second, counter-clockwise — the same unit as `Transform.rotation2D`.
+	*/
+	get angularVelocity() {
+		return this.#runtime()?.readAngular(this.entity) ?? 0;
+	}
+	/**
+	* Replaces the body's angular velocity.
+	*
+	* @param value - Degrees per second, counter-clockwise.
+	*/
+	set angularVelocity(value) {
+		this.#runtime()?.setAngularVelocity(this.entity, value);
+	}
+	/**
+	* The mass Rapier computed for the body, in kilograms.
+	*
+	* @returns The mass, or `0` before the body exists.
+	*/
+	get computedMass() {
+		return this.#runtime()?.massOf(this.entity) ?? 0;
+	}
+	/**
+	* Applies a force for one fixed step. Call it from `fixedUpdate`.
+	*
+	* @param force - Newtons, world space.
+	* @param point - Where to apply it; defaults to the centre of mass.
+	*
+	* @example
+	* ```ts
+	* fixedUpdate(): void {
+	*   this.body.addForce({ x: 0, y: 20 });
+	* }
+	* ```
+	*/
+	addForce(force, point) {
+		this.#runtime()?.addForce(this.entity, force, point ?? null);
+	}
+	/**
+	* Applies an instantaneous impulse.
+	*
+	* @param impulse - Newton-seconds, world space.
+	* @param point - Where to apply it; defaults to the centre of mass.
+	*/
+	addImpulse(impulse, point) {
+		this.#runtime()?.addImpulse(this.entity, impulse, point ?? null);
+	}
+	/**
+	* Applies a torque for one fixed step.
+	*
+	* @param torque - Newton-metres, positive counter-clockwise.
+	*/
+	addTorque(torque) {
+		this.#runtime()?.addTorque(this.entity, torque);
+	}
+	/**
+	* Moves the body without integrating a velocity, and resets the interpolation history so the
+	* display pose does not slide across the gap.
+	*
+	* @param position - The new world position, in metres.
+	* @param rotation - The new rotation in degrees counter-clockwise; defaults to the current one.
+	*/
+	teleport(position, rotation) {
+		this.#runtime()?.teleport(this.entity, position, rotation ?? this.transform.rotation2D);
+	}
+	/**
+	* The runtime, or `null` when the extension is not registered on this app.
+	*
+	* @returns The runtime.
+	*/
+	#runtime() {
+		return this.app.services.tryGet(Physics2DHostKey)?.runtime ?? null;
+	}
+};
+/**
+* Builds the `Rigidbody2D` schema.
+*
+* @returns The schema.
+*/
+function rigidbody2DSchema() {
+	return defineSchema({
+		bodyType: enumOf(BODY_TYPES_2D, "dynamic"),
+		mass: f32(1, { min: 0 }),
+		gravityScale: f32(1),
+		linearDamping: f32(0, { min: 0 }),
+		angularDamping: f32(.05, { min: 0 }),
+		freezeRotation: bool(false),
+		interpolation: enumOf(INTERPOLATION_MODES_2D, "interpolate"),
+		collisionEvents: enumOf(COLLISION_EVENT_MODES_2D, "auto")
+	});
+}
+//#endregion
+//#region src/components/character-controller.ts
+/**
+* The `CharacterController2D` component (`docs/architecture/11-2d-toolkit.md` §8): Rapier's
+* `KinematicCharacterController` (`control/character_controller.d.ts`) driven from `fixedUpdate`.
+*
+* ## How it is driven
+*
+* Call {@link CharacterController2D.move} from `fixedUpdate`. The requested displacements of one
+* step are summed and handed to Rapier's `computeColliderMovement` by the step system, so two
+* scripts moving the same character compose instead of fighting. Gravity is **not** applied by this
+* component: a bare controller is purely kinematic, exactly as the 3D one is, and the toolkit
+* controller scripts integrate gravity themselves.
+*
+* After the step the controller owns the entity's world X and Y. Z and `rotation2D` stay
+* user-controlled.
+*
+* ## The one addition to §8: `shape`
+*
+* §8 describes the controller as a capsule. Measured against `@dimforge/rapier2d-compat@0.20.0`
+* (spike S6.2), Rapier's autostep clears a 0.3 m step with a **box** character and refuses anything
+* above about 0.15 m with a capsule of radius 0.2 — so `stepOffset` is only usable with a box.
+* {@link CharacterController2D.shape} therefore chooses between the two, defaulting to `"capsule"`
+* as §8 says, and the limitation is documented in the skill and in ADR-0006's validation section.
+*/
+/**
+* The collision shape a 2D character controller uses.
+*
+* @public
+*/
+const CHARACTER_SHAPES_2D = ["capsule", "box"];
+/**
+* A kinematic character that walks, slides, climbs slopes, and steps up.
+*
+* @example
+* ```ts
+* class Walk extends Script implements ScriptCallbacks {
+*   static typeId = "mygame/Walk";
+*   fixedUpdate(dt: number): void {
+*     const controller = this.entity.requireComponent(CharacterController2D);
+*     controller.move({ x: 4 * dt, y: -9.81 * dt });
+*   }
+* }
+* ```
+*
+* @public
+*/
+var CharacterController2D = class CharacterController2D extends Component {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/CharacterController2D";
+	/** One controller per entity. */
+	static allowMultiple = false;
+	/** The serialized field declarations (ADR-0004). */
+	static schema = characterSchema();
+	/** The displacement requested so far this fixed step. */
+	#pendingMove = new Vec2();
+	/** The movement Rapier resolved for the last step, which is what `velocity` reports. */
+	#resolvedMove = new Vec2();
+	/** The averaged normal of the supporting surface, written by the step system. */
+	#groundNormal = new Vec2(0, 1);
+	/** Whether the last step ended on walkable ground. */
+	#grounded = false;
+	/** The fixed step the last move was resolved over, for `velocity`. */
+	#lastDelta = 0;
+	/** Emitted for every obstacle the character hit; created on first access. */
+	#onCollided = null;
+	/** Applies the schema defaults. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(CharacterController2D.schema));
+	}
+	/** Creates the Rapier controller at the start of the next fixed step. */
+	onAttach() {
+		this.rebuild();
+	}
+	/** Releases the Rapier controller and its collider. */
+	onDetach() {
+		this.#runtime()?.releaseController(this);
+	}
+	/** Rebuilds the capsule or box at the start of the next fixed step. */
+	rebuild() {
+		this.#runtime()?.markControllerDirty(this);
+	}
+	/**
+	* Requests a displacement for this fixed step. Displacements accumulate until the step runs.
+	*
+	* @param displacement - The world-space displacement to attempt, in metres.
+	*/
+	move(displacement) {
+		this.#pendingMove.set(this.#pendingMove.x + displacement.x, this.#pendingMove.y + displacement.y);
+	}
+	/**
+	* How fast the character actually moved over the last fixed step, after sliding and blocking.
+	*
+	* @returns A freshly allocated vector in metres per second.
+	*/
+	get velocity() {
+		if (this.#lastDelta <= 0) return new Vec2();
+		return new Vec2(this.#resolvedMove.x / this.#lastDelta, this.#resolvedMove.y / this.#lastDelta);
+	}
+	/**
+	* Whether the character ended the last step on walkable ground.
+	*
+	* @returns Rapier's `computedGrounded` from the last move.
+	*/
+	get isGrounded() {
+		return this.#grounded;
+	}
+	/**
+	* The most upward-facing normal of the obstacles the last move touched.
+	*
+	* @returns A live view; copy it if you keep it.
+	*/
+	get groundNormal() {
+		return this.#groundNormal;
+	}
+	/**
+	* Emitted once per obstacle the character hit during a step.
+	*
+	* @returns The signal, created on first access.
+	*/
+	get onCollided() {
+		this.#onCollided ??= new Signal();
+		return this.#onCollided;
+	}
+	/**
+	* Teleports the character, clearing any pending motion and the interpolation history.
+	*
+	* @param position - The new world position of the entity, in metres.
+	*/
+	teleport(position) {
+		this.#pendingMove.set(0, 0);
+		this.#runtime()?.teleportController(this, position);
+	}
+	/**
+	* The displacement requested so far this step, consumed by the step system.
+	*
+	* @returns A live view of the accumulator.
+	*
+	* @internal
+	*/
+	takePendingMove() {
+		return this.#pendingMove;
+	}
+	/**
+	* Records the outcome of a step.
+	*
+	* @param movement - What Rapier resolved.
+	* @param grounded - Whether the character ended on walkable ground.
+	* @param normal - The most upward-facing contact normal, or `null` when there was none.
+	* @param deltaSeconds - The fixed step the move covered.
+	*
+	* @internal
+	*/
+	applyStepResult(movement, grounded, normal, deltaSeconds) {
+		this.#resolvedMove.set(movement.x, movement.y);
+		this.#grounded = grounded;
+		this.#lastDelta = deltaSeconds;
+		if (normal !== null) this.#groundNormal.set(normal.x, normal.y);
+		this.#pendingMove.set(0, 0);
+	}
+	/**
+	* Emits `onCollided` if anything is listening.
+	*
+	* @param collision - The obstacle to report.
+	*
+	* @internal
+	*/
+	reportHit(collision) {
+		this.#onCollided?.emit(collision);
+	}
+	/**
+	* The runtime, or `null` when the extension is not registered on this app.
+	*
+	* @returns The runtime.
+	*/
+	#runtime() {
+		return this.app.services.tryGet(Physics2DHostKey)?.runtime ?? null;
+	}
+};
+/**
+* Builds the `CharacterController2D` schema.
+*
+* @returns The schema.
+*/
+function characterSchema() {
+	return defineSchema({
+		shape: enumOf(CHARACTER_SHAPES_2D, "capsule"),
+		radius: f32(.25, { min: 0 }),
+		height: f32(1, { min: 0 }),
+		offset: vec2(),
+		slopeLimit: f32(45, {
+			min: 0,
+			max: 90
+		}),
+		stepOffset: f32(0, { min: 0 }),
+		snapToGround: f32(0, { min: 0 }),
+		skinWidth: f32(.01, { min: 0 }),
+		onOneWayPlatforms: bool(true),
+		pushBodies: bool(false),
+		interpolation: enumOf(INTERPOLATION_MODES_2D, "interpolate")
+	});
+}
+//#endregion
+//#region src/errors.ts
+/**
+* The diagnostic codes `@ignifx/physics-2d` owns. 2D physics shares the `11` subsystem range with
+* the 2D toolkit (`docs/architecture/15-devtools-and-diagnostics.md` §1,
+* `docs/architecture/11-2d-toolkit.md` §8), so the range is split: `@ignifx/2d` owns
+* `IGX-1101`–`IGX-1149` and this package owns `IGX-1150` upwards.
+*
+* `IGX-1101` is the one exception. `11-2d-toolkit.md` §8 names it by number — "registering both
+* throws `IGX-1101`" — and only this package can detect the condition, so this package registers
+* it. An app's error-code registry refuses a duplicate registration
+* (`packages/core/src/errors/error-code-registry.ts`), so `@ignifx/2d` must not declare it.
+*/
+/**
+* Every diagnostic code `@ignifx/physics-2d` can throw or report.
+*
+* @example
+* ```ts
+* throw physics2DError(Physics2DErrorCode.queryBeforeStep, "raycast() ran before the first step.", {
+*   context: { query: "raycast" },
+* });
+* ```
+*
+* @public
+*/
+const Physics2DErrorCode = {
+	/** Both `physics()` and `physics2d()` are registered on one world (`11-2d-toolkit.md` §8). */
+	bothPhysicsExtensions: "IGX-1101",
+	/** The Rapier WebAssembly module could not be instantiated. */
+	rapierUnavailable: "IGX-1150",
+	/** An entity with 2D colliders but no `Rigidbody2D` moved after its static body was placed. */
+	movedStaticBody: "IGX-1151",
+	/** A collider's layer index is outside the sixteen Rapier's interaction groups can express. */
+	layerOutOfRange: "IGX-1152",
+	/** A query ran before the first completed fixed step, so Rapier has no broadphase yet. */
+	queryBeforeStep: "IGX-1153",
+	/** A `.physicsmaterial.json` file is not an `ignifx.physicsmaterial` document this build reads. */
+	invalidMaterialFile: "IGX-1154",
+	/** The `physics2d.collisionMatrix` setting names a layer the project does not declare. */
+	unknownLayer: "IGX-1155",
+	/** A collider's geometry is degenerate: too few points, or a hull Rapier refused to build. */
+	colliderGeometryInvalid: "IGX-1156",
+	/** A 2D body was built for an entity that has a parent, whose pose is not world space. */
+	bodyOnChildEntity: "IGX-1157"
+};
+/**
+* The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
+*
+* @public
+*/
+const PHYSICS_2D_ERROR_MESSAGES = Object.freeze({
+	"IGX-1101": "A world uses either physics() or physics2d(), and {extension} found the other already there.",
+	"IGX-1150": "The Rapier 2D WebAssembly module could not be instantiated.",
+	"IGX-1151": "{entity} has 2D colliders but no Rigidbody2D, and it moved after its body was placed.",
+	"IGX-1152": "{entity} is on layer {layer}, which is outside the sixteen layers Rapier 2D can filter by.",
+	"IGX-1153": "{query} needs at least one completed fixed step before Rapier can answer it.",
+	"IGX-1154": "{file} is not an ignifx.physicsmaterial document this build can read.",
+	"IGX-1155": "physics2d.collisionMatrix names the layer {layer}, which the project does not declare.",
+	"IGX-1156": "{entity} has a 2D collider whose geometry Rapier cannot build a shape from.",
+	"IGX-1157": "{entity} carries a 2D physics body but is not a root entity; Rapier writes its world pose."
+});
+/**
+* Builds an `IgnifxError` carrying one of this package's codes.
+*
+* @param code - The code from the `Physics2DErrorCode` table.
+* @param message - The actionable development sentence.
+* @param options - Context identifiers, a remedy hint, and the wrapped cause.
+* @returns The error to throw or to reject with.
+*
+* @example
+* ```ts
+* throw physics2DError(Physics2DErrorCode.unknownLayer, "physics2d.collisionMatrix names Enemy.", {
+*   context: { layer: "Enemy" },
+* });
+* ```
+*
+* @public
+*/
+function physics2DError(code, message, options) {
+	return new IgnifxError(code, message, {
+		...options?.context === void 0 ? {} : { context: options.context },
+		...options?.hint === void 0 ? {} : { hint: options.hint },
+		...options?.cause === void 0 ? {} : { cause: options.cause }
+	});
+}
+//#endregion
+//#region src/material.ts
+/**
+* The `ignifx.physicsmaterial` asset, read by the 2D extension.
+*
+* ## Why the format is the 3D one
+*
+* `11-2d-toolkit.md` §8 lists a `PhysicsMaterial2D`, and `09-physics.md` §2.4 already defines
+* `{ "format": "ignifx.physicsmaterial", "friction": …, "staticFriction": …, "restitution": … }`.
+* Inventing a second document for the same two numbers would give artists two files to keep in
+* step, so this package reads **the same format and the same `.physicsmaterial.json` extension**,
+* ignoring `staticFriction` (Rapier 2D has one friction coefficient, `geometry/collider.d.ts`).
+* `@ignifx/physics` and `@ignifx/physics-2d` never run in one world — `IGX-1101` — so the two
+* loaders never collide.
+*
+* The 2D-only knobs, how two surfaces' friction and restitution are **combined**, are fields on the
+* collider rather than on the asset, so the document stays byte-identical to the 3D one.
+*/
+/**
+* The asset type name `.physicsmaterial.json` addresses resolve to.
+*
+* @public
+*/
+const PHYSICS_MATERIAL_2D_ASSET_TYPE = "physicsmaterial";
+/**
+* The address suffix that selects the loader.
+*
+* @public
+*/
+const PHYSICS_MATERIAL_2D_FILE_EXTENSION = ".physicsmaterial.json";
+/**
+* The `format` string every physics-material document declares.
+*
+* @public
+*/
+const PHYSICS_MATERIAL_2D_FILE_FORMAT = "ignifx.physicsmaterial";
+/**
+* The file format version; `1` before ignifx 1.0.
+*
+* @public
+*/
+const PHYSICS_MATERIAL_2D_FORMAT_VERSION = 1;
+/**
+* A loaded 2D surface.
+*
+* @example
+* ```ts
+* const ice = await app.assets.load<PhysicsMaterial2D>("materials/ice.physicsmaterial.json");
+* floor.addComponent(BoxCollider2D, { size: { x: 10, y: 1 }, material: ice });
+* ```
+*
+* @public
+*/
+var PhysicsMaterial2D = class PhysicsMaterial2D {
+	/** The asset type token, so `asset(PhysicsMaterial2D)` fields resolve. */
+	static assetType = PHYSICS_MATERIAL_2D_ASSET_TYPE;
+	/** A human-readable name, used in diagnostics. */
+	name;
+	/** The friction coefficient. */
+	friction;
+	/** How much of the approach speed is returned, `0` to `1`. */
+	restitution;
+	/**
+	* Wraps parsed values.
+	*
+	* @param name - A human-readable name.
+	* @param values - Friction and restitution.
+	*/
+	constructor(name, values) {
+		this.name = name;
+		this.friction = values.friction;
+		this.restitution = values.restitution;
+	}
+	/**
+	* Builds a material in code, filling in the fields the caller omitted.
+	*
+	* @param name - A human-readable name.
+	* @param values - Any subset of the two coefficients.
+	* @returns The material.
+	*
+	* @example
+	* ```ts
+	* const bouncy = PhysicsMaterial2D.fromValues("bouncy", { restitution: 0.9 });
+	* ```
+	*/
+	static fromValues(name, values) {
+		return new PhysicsMaterial2D(name, {
+			friction: values.friction ?? .6,
+			restitution: values.restitution ?? 0
+		});
+	}
+};
+/**
+* Builds the loader for `.physicsmaterial.json` files.
+*
+* @returns The loader, ready for `ctx.registerAssetLoader`.
+*
+* @public
+*/
+function createPhysicsMaterial2DLoader() {
+	return {
+		type: PHYSICS_MATERIAL_2D_ASSET_TYPE,
+		extensions: [PHYSICS_MATERIAL_2D_FILE_EXTENSION],
+		load: async (ctx) => {
+			const document = await ctx.fetchJson();
+			return parsePhysicsMaterial2D(ctx.address, document);
+		}
+	};
+}
+/**
+* Parses one `ignifx.physicsmaterial` document into a 2D surface.
+*
+* @param address - The address it came from, for the diagnostic.
+* @param document - The parsed JSON.
+* @returns The material.
+* @throws IgnifxError with code `IGX-1154` when the document is not one this build can read.
+*
+* @public
+*/
+function parsePhysicsMaterial2D(address, document) {
+	const object = asObject(document);
+	if (object === null || object["format"] !== "ignifx.physicsmaterial") throw physics2DError(Physics2DErrorCode.invalidMaterialFile, `${address} is not an ${PHYSICS_MATERIAL_2D_FILE_FORMAT}.`, {
+		context: { file: address },
+		hint: `Add "format": "${PHYSICS_MATERIAL_2D_FILE_FORMAT}" to the document.`
+	});
+	const version = numberAt(object, "formatVersion", 1);
+	if (version > 1) throw physics2DError(Physics2DErrorCode.invalidMaterialFile, `${address} is version ${String(version)}.`, {
+		context: {
+			file: address,
+			version
+		},
+		hint: "Upgrade @ignifx/physics-2d, or re-save the material from this version of the editor."
+	});
+	return new PhysicsMaterial2D(typeof object["name"] === "string" ? object["name"] : address, {
+		friction: numberAt(object, "friction", .6),
+		restitution: numberAt(object, "restitution", 0)
+	});
+}
+/**
+* Views a JSON value as an object.
+*
+* @param value - The parsed JSON.
+* @returns The object, or `null` when the value is not one.
+*/
+function asObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+	return value;
+}
+/**
+* Reads a numeric property, tolerating its absence.
+*
+* @param object - The document.
+* @param key - The property name.
+* @param fallback - What to use when the property is missing or not a number.
+* @returns The value.
+*/
+function numberAt(object, key, fallback) {
+	const value = object[key];
+	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+//#endregion
+//#region src/components/collider.ts
+/**
+* The 2D collider contract (`docs/architecture/11-2d-toolkit.md` §8). Every collider shares an
+* offset, the trigger flag, a surface, a layer override, and the one-way platform flag, and answers
+* one question the body builder asks: which Rapier shapes it stands for.
+*
+* ## Corrections to §8
+*
+* - **The material is two fields, not a union.** A schema field has exactly one kind (ADR-0004), so
+*   {@link Collider2D.material} (an asset reference) and {@link Collider2D.inlineMaterial} (a
+*   record) are separate; the asset wins, the inline record is the fallback, and
+*   `physics2d.defaultMaterial` is the last resort. This is the same split `@ignifx/physics` makes.
+* - **Combine rules are collider fields.** Rapier combines two surfaces' friction and restitution
+*   with a per-collider rule (`dynamics/coefficient_combine_rule.d.ts`); the 3D
+*   `ignifx.physicsmaterial` document has no such field, so the knob lives here rather than
+*   forking the asset format.
+* - **A collider may stand for several Rapier colliders.** `TilemapCollider2D` produces one polygon
+*   per merged tile run, so {@link Collider2D.collectShapes} fills a list rather than returning one
+*   shape.
+*
+* ## Sizes and scale
+*
+* Sizes are authored in local metres and multiplied by the entity's lossy scale when the shapes are
+* built. Rapier cannot rescale a built shape, so a later scale change needs
+* {@link Collider2D.rebuild}.
+*/
+/**
+* How two surfaces' coefficients are combined when they touch, mirroring Rapier's
+* `CoefficientCombineRule`.
+*
+* @public
+*/
+const COMBINE_RULES = [
+	"average",
+	"min",
+	"multiply",
+	"max"
+];
+/**
+* The fields every 2D collider declares.
+*
+* @returns The shared field declarations, ready to spread into a collider's own schema.
+*
+* @public
+*/
+function collider2DFields() {
+	return {
+		offset: vec2(),
+		isTrigger: bool(false),
+		material: asset(PhysicsMaterial2D),
+		inlineMaterial: optional(record({
+			friction: f32(.6, { min: 0 }),
+			restitution: f32(0, {
+				min: 0,
+				max: 1
+			})
+		})),
+		frictionCombine: enumOf(COMBINE_RULES, "average"),
+		restitutionCombine: enumOf(COMBINE_RULES, "average"),
+		oneWay: bool(false),
+		layerOverride: str("")
+	};
+}
+/**
+* The base class of every 2D collider.
+*
+* @public
+*/
+var Collider2D = class extends Component {
+	/** Several colliders on one entity make one compound body. */
+	static allowMultiple = true;
+	/** Applies the shared defaults. A concrete collider calls `super()` and then applies its own. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(collider2DFields()));
+	}
+	/** Marks the entity's body for a rebuild at the start of the next fixed step. */
+	onAttach() {
+		this.rebuild();
+	}
+	/** Marks the entity's body for a rebuild, which removes this collider from it. */
+	onDetach() {
+		this.rebuild();
+	}
+	/**
+	* Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
+	* changing a size, an offset, `isTrigger`, or the entity's scale.
+	*
+	* @example
+	* ```ts
+	* box.size = { x: 2, y: 2 };
+	* box.rebuild();
+	* ```
+	*/
+	rebuild() {
+		this.app.services.tryGet(Physics2DHostKey)?.runtime?.markDirty(this.entity);
+	}
+	/**
+	* Resolves the surface this collider presents to Rapier.
+	*
+	* @param fallback - The world's `physics2d.defaultMaterial`.
+	* @returns The asset's values, the inline values, or the fallback.
+	*/
+	resolveMaterial(fallback) {
+		return this.material?.value ?? this.inlineMaterial ?? fallback;
+	}
+};
+//#endregion
+//#region src/components/colliders.ts
+/**
+* The concrete 2D colliders (`docs/architecture/11-2d-toolkit.md` §8). Each maps to one Rapier
+* shape (`geometry/shape.d.ts`), sized in local metres and multiplied by the entity's lossy scale.
+*
+* ## The two point-list colliders
+*
+* - `PolygonCollider2D` builds a **convex** shape (`ColliderDesc.convexHull`). Rapier 2D also ships
+*   `convexDecomposition`, which needs a triangle mesh with an index buffer and runs V-HACD — far
+*   too heavy for a component field. Concave outlines are expressed as several
+*   `PolygonCollider2D`s on one entity, which is what a compound body is for, or as an
+*   `EdgeCollider2D` when the outline is open.
+* - `EdgeCollider2D` builds a `polyline`, the open chain a platformer's ground contour wants. A
+*   polyline is infinitely thin: a fast body can tunnel through it, and a character controller that
+*   starts *inside* one is not pushed out. Static level geometry is what it is for.
+*/
+/** A quarter turn in radians, which is how a horizontal capsule is expressed. */
+const QUARTER_TURN = Math.PI / 2;
+/**
+* The axis a 2D capsule stands along.
+*
+* @public
+*/
+const CAPSULE_DIRECTIONS_2D = ["x", "y"];
+/**
+* An axis-aligned box collider, sized in local metres.
+*
+* @example
+* ```ts
+* const floor = world.createEntity("Floor");
+* floor.addComponent(BoxCollider2D, { size: { x: 20, y: 1 } });
+* ```
+*
+* @public
+*/
+var BoxCollider2D = class BoxCollider2D extends Collider2D {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/BoxCollider2D";
+	/** The serialized field declarations (ADR-0004). */
+	static schema = boxSchema();
+	/** Applies this collider's defaults on top of the shared ones. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(BoxCollider2D.schema));
+	}
+	/**
+	* Appends this collider's Rapier shape.
+	*
+	* @param scale - The entity's lossy 2D scale.
+	* @param out - The list to append to.
+	*
+	* @internal
+	*/
+	collectShapes(scale, out) {
+		out.push({
+			shape: {
+				kind: "box",
+				halfWidth: this.size.x * abs(scale.x) / 2,
+				halfHeight: this.size.y * abs(scale.y) / 2
+			},
+			offset: scaled(this.offset, scale),
+			rotation: 0,
+			oneWay: this.oneWay
+		});
+	}
+};
+/**
+* A circle collider. Non-uniform scale is not representable as a circle, so the larger scale axis
+* wins — the same rule Unity applies.
+*
+* @public
+*/
+var CircleCollider2D = class CircleCollider2D extends Collider2D {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/CircleCollider2D";
+	/** The serialized field declarations. */
+	static schema = circleSchema();
+	/** Applies this collider's defaults on top of the shared ones. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(CircleCollider2D.schema));
+	}
+	/**
+	* Appends this collider's Rapier shape.
+	*
+	* @param scale - The entity's lossy 2D scale.
+	* @param out - The list to append to.
+	*
+	* @internal
+	*/
+	collectShapes(scale, out) {
+		out.push({
+			shape: {
+				kind: "circle",
+				radius: this.radius * Math.max(abs(scale.x), abs(scale.y))
+			},
+			offset: scaled(this.offset, scale),
+			rotation: 0,
+			oneWay: this.oneWay
+		});
+	}
+};
+/**
+* A capsule collider: a rectangle with semicircular caps, standing along X or Y.
+*
+* @remarks
+* `height` is the **total** tip-to-tip height, so a capsule shorter than `2 * radius` degenerates to
+* a circle of that radius rather than inverting. Rapier's capsule always stands along Y, so an
+* `x` capsule is expressed by swapping the axes of the half-extents — which means an `x` capsule
+* and a rotated `y` capsule are the same shape.
+*
+* @public
+*/
+var CapsuleCollider2D = class CapsuleCollider2D extends Collider2D {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/CapsuleCollider2D";
+	/** The serialized field declarations. */
+	static schema = capsuleSchema();
+	/** Applies this collider's defaults on top of the shared ones. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(CapsuleCollider2D.schema));
+	}
+	/**
+	* Appends this collider's Rapier shape.
+	*
+	* @param scale - The entity's lossy 2D scale.
+	* @param out - The list to append to.
+	*
+	* @internal
+	*/
+	collectShapes(scale, out) {
+		const alongY = this.direction === "y";
+		const radialScale = alongY ? abs(scale.x) : abs(scale.y);
+		const axisScale = alongY ? abs(scale.y) : abs(scale.x);
+		const radius = this.radius * radialScale;
+		const half = Math.max(0, this.height * axisScale / 2 - radius);
+		out.push({
+			shape: {
+				kind: "capsule",
+				halfHeight: half,
+				radius
+			},
+			offset: scaled(this.offset, scale),
+			rotation: alongY ? 0 : QUARTER_TURN,
+			oneWay: this.oneWay
+		});
+	}
+};
+/**
+* A convex polygon collider, wound in either direction, in local metres.
+*
+* @remarks
+* Rapier builds the **convex hull** of the points, so a concave outline is silently rounded out.
+* Model a concave shape as several `PolygonCollider2D`s on one entity, or as an
+* {@link EdgeCollider2D} when it is an open contour.
+*
+* @public
+*/
+var PolygonCollider2D = class PolygonCollider2D extends Collider2D {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/PolygonCollider2D";
+	/** The serialized field declarations. */
+	static schema = pointsSchema();
+	/** Applies this collider's defaults on top of the shared ones. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(PolygonCollider2D.schema));
+	}
+	/**
+	* Appends this collider's Rapier shape.
+	*
+	* @param scale - The entity's lossy 2D scale.
+	* @param out - The list to append to.
+	* @throws IgnifxError with code `IGX-1156` when fewer than three points are given.
+	*
+	* @internal
+	*/
+	collectShapes(scale, out) {
+		if (this.points.length < 3) throw degenerate(this.entity.name, "PolygonCollider2D", "at least three points");
+		out.push({
+			shape: {
+				kind: "polygon",
+				points: packPoints(this.points, scale)
+			},
+			offset: scaled(this.offset, scale),
+			rotation: 0,
+			oneWay: this.oneWay
+		});
+	}
+};
+/**
+* An open chain of line segments — a platformer's ground contour.
+*
+* @public
+*/
+var EdgeCollider2D = class EdgeCollider2D extends Collider2D {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/EdgeCollider2D";
+	/** The serialized field declarations. */
+	static schema = pointsSchema();
+	/** Applies this collider's defaults on top of the shared ones. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(EdgeCollider2D.schema));
+	}
+	/**
+	* Appends this collider's Rapier shape.
+	*
+	* @param scale - The entity's lossy 2D scale.
+	* @param out - The list to append to.
+	* @throws IgnifxError with code `IGX-1156` when fewer than two points are given.
+	*
+	* @internal
+	*/
+	collectShapes(scale, out) {
+		if (this.points.length < 2) throw degenerate(this.entity.name, "EdgeCollider2D", "at least two points");
+		out.push({
+			shape: {
+				kind: "polyline",
+				points: packPoints(this.points, scale)
+			},
+			offset: scaled(this.offset, scale),
+			rotation: 0,
+			oneWay: this.oneWay
+		});
+	}
+};
+/**
+* Builds the `BoxCollider2D` schema.
+*
+* @returns The schema.
+*/
+function boxSchema() {
+	return defineSchema({
+		...collider2DFields(),
+		size: vec2({
+			x: 1,
+			y: 1
+		})
+	});
+}
+/**
+* Builds the `CircleCollider2D` schema.
+*
+* @returns The schema.
+*/
+function circleSchema() {
+	return defineSchema({
+		...collider2DFields(),
+		radius: f32(.5, { min: 0 })
+	});
+}
+/**
+* Builds the `CapsuleCollider2D` schema.
+*
+* @returns The schema.
+*/
+function capsuleSchema() {
+	return defineSchema({
+		...collider2DFields(),
+		radius: f32(.25, { min: 0 }),
+		height: f32(1, { min: 0 }),
+		direction: enumOf(CAPSULE_DIRECTIONS_2D, "y")
+	});
+}
+/**
+* Builds the schema the two point-list colliders share.
+*
+* @returns The schema.
+*/
+function pointsSchema() {
+	return defineSchema({
+		...collider2DFields(),
+		points: array(vec2())
+	});
+}
+/**
+* The absolute value of a scale component; a negative scale mirrors geometry, so the shape uses the
+* magnitude.
+*
+* @param value - The scale component.
+* @returns Its magnitude.
+*/
+function abs(value) {
+	return Math.abs(value);
+}
+/**
+* Scales a local offset into shape space.
+*
+* @param offset - The authored offset.
+* @param scale - The lossy 2D scale.
+* @returns A fresh vector; shape construction is not a per-frame path.
+*/
+function scaled(offset, scale) {
+	return {
+		x: offset.x * scale.x,
+		y: offset.y * scale.y
+	};
+}
+/**
+* Packs a point list into the interleaved `Float32Array` Rapier's shape constructors take.
+*
+* @param points - The authored points.
+* @param scale - The lossy 2D scale.
+* @returns A fresh buffer.
+*/
+function packPoints(points, scale) {
+	const packed = new Float32Array(points.length * 2);
+	for (let index = 0; index < points.length; index += 1) {
+		const point = points[index];
+		if (point === void 0) continue;
+		packed[index * 2] = point.x * scale.x;
+		packed[index * 2 + 1] = point.y * scale.y;
+	}
+	return packed;
+}
+/**
+* Builds the "that geometry is degenerate" failure.
+*
+* @param entity - The entity name.
+* @param component - Which collider complained.
+* @param requirement - What it needed.
+* @returns The error to throw.
+*/
+function degenerate(entity, component, requirement) {
+	return physics2DError(Physics2DErrorCode.colliderGeometryInvalid, `${component} on ${entity} needs ${requirement}.`, {
+		context: {
+			entity,
+			component
+		},
+		hint: `Give the collider ${requirement}.`
+	});
+}
+//#endregion
+//#region src/components/tilemap-collider.ts
+/**
+* `TilemapCollider2D` (`docs/architecture/11-2d-toolkit.md` §2.5, §8): the merged collision surface
+* of a `Tilemap`, turned into Rapier geometry.
+*
+* ## How it reaches the data
+*
+* `@ignifx/2d` is an **optional** peer of `@ignifx/physics-2d` (a physics-only 2D game needs no
+* sprite toolkit), so this component never imports the toolkit as a value — only the
+* `TilemapCollisionData` type. A game, or `@ignifx/2d`'s own tilemap loader, assigns
+* {@link TilemapCollider2D.collisionData}; the runtime compares the data's `version` at the start of
+* every fixed step and rebuilds the shapes when it changes, which is the same moment
+* `Tilemap.onCollisionChanged` fires and needs no signal subscription across the package boundary.
+*
+* ## Why closed polylines rather than polygons
+*
+* A merged run of solid tiles is not convex in general — an L of tiles merges into an L — and
+* Rapier's polygon shape is a **convex hull** (`geometry/shape.d.ts`, `ConvexPolygon`), which would
+* silently fill the notch. A closed `polyline` reproduces the outline exactly and is the shape
+* static level geometry wants; the trade-off is that a polyline is infinitely thin, so a body that
+* starts inside the tilemap is not pushed out.
+*/
+/**
+* The collision surface of a tilemap, as one static body's worth of Rapier shapes.
+*
+* @example
+* ```ts
+* const map = world.createEntity("Map");
+* const collider = map.addComponent(TilemapCollider2D);
+* collider.collisionData = tilemap.collisionData;
+* ```
+*
+* @public
+*/
+var TilemapCollider2D = class TilemapCollider2D extends Collider2D {
+	/** The namespaced registration id. */
+	static typeId = "ignifx/TilemapCollider2D";
+	/** The serialized field declarations; the geometry itself comes from the tilemap asset. */
+	static schema = tilemapSchema();
+	/** The merged chunk geometry, or `null` until a tilemap supplies it. */
+	#data = null;
+	/** The `version` of the data the current shapes were built from. */
+	#builtVersion = -1;
+	/** Applies the shared defaults. */
+	constructor() {
+		super();
+		Object.assign(this, createDefaults(TilemapCollider2D.schema));
+	}
+	/**
+	* The merged chunk geometry this collider builds shapes from.
+	*
+	* @returns The data, or `null` when none has been supplied.
+	*/
+	get collisionData() {
+		return this.#data;
+	}
+	/**
+	* Replaces the tilemap geometry and schedules a rebuild.
+	*
+	* @param value - The merged chunk geometry, or `null` to drop the shapes.
+	*/
+	set collisionData(value) {
+		this.#data = value;
+		this.#builtVersion = -1;
+		this.rebuild();
+	}
+	/**
+	* Whether the supplied data has changed since the shapes were built. The runtime polls this once
+	* per fixed step, which is how a tile edit reaches physics without a cross-package subscription.
+	*
+	* @returns `true` when a rebuild is due.
+	*
+	* @internal
+	*/
+	needsRebuild() {
+		return (this.#data?.version ?? -1) !== this.#builtVersion;
+	}
+	/**
+	* Appends one shape per merged outline and one per one-way edge.
+	*
+	* @param scale - The entity's lossy 2D scale.
+	* @param out - The list to append to.
+	*
+	* @internal
+	*/
+	collectShapes(scale, out) {
+		const data = this.#data;
+		this.#builtVersion = data?.version ?? -1;
+		if (data === null) return;
+		const offset = {
+			x: this.offset.x * scale.x,
+			y: this.offset.y * scale.y
+		};
+		for (const chunk of data.chunks) {
+			for (const polygon of chunk.polygons) {
+				if (polygon.length < 3) continue;
+				out.push({
+					shape: {
+						kind: "polyline",
+						points: closedLoop(polygon, scale)
+					},
+					offset,
+					rotation: 0,
+					oneWay: false
+				});
+			}
+			for (const edge of chunk.oneWayEdges) out.push({
+				shape: {
+					kind: "polyline",
+					points: segment(edge[0], edge[1], scale)
+				},
+				offset,
+				rotation: 0,
+				oneWay: true
+			});
+		}
+	}
+};
+/**
+* Builds the `TilemapCollider2D` schema.
+*
+* @returns The schema.
+*/
+function tilemapSchema() {
+	return defineSchema({ ...collider2DFields() });
+}
+/**
+* Packs an outline as a closed chain of vertices.
+*
+* @param points - The outline, wound counter-clockwise.
+* @param scale - The entity's lossy 2D scale.
+* @returns A fresh buffer whose last vertex repeats the first.
+*/
+function closedLoop(points, scale) {
+	const packed = new Float32Array((points.length + 1) * 2);
+	for (let index = 0; index < points.length; index += 1) {
+		const point = points[index];
+		if (point === void 0) continue;
+		packed[index * 2] = point.x * scale.x;
+		packed[index * 2 + 1] = point.y * scale.y;
+	}
+	packed[points.length * 2] = packed[0] ?? 0;
+	packed[points.length * 2 + 1] = packed[1] ?? 0;
+	return packed;
+}
+/**
+* Packs one one-way edge as a two-vertex chain.
+*
+* @param from - The edge's start.
+* @param to - The edge's end.
+* @param scale - The entity's lossy 2D scale.
+* @returns A fresh buffer.
+*/
+function segment(from, to, scale) {
+	return new Float32Array([
+		from.x * scale.x,
+		from.y * scale.y,
+		to.x * scale.x,
+		to.y * scale.y
+	]);
+}
+//#endregion
+//#region src/lite/rapier/module.ts
+/**
+* The one place `@dimforge/rapier2d-compat`'s WebAssembly is instantiated
+* (`docs/standards/coding-standards.md` §4, `CONSTITUTION.md` §3.4). Rapier is not Babylon Lite,
+* but it is a native/WASM backend under the same adapter rule, and the rule's allowed directory is
+* `src/lite/**` — hence `src/lite/rapier/`.
+*
+* ## Why `-compat`
+*
+* The `-compat` build inlines the WebAssembly module as base64 inside `rapier.mjs`, so it needs no
+* asset serving and works unchanged in Node and in the browser (spike S6.2, ADR-0006 Validation).
+* `init()` is what decodes and instantiates it; every other Rapier call before that throws.
+*
+* The import is static: `world.ts` and `service.ts` also import Rapier's classes statically, so a
+* dynamic import here alone would not move the 2 MB module out of an app's entry chunk (measured in
+* Phase 6). Splitting it needs the adapter to read every class off the loaded module instead, which
+* is the Phase 12 bundle work.
+*
+* @internal
+*/
+/**
+* Instantiates Rapier's WebAssembly module.
+*
+* @remarks
+* Rapier's own `init()` is idempotent and caches the instantiated module in the package's module
+* scope, so the second and later apps in one process pay nothing.
+*
+* @returns A promise that settles once Rapier is usable.
+*
+* @internal
+*/
+async function loadRapier() {
+	await init();
+}
+//#endregion
+//#region src/lite/rapier/world.ts
+/**
+* How a body moves, in the three flavours ignifx exposes.
+*
+* @internal
+*/
+const BodyMotion2D = {
+	/** Simulated by the solver. */
+	dynamic: "dynamic",
+	/** Moved by the game, pushes dynamic bodies, ignores forces. */
+	kinematic: "kinematic",
+	/** Never moves. */
+	static: "static"
+};
+/**
+* How two surfaces' friction or restitution coefficients are combined, mirroring Rapier's
+* `CoefficientCombineRule` (`dynamics/coefficient_combine_rule.d.ts`).
+*
+* @internal
+*/
+const CombineRule2D = {
+	/** The arithmetic mean; Rapier's default. */
+	average: "average",
+	/** The smaller of the two. */
+	min: "min",
+	/** The product. */
+	multiply: "multiply",
+	/** The larger of the two. */
+	max: "max"
+};
+/** Radians per full turn, for the degree conversions the components use. */
+const TAU = Math.PI * 2;
+/** How wide one half of an `InteractionGroups` word is. */
+const GROUP_BITS = 16;
+/** Every bit of one half. */
+const GROUP_MASK = 65535;
+/**
+* Packs a membership mask and a collide mask into Rapier's single `InteractionGroups` word.
+*
+* @param membership - Which layers the collider belongs to, in the low 16 bits.
+* @param filter - Which layers it may collide with, in the low 16 bits.
+* @returns The packed word.
+*
+* @internal
+*/
+function interactionGroups(membership, filter) {
+	return (membership & GROUP_MASK) << GROUP_BITS | filter & GROUP_MASK;
+}
+/**
+* Creates the physics world.
+*
+* @param gravity - The acceleration in metres per second squared.
+* @returns The world.
+*
+* @internal
+*/
+function createWorld(gravity) {
+	return new World({
+		x: gravity.x,
+		y: gravity.y
+	});
+}
+/**
+* Releases the world and every WebAssembly object it owns.
+*
+* @param world - The world.
+*
+* @internal
+*/
+function destroyWorld(world) {
+	world.free();
+}
+/**
+* Replaces world gravity.
+*
+* @param world - The world.
+* @param gravity - The new acceleration.
+*
+* @internal
+*/
+function setGravity(world, gravity) {
+	world.gravity.x = gravity.x;
+	world.gravity.y = gravity.y;
+}
+/**
+* Sets the length of the next step.
+*
+* @param world - The world.
+* @param seconds - The fixed step in seconds.
+*
+* @internal
+*/
+function setTimestep(world, seconds) {
+	world.timestep = seconds;
+}
+/**
+* Sets how many iterations the constraint solver runs.
+*
+* @param world - The world.
+* @param iterations - The iteration count; Rapier's default is 4.
+*
+* @internal
+*/
+function setSolverIterations(world, iterations) {
+	world.numSolverIterations = iterations;
+}
+/**
+* Advances the simulation by one timestep, collecting events.
+*
+* @param world - The world.
+* @param queue - The event collector.
+*
+* @internal
+*/
+function stepWorld(world, queue) {
+	world.step(queue);
+}
+/**
+* Rebuilds the broadphase without advancing time, by running a zero-length step.
+*
+* @remarks
+* Rapier only refreshes its acceleration structure inside `World.step`, so a collider created since
+* the last step is invisible to queries and to the character controller (S6.2). The queue is passed
+* so an enter event raised by the priming step is still delivered.
+*
+* @param world - The world.
+* @param queue - The event collector.
+*
+* @internal
+*/
+function primeWorld(world, queue) {
+	const timestep = world.timestep;
+	world.timestep = 0;
+	world.step(queue);
+	world.timestep = timestep;
+}
+/**
+* Creates the event collector.
+*
+* @remarks
+* `autoDrain: false` — the collector must survive both the priming step and the real step of one
+* fixed update, and the runtime drains it once at the end of that update.
+*
+* @returns The queue.
+*
+* @internal
+*/
+function createEventQueue() {
+	return new EventQueue(false);
+}
+/**
+* Releases the event collector.
+*
+* @param queue - The queue.
+*
+* @internal
+*/
+function destroyEventQueue(queue) {
+	queue.free();
+}
+/**
+* Hands every buffered collision and intersection event to a sink and clears the buffer.
+*
+* @param queue - The queue.
+* @param sink - Called once per event with the two collider handles and the enter/exit flag.
+*
+* @internal
+*/
+function drainCollisions(queue, sink) {
+	queue.drainCollisionEvents((first, second, started) => {
+		sink({
+			first,
+			second,
+			started
+		});
+	});
+}
+/**
+* Creates a rigid body.
+*
+* @param world - The world.
+* @param options - Motion, pose, damping, gravity scale, and mass.
+* @returns The body.
+*
+* @internal
+*/
+function createBody(world, options) {
+	const description = descriptionFor(options.motion).setTranslation(options.position.x, options.position.y).setRotation(options.rotation).setGravityScale(options.gravityScale).setLinearDamping(options.linearDamping).setAngularDamping(options.angularDamping).setSleeping(options.startAsleep);
+	if (options.freezeRotation) description.lockRotations();
+	if (options.additionalMass > 0) description.setAdditionalMass(options.additionalMass);
+	return world.createRigidBody(description);
+}
+/**
+* Removes a body and every collider attached to it.
+*
+* @param world - The world.
+* @param body - The body.
+*
+* @internal
+*/
+function destroyBody(world, body) {
+	world.removeRigidBody(body);
+}
+/**
+* Reads a body's world pose without allocating.
+*
+* @param body - The body.
+* @param out - The vector the translation is written into.
+* @returns The rotation in radians.
+*
+* @internal
+*/
+function readBodyPose(body, out) {
+	body.translation(out);
+	return body.rotation();
+}
+/**
+* Moves a body immediately, as a teleport.
+*
+* @param body - The body.
+* @param position - The new world position.
+* @param rotation - The new rotation in radians.
+*
+* @internal
+*/
+function setBodyPose(body, position, rotation) {
+	body.setTranslation({
+		x: position.x,
+		y: position.y
+	}, true);
+	body.setRotation(rotation, true);
+}
+/**
+* Asks Rapier to interpolate a kinematic body to a pose over the next step, which is what makes it
+* push dynamic bodies instead of tunnelling through them.
+*
+* @param body - The body.
+* @param position - The pose to reach.
+* @param rotation - The rotation to reach, in radians.
+*
+* @internal
+*/
+function setNextKinematicPose(body, position, rotation) {
+	body.setNextKinematicTranslation({
+		x: position.x,
+		y: position.y
+	});
+	body.setNextKinematicRotation(rotation);
+}
+/**
+* Reads a body's linear velocity without allocating.
+*
+* @param body - The body.
+* @param out - The vector to write.
+*
+* @internal
+*/
+function readLinearVelocity(body, out) {
+	body.linvel(out);
+}
+/**
+* Replaces a body's linear velocity.
+*
+* @param body - The body.
+* @param velocity - Metres per second.
+*
+* @internal
+*/
+function writeLinearVelocity(body, velocity) {
+	body.setLinvel({
+		x: velocity.x,
+		y: velocity.y
+	}, true);
+}
+/**
+* Reads a body's angular velocity.
+*
+* @param body - The body.
+* @returns Radians per second, counter-clockwise.
+*
+* @internal
+*/
+function readAngularVelocity(body) {
+	return body.angvel();
+}
+/**
+* Replaces a body's angular velocity.
+*
+* @param body - The body.
+* @param velocity - Radians per second.
+*
+* @internal
+*/
+function writeAngularVelocity(body, velocity) {
+	body.setAngvel(velocity, true);
+}
+/**
+* Adds a force that lasts for one step.
+*
+* @param body - The body.
+* @param force - Newtons.
+* @param point - Where to apply it, or `null` for the centre of mass.
+*
+* @internal
+*/
+function addForce(body, force, point) {
+	if (point === null) {
+		body.addForce({
+			x: force.x,
+			y: force.y
+		}, true);
+		return;
+	}
+	body.addForceAtPoint({
+		x: force.x,
+		y: force.y
+	}, {
+		x: point.x,
+		y: point.y
+	}, true);
+}
+/**
+* Applies an instantaneous impulse.
+*
+* @param body - The body.
+* @param impulse - Newton-seconds.
+* @param point - Where to apply it, or `null` for the centre of mass.
+*
+* @internal
+*/
+function applyImpulse(body, impulse, point) {
+	if (point === null) {
+		body.applyImpulse({
+			x: impulse.x,
+			y: impulse.y
+		}, true);
+		return;
+	}
+	body.applyImpulseAtPoint({
+		x: impulse.x,
+		y: impulse.y
+	}, {
+		x: point.x,
+		y: point.y
+	}, true);
+}
+/**
+* Adds a torque that lasts for one step.
+*
+* @param body - The body.
+* @param torque - Newton-metres, positive counter-clockwise.
+*
+* @internal
+*/
+function addTorque(body, torque) {
+	body.addTorque(torque, true);
+}
+/**
+* The mass Rapier computed for a body from its colliders and any additional mass.
+*
+* @param body - The body.
+* @returns Kilograms.
+*
+* @internal
+*/
+function bodyMass(body) {
+	return body.mass();
+}
+/**
+* Sets how many kilograms a square metre of a collider weighs. Rapier derives the body's mass and
+* angular inertia from this and the collider's area.
+*
+* @param collider - The collider.
+* @param density - Kilograms per square metre.
+*
+* @internal
+*/
+function setColliderDensity(collider, density) {
+	collider.setDensity(density);
+}
+/**
+* Recomputes a body's mass and inertia from its colliders, after their densities changed.
+*
+* @param body - The body.
+*
+* @internal
+*/
+function recomputeMass(body) {
+	body.recomputeMassPropertiesFromColliders();
+}
+/**
+* Creates a collider and attaches it to a body.
+*
+* @param world - The world.
+* @param body - The body it belongs to.
+* @param shape - The geometry, in body-local metres.
+* @param options - Offset, sensor flag, filter word, surface, and event flags.
+* @returns The collider, or `null` when Rapier refuses the geometry — a convex hull of collinear or
+* duplicated points, say, which throws inside its WebAssembly rather than returning nothing.
+*
+* @internal
+*/
+function createCollider(world, body, shape, options) {
+	const description = describeShape(shape);
+	if (description === null) return null;
+	description.setTranslation(options.offset.x, options.offset.y).setRotation(options.rotation).setSensor(options.sensor).setCollisionGroups(options.groups).setFriction(options.friction).setRestitution(options.restitution).setFrictionCombineRule(combineRule(options.frictionCombine)).setRestitutionCombineRule(combineRule(options.restitutionCombine));
+	if (options.events) description.setActiveEvents(ActiveEvents.COLLISION_EVENTS).setActiveCollisionTypes(ActiveCollisionTypes.ALL);
+	try {
+		return world.createCollider(description, body);
+	} catch {
+		return null;
+	}
+}
+/**
+* Turns a collider's collision and intersection events on or off without rebuilding it.
+*
+* @param collider - The collider.
+* @param enabled - Whether it reports events.
+*
+* @internal
+*/
+function setColliderEvents(collider, enabled) {
+	collider.setActiveEvents(enabled ? ActiveEvents.COLLISION_EVENTS : ActiveEvents.NONE);
+	collider.setActiveCollisionTypes(enabled ? ActiveCollisionTypes.ALL : ActiveCollisionTypes.DEFAULT);
+}
+/**
+* Reads a collider's world position without allocating.
+*
+* @param collider - The collider.
+* @param out - The vector to write.
+*
+* @internal
+*/
+function readColliderTranslation(collider, out) {
+	collider.translation(out);
+}
+/**
+* The stable integer Rapier identifies a collider by, which is what its event queue reports.
+*
+* @param collider - The collider.
+* @returns The handle.
+*
+* @internal
+*/
+function colliderHandle(collider) {
+	return collider.handle;
+}
+/**
+* Whether a collider is a sensor, which is how a trigger event is told from a contact.
+*
+* @param collider - The collider.
+* @returns `true` for a sensor.
+*
+* @internal
+*/
+function isColliderSensor(collider) {
+	return collider.isSensor();
+}
+/**
+* Reads the first contact of a collider pair.
+*
+* @param world - The world.
+* @param first - One collider.
+* @param second - The other.
+* @param out - The record to write.
+*
+* @internal
+*/
+function readContact(world, first, second, out) {
+	out.touching = false;
+	out.impulse = 0;
+	world.contactPair(first, second, (manifold, flipped) => {
+		const normal = manifold.normal();
+		const sign = flipped ? -1 : 1;
+		out.normal.set(normal.x * sign, normal.y * sign);
+		const point = manifold.numSolverContacts() > 0 ? manifold.solverContactPoint(0) : null;
+		if (point !== null) out.point.set(point.x, point.y);
+		out.impulse = manifold.numContacts() > 0 ? manifold.contactImpulse(0) : 0;
+		out.touching = true;
+	});
+}
+/**
+* Casts a ray and writes the nearest hit.
+*
+* @param world - The world.
+* @param origin - The world-space origin.
+* @param direction - A unit direction.
+* @param maxDistance - How far to travel.
+* @param groups - The packed filter word.
+* @param hitSensors - Whether sensors count.
+* @param outPoint - Receives the contact point.
+* @param outNormal - Receives the contact normal.
+* @param out - Receives the hit flag, collider, and distance.
+*
+* @internal
+*/
+function castRay(world, origin, direction, maxDistance, groups, hitSensors, outPoint, outNormal, out) {
+	out.hit = false;
+	out.collider = null;
+	out.distance = 0;
+	const ray = new Ray({
+		x: origin.x,
+		y: origin.y
+	}, {
+		x: direction.x,
+		y: direction.y
+	});
+	const hit = world.castRayAndGetNormal(ray, maxDistance, true, sensorFlags(hitSensors), groups);
+	if (hit === null) return;
+	out.hit = true;
+	out.collider = hit.collider;
+	out.distance = hit.timeOfImpact;
+	outPoint.set(origin.x + direction.x * hit.timeOfImpact, origin.y + direction.y * hit.timeOfImpact);
+	outNormal.set(hit.normal.x, hit.normal.y);
+}
+/**
+* Casts a ray and hands every hit to a sink, nearest first is **not** guaranteed — the caller sorts.
+*
+* @param world - The world.
+* @param origin - The world-space origin.
+* @param direction - A unit direction.
+* @param maxDistance - How far to travel.
+* @param groups - The packed filter word.
+* @param hitSensors - Whether sensors count.
+* @param sink - Called once per hit with the collider, distance, and normal.
+*
+* @internal
+*/
+function castRayAll(world, origin, direction, maxDistance, groups, hitSensors, sink) {
+	const ray = new Ray({
+		x: origin.x,
+		y: origin.y
+	}, {
+		x: direction.x,
+		y: direction.y
+	});
+	world.intersectionsWithRay(ray, maxDistance, true, (intersection) => {
+		sink(intersection.collider, intersection.timeOfImpact, intersection.normal.x, intersection.normal.y);
+		return true;
+	}, sensorFlags(hitSensors), groups);
+}
+/**
+* Lists every collider a positioned shape overlaps.
+*
+* @param world - The world.
+* @param shape - The query geometry.
+* @param position - Its world position.
+* @param rotation - Its world rotation in radians.
+* @param groups - The packed filter word.
+* @param hitSensors - Whether sensors count.
+* @param sink - Called once per overlapping collider.
+*
+* @internal
+*/
+function overlapShape(world, shape, position, rotation, groups, hitSensors, sink) {
+	const built = buildShape(shape);
+	if (built === null) return;
+	world.intersectionsWithShape({
+		x: position.x,
+		y: position.y
+	}, rotation, built, (collider) => {
+		sink(collider);
+		return true;
+	}, sensorFlags(hitSensors), groups);
+}
+/**
+* Sweeps a shape and writes the first contact.
+*
+* @param world - The world.
+* @param shape - The query geometry.
+* @param position - Where the sweep starts.
+* @param rotation - The shape's rotation in radians.
+* @param direction - A unit sweep direction.
+* @param maxDistance - How far to sweep.
+* @param groups - The packed filter word.
+* @param hitSensors - Whether sensors count.
+* @param outPoint - Receives the contact point.
+* @param outNormal - Receives the contact normal.
+* @param out - Receives the hit flag, collider, and distance.
+*
+* @internal
+*/
+function castShape(world, shape, position, rotation, direction, maxDistance, groups, hitSensors, outPoint, outNormal, out) {
+	out.hit = false;
+	out.collider = null;
+	out.distance = 0;
+	const built = buildShape(shape);
+	if (built === null) return;
+	const hit = world.castShape({
+		x: position.x,
+		y: position.y
+	}, rotation, {
+		x: direction.x,
+		y: direction.y
+	}, built, 0, maxDistance, true, sensorFlags(hitSensors), groups);
+	if (hit === null) return;
+	out.hit = true;
+	out.collider = hit.collider;
+	out.distance = hit.time_of_impact;
+	const cos = Math.cos(rotation);
+	const sin = Math.sin(rotation);
+	const originX = position.x + direction.x * hit.time_of_impact;
+	const originY = position.y + direction.y * hit.time_of_impact;
+	outPoint.set(originX + hit.witness1.x * cos - hit.witness1.y * sin, originY + hit.witness1.x * sin + hit.witness1.y * cos);
+	outNormal.set(hit.normal1.x * cos - hit.normal1.y * sin, hit.normal1.x * sin + hit.normal1.y * cos);
+}
+/**
+* Turns degrees counter-clockwise into the radians Rapier stores.
+*
+* @param degrees - The angle in degrees.
+* @returns The angle in radians.
+*
+* @internal
+*/
+function toRadians(degrees) {
+	return degrees * TAU / 360;
+}
+/**
+* Turns Rapier's radians into the degrees `Transform.rotation2D` uses.
+*
+* @param radians - The angle in radians.
+* @returns The angle in degrees.
+*
+* @internal
+*/
+function toDegrees(radians) {
+	return radians * 360 / TAU;
+}
+/**
+* Builds the Rapier `Shape` a description stands for, for the query paths.
+*
+* @param shape - The description.
+* @returns The shape, or `null` when the geometry is degenerate.
+*/
+function buildShape(shape) {
+	if (shape.kind === "box") return new Cuboid(shape.halfWidth, shape.halfHeight);
+	if (shape.kind === "circle") return new Ball(shape.radius);
+	if (shape.kind === "capsule") return new Capsule(shape.halfHeight, shape.radius);
+	if (shape.kind === "polyline") return new Polyline(shape.points);
+	return new ConvexPolygon(shape.points, false);
+}
+/**
+* Builds the collider description a shape stands for.
+*
+* @param shape - The description.
+* @returns The description, or `null` when Rapier refuses the geometry.
+*/
+function describeShape(shape) {
+	if (shape.kind === "box") return ColliderDesc.cuboid(shape.halfWidth, shape.halfHeight);
+	if (shape.kind === "circle") return ColliderDesc.ball(shape.radius);
+	if (shape.kind === "capsule") return ColliderDesc.capsule(shape.halfHeight, shape.radius);
+	if (shape.kind === "polyline") return ColliderDesc.polyline(shape.points);
+	return ColliderDesc.convexHull(shape.points);
+}
+/**
+* The body description a motion type starts from.
+*
+* @param motion - The motion type.
+* @returns A fresh description.
+*/
+function descriptionFor(motion) {
+	if (motion === BodyMotion2D.dynamic) return RigidBodyDesc.dynamic();
+	return motion === BodyMotion2D.kinematic ? RigidBodyDesc.kinematicPositionBased() : RigidBodyDesc.fixed();
+}
+/**
+* Rapier's combine rule for one of ours.
+*
+* @param rule - The ignifx name.
+* @returns Rapier's value.
+*/
+function combineRule(rule) {
+	if (rule === CombineRule2D.min) return CoefficientCombineRule.Min;
+	if (rule === CombineRule2D.multiply) return CoefficientCombineRule.Multiply;
+	return rule === CombineRule2D.max ? CoefficientCombineRule.Max : CoefficientCombineRule.Average;
+}
+/**
+* The query filter flags that express "sensors count" or "sensors do not".
+*
+* @param hitSensors - Whether sensors count.
+* @returns The flags.
+*/
+function sensorFlags(hitSensors) {
+	return hitSensors ? void 0 : QueryFilterFlags.EXCLUDE_SENSORS;
+}
+//#endregion
+//#region src/runtime/host.ts
+/**
+* The one mutable cell between `register` and `onStart`.
+*
+* `Extension.register` runs **before** `createApp` builds the world
+* (`packages/core/src/app/app.ts`, `initialize`), and the Rapier world needs the world's layer
+* table and Rapier's WebAssembly module, which is loaded asynchronously. So the extension declares
+* its systems and its service in `register` — which is where `docs/architecture/04-extensions.md`
+* §1 says everything is declared — and they all read the runtime through this holder, which
+* `onStart` fills in.
+*
+* @internal
+*/
+var Physics2DHost = class {
+	/** The runtime, or `null` until `onStart` has built it. */
+	runtime = null;
+};
+//#endregion
+//#region src/lite/rapier/character.ts
+/**
+* Creates a character controller.
+*
+* @param world - The world.
+* @param skinWidth - The gap Rapier keeps between the character and its surroundings, in metres.
+* @returns The controller.
+*
+* @internal
+*/
+function createController(world, skinWidth) {
+	const controller = world.createCharacterController(skinWidth);
+	controller.setUp({
+		x: 0,
+		y: 1
+	});
+	return controller;
+}
+/**
+* Releases a controller.
+*
+* @param world - The world.
+* @param controller - The controller.
+*
+* @internal
+*/
+function destroyController(world, controller) {
+	world.removeCharacterController(controller);
+}
+/**
+* Applies the component's settings to a controller.
+*
+* @param controller - The controller.
+* @param tuning - The slope, step, snap, and pushing settings.
+*
+* @internal
+*/
+function tuneController(controller, tuning) {
+	controller.setMaxSlopeClimbAngle(tuning.slopeLimit);
+	controller.setMinSlopeSlideAngle(tuning.slideLimit);
+	controller.setApplyImpulsesToDynamicBodies(tuning.pushBodies);
+	if (tuning.stepOffset > 0) controller.enableAutostep(tuning.stepOffset, tuning.stepMinWidth, true);
+	else controller.disableAutostep();
+	if (tuning.snapToGround > 0) controller.enableSnapToGround(tuning.snapToGround);
+	else controller.disableSnapToGround();
+}
+/**
+* Runs one collide-and-slide move.
+*
+* @param controller - The controller.
+* @param collider - The character's own collider.
+* @param desired - The displacement to attempt, in metres.
+* @param groups - The packed filter word obstacles must pass.
+* @param filter - An extra per-collider predicate — how one-way platforms are done — or `null`.
+* @param out - Receives the movement Rapier resolved.
+* @returns `true` when the character ended the move on walkable ground.
+*
+* @internal
+*/
+function computeControllerMovement(controller, collider, desired, groups, filter, out) {
+	if (filter === null) controller.computeColliderMovement(collider, {
+		x: desired.x,
+		y: desired.y
+	}, void 0, groups);
+	else controller.computeColliderMovement(collider, {
+		x: desired.x,
+		y: desired.y
+	}, void 0, groups, filter);
+	controller.computedMovement(out);
+	return controller.computedGrounded();
+}
+/**
+* How many obstacles the last move hit.
+*
+* @param controller - The controller.
+* @returns The count.
+*
+* @internal
+*/
+function controllerHitCount(controller) {
+	return controller.numComputedCollisions();
+}
+/**
+* Reads one obstacle of the last move.
+*
+* @param controller - The controller.
+* @param index - Which obstacle.
+* @param out - The record to write.
+* @returns `true` when the obstacle exists.
+*
+* @internal
+*/
+function readControllerHit(controller, index, out) {
+	const hit = controller.computedCollision(index);
+	if (hit === null) return false;
+	out.collider = hit.collider;
+	out.point.set(hit.witness1.x, hit.witness1.y);
+	out.normal.set(hit.normal1.x, hit.normal1.y);
+	return true;
+}
+//#endregion
+//#region src/runtime/runtime.ts
+/**
+* The counters `09-physics.md` §9 and `11-2d-toolkit.md` §8 name for 2D.
+*
+* @public
+*/
+const PHYSICS_2D_DIAGNOSTICS_COUNTERS = Object.freeze([
+	"bodies",
+	"colliders",
+	"stepsThisFrame",
+	"collisionEvents",
+	"triggerEvents",
+	"stepMs"
+]);
+/**
+* The diagnostics group name.
+*
+* @public
+*/
+const PHYSICS_2D_DIAGNOSTICS_GROUP = "physics2d";
+/** How far an implicit static body may move before the diagnostic considers it moved. */
+const STATIC_MOVE_EPSILON = 1e-6;
+/** How much clear floor Rapier requires past an autostep, in metres. */
+const AUTOSTEP_MIN_WIDTH = .05;
+/** Every layer bit Rapier can express. */
+const ALL_LAYER_BITS = 65535;
+/**
+* The per-app 2D physics runtime.
+*
+* @internal
+*/
+var Physics2DRuntime = class {
+	#ctx;
+	#settings;
+	#world;
+	#counters;
+	#queue;
+	#records = [];
+	#byEntity = /* @__PURE__ */ new Map();
+	#byCollider = /* @__PURE__ */ new Map();
+	#controllers = /* @__PURE__ */ new Map();
+	#oneWay = /* @__PURE__ */ new Map();
+	#dirty = /* @__PURE__ */ new Set();
+	#collideMasks = (/* @__PURE__ */ new Int32Array(16)).fill(ALL_LAYER_BITS);
+	#pairs = /* @__PURE__ */ new Map();
+	#endedPairs = [];
+	#startedPairs = [];
+	#contact = {
+		touching: false,
+		point: new Vec2(),
+		normal: new Vec2(),
+		impulse: 0
+	};
+	#contactPoint = {
+		point: new Vec2(),
+		normal: new Vec2(),
+		impulse: 0
+	};
+	#contacts = [];
+	#controllerHit = {
+		collider: null,
+		point: new Vec2(),
+		normal: new Vec2()
+	};
+	#trigger = null;
+	#collision = null;
+	#characterCollision = null;
+	#scratchPose = new Vec3();
+	#scratchVector = new Vec2();
+	#relativeVelocity = new Vec2();
+	#movement = new Vec2();
+	#groundNormal = new Vec2();
+	#filterScratch = new Vec2();
+	/** The vertical component of the displacement the filtered move is attempting. */
+	#filterDesiredY = 0;
+	/** The bottom of the filtered character, in metres. */
+	#filterFeet = 0;
+	#colliderSetChanged = true;
+	#stepped = false;
+	#disposed = false;
+	#stepsThisFrame = 0;
+	#stepMs = 0;
+	#collisionEventCount = 0;
+	#triggerEventCount = 0;
+	#colliderCount = 0;
+	/**
+	* Builds the runtime and applies the world settings.
+	*
+	* @param options - The context, settings, world, and counters.
+	* @throws IgnifxError with code `IGX-1155` when the collision matrix names an unknown layer.
+	*/
+	constructor(options) {
+		this.#ctx = options.ctx;
+		this.#settings = options.settings;
+		this.#world = options.world;
+		this.#counters = options.counters;
+		this.#queue = createEventQueue();
+		this.#contacts.push(this.#contactPoint);
+		setGravity(this.#world, this.#settings.gravity);
+		if (this.#settings.velocityIterations > 0) setSolverIterations(this.#world, this.#settings.velocityIterations);
+		this.#buildCollideMasks();
+	}
+	/**
+	* The Rapier world, for the query and escape-hatch paths.
+	*
+	* @returns The world handle.
+	*/
+	get world() {
+		return this.#world;
+	}
+	/**
+	* Whether at least one fixed step has run, which is what Rapier's broadphase needs before a query
+	* can answer (`09-physics.md` §5, spike S6.2).
+	*
+	* @returns `true` once a step has completed.
+	*/
+	get hasStepped() {
+		return this.#stepped;
+	}
+	/**
+	* Every body, in creation order.
+	*
+	* @returns The records.
+	*/
+	get records() {
+		return this.#records;
+	}
+	/**
+	* The resolved settings.
+	*
+	* @returns The `physics2d` section.
+	*/
+	get settings() {
+		return this.#settings;
+	}
+	/**
+	* Replaces world gravity.
+	*
+	* @param gravity - The new acceleration vector.
+	*/
+	setGravity(gravity) {
+		setGravity(this.#world, gravity);
+	}
+	/**
+	* Marks an entity's body for a rebuild at the start of the next fixed step.
+	*
+	* @param entity - The entity whose colliders, `Rigidbody2D`, or controller changed.
+	*/
+	markDirty(entity) {
+		if (!this.#disposed && !entity.isDestroyed) this.#dirty.add(entity);
+	}
+	/**
+	* Marks a character controller's entity for a rebuild.
+	*
+	* @param component - The controller component.
+	*/
+	markControllerDirty(component) {
+		this.markDirty(component.entity);
+	}
+	/**
+	* Drops a character controller's body, which is what detaching the component does.
+	*
+	* @param component - The controller component.
+	*/
+	releaseController(component) {
+		this.markDirty(component.entity);
+	}
+	/**
+	* The Rapier body of an entity, for the escape hatch.
+	*
+	* @param entity - The entity.
+	* @returns The body handle, or `null`.
+	*/
+	bodyHandleOf(entity) {
+		return this.#byEntity.get(entity)?.body ?? null;
+	}
+	/**
+	* The record an entity owns.
+	*
+	* @param entity - The entity.
+	* @returns The record, or `null`.
+	*/
+	recordOf(entity) {
+		return this.#byEntity.get(entity) ?? null;
+	}
+	/**
+	* The entity and collider a Rapier collider belongs to, which is how a query result or an event
+	* becomes an ignifx object.
+	*
+	* @param collider - The Rapier collider, or `null`.
+	* @returns The binding, or `null`.
+	*/
+	bindingOf(collider) {
+		return collider === null ? null : this.#byCollider.get(colliderHandle(collider)) ?? null;
+	}
+	/**
+	* The mass Rapier computed for an entity's body.
+	*
+	* @param entity - The entity.
+	* @returns Kilograms, or `0` when there is no body.
+	*/
+	massOf(entity) {
+		const record = this.#byEntity.get(entity);
+		return record === void 0 ? 0 : bodyMass(record.body);
+	}
+	/**
+	* Reads a body's linear velocity.
+	*
+	* @param entity - The entity.
+	* @param out - The vector to write; left untouched when there is no body.
+	*/
+	readLinear(entity, out) {
+		const record = this.#byEntity.get(entity);
+		if (record !== void 0) readLinearVelocity(record.body, out);
+	}
+	/**
+	* Reads a body's angular velocity.
+	*
+	* @param entity - The entity.
+	* @returns Degrees per second, counter-clockwise.
+	*/
+	readAngular(entity) {
+		const record = this.#byEntity.get(entity);
+		return record === void 0 ? 0 : toDegrees(readAngularVelocity(record.body));
+	}
+	/**
+	* Sets a body's linear velocity.
+	*
+	* @param entity - The entity.
+	* @param velocity - Metres per second.
+	*/
+	setLinearVelocity(entity, velocity) {
+		const record = this.#byEntity.get(entity);
+		if (record !== void 0) writeLinearVelocity(record.body, velocity);
+	}
+	/**
+	* Sets a body's angular velocity.
+	*
+	* @param entity - The entity.
+	* @param velocity - Degrees per second.
+	*/
+	setAngularVelocity(entity, velocity) {
+		const record = this.#byEntity.get(entity);
+		if (record !== void 0) writeAngularVelocity(record.body, toRadians(velocity));
+	}
+	/**
+	* Applies a force for one fixed step.
+	*
+	* @param entity - The entity.
+	* @param force - Newtons.
+	* @param point - The application point, or `null` for the centre of mass.
+	*/
+	addForce(entity, force, point) {
+		const record = this.#byEntity.get(entity);
+		if (record !== void 0) addForce(record.body, force, point);
+	}
+	/**
+	* Applies an impulse.
+	*
+	* @param entity - The entity.
+	* @param impulse - Newton-seconds.
+	* @param point - The application point, or `null` for the centre of mass.
+	*/
+	addImpulse(entity, impulse, point) {
+		const record = this.#byEntity.get(entity);
+		if (record !== void 0) applyImpulse(record.body, impulse, point);
+	}
+	/**
+	* Applies a torque for one fixed step.
+	*
+	* @param entity - The entity.
+	* @param torque - Newton-metres, positive counter-clockwise.
+	*/
+	addTorque(entity, torque) {
+		const record = this.#byEntity.get(entity);
+		if (record !== void 0) addTorque(record.body, torque);
+	}
+	/**
+	* Teleports a body and resets its interpolation history.
+	*
+	* @param entity - The entity.
+	* @param position - The new world position.
+	* @param rotationDegrees - The new rotation in degrees counter-clockwise.
+	*/
+	teleport(entity, position, rotationDegrees) {
+		const record = this.#byEntity.get(entity);
+		this.#writeTransform(entity, position, rotationDegrees);
+		if (record === void 0) return;
+		const radians = toRadians(rotationDegrees);
+		setBodyPose(record.body, position, radians);
+		record.currentPosition.set(position.x, position.y);
+		record.previousPosition.set(position.x, position.y);
+		record.currentRotation = radians;
+		record.previousRotation = radians;
+		this.#colliderSetChanged = true;
+	}
+	/**
+	* Teleports a character controller.
+	*
+	* @param component - The controller component.
+	* @param position - The new world position.
+	*/
+	teleportController(component, position) {
+		this.teleport(component.entity, position, component.transform.rotation2D);
+	}
+	/**
+	* Restores the authoritative pose of every interpolated body, undoing the display pose the
+	* `PreRender` system wrote (`09-physics.md` §1).
+	*/
+	restorePoses() {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record !== void 0 && record.interpolate) this.#writeTransform(record.entity, record.currentPosition, toDegrees(record.currentRotation));
+		}
+	}
+	/**
+	* Runs one fixed step: reconcile, push kinematic poses, move controllers, step Rapier, snapshot,
+	* dispatch events.
+	*
+	* @param fixedDeltaSeconds - The fixed step in seconds.
+	*/
+	step(fixedDeltaSeconds) {
+		this.#syncLayers();
+		this.#pollTilemaps();
+		this.#reconcile();
+		this.#pushKinematicPoses();
+		setTimestep(this.#world, fixedDeltaSeconds);
+		const started = now();
+		if (this.#colliderSetChanged || !this.#stepped) {
+			primeWorld(this.#world, this.#queue);
+			this.#colliderSetChanged = false;
+		}
+		this.#refreshOneWayPlatforms();
+		this.#moveControllers(fixedDeltaSeconds);
+		this.#capturePreStepVelocities();
+		stepWorld(this.#world, this.#queue);
+		this.#stepMs += now() - started;
+		this.#stepsThisFrame += 1;
+		this.#stepped = true;
+		this.#snapshot();
+		this.#dispatchEvents();
+	}
+	/**
+	* Writes the interpolated display pose of every interpolated body.
+	*
+	* @param alpha - `time.fixedStepAlpha`, in `[0, 1)`.
+	*/
+	interpolate(alpha) {
+		this.#publishCounters();
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record === void 0 || !record.interpolate) continue;
+			this.#scratchVector.set(lerp(record.previousPosition.x, record.currentPosition.x, alpha), lerp(record.previousPosition.y, record.currentPosition.y, alpha));
+			const rotation = record.previousRotation + shortestArc(record.previousRotation, record.currentRotation) * alpha;
+			this.#writeTransform(record.entity, this.#scratchVector, toDegrees(rotation));
+		}
+	}
+	/** Tears every body down and releases the Rapier world. */
+	dispose() {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		for (let index = this.#records.length - 1; index >= 0; index -= 1) {
+			const record = this.#records[index];
+			if (record !== void 0) this.#teardown(record);
+		}
+		this.#records.length = 0;
+		this.#byEntity.clear();
+		this.#byCollider.clear();
+		this.#controllers.clear();
+		this.#pairs.clear();
+		destroyEventQueue(this.#queue);
+		destroyWorld(this.#world);
+	}
+	/**
+	* Publishes the frame's counters and zeroes the accumulators. `PreRender` is where a frame's fixed
+	* steps are all done.
+	*/
+	#publishCounters() {
+		this.#counters.set(this.#counters.index("bodies"), this.#records.length);
+		this.#counters.set(this.#counters.index("colliders"), this.#colliderCount);
+		this.#counters.set(this.#counters.index("stepsThisFrame"), this.#stepsThisFrame);
+		this.#counters.set(this.#counters.index("collisionEvents"), this.#collisionEventCount);
+		this.#counters.set(this.#counters.index("triggerEvents"), this.#triggerEventCount);
+		this.#counters.set(this.#counters.index("stepMs"), this.#stepMs);
+		this.#stepsThisFrame = 0;
+		this.#collisionEventCount = 0;
+		this.#triggerEventCount = 0;
+		this.#stepMs = 0;
+	}
+	/**
+	* Builds the per-layer collide masks from `physics2d.collisionMatrix` (`09-physics.md` §3).
+	*
+	* @throws IgnifxError with code `IGX-1155` when a name is not a declared layer, and reports
+	* `IGX-1152` for a layer Rapier's sixteen interaction groups cannot express.
+	*/
+	#buildCollideMasks() {
+		for (const [name, others] of Object.entries(this.#settings.collisionMatrix)) {
+			const index = this.#layerIndex(name);
+			let mask = 0;
+			for (const other of others) mask |= 1 << this.#layerIndex(other);
+			this.#collideMasks[index] = mask;
+		}
+	}
+	/**
+	* Resolves a layer name to its index, refusing an undeclared one.
+	*
+	* @param name - The layer name.
+	* @returns The index, clamped into Rapier's sixteen.
+	* @throws IgnifxError with code `IGX-1155` when the project does not declare the layer.
+	*/
+	#layerIndex(name) {
+		const index = this.#ctx.app.world.layers.indexOf(name);
+		if (index < 0) throw physics2DError(Physics2DErrorCode.unknownLayer, `${name} is not a layer this project declares.`, {
+			context: { layer: name },
+			hint: "Add the layer to the layers settings section, or fix the name in physics2d.collisionMatrix."
+		});
+		return this.#clampLayer(index, name);
+	}
+	/**
+	* Reports a layer Rapier cannot express and falls back to layer 0.
+	*
+	* @param layer - The layer index.
+	* @param subject - What the diagnostic names.
+	* @returns The layer to use.
+	*/
+	#clampLayer(layer, subject) {
+		if (layer < 16) return layer;
+		this.#ctx.log.warn(`${Physics2DErrorCode.layerOutOfRange}: {entity} is on layer {layer}, which is outside the sixteen layers Rapier 2D can filter by.`, subject, String(layer));
+		return 0;
+	}
+	/** Marks every entity whose layer changed since its body was built. */
+	#syncLayers() {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record !== void 0 && record.entity.layer !== record.layer) this.markDirty(record.entity);
+		}
+	}
+	/** Marks every entity whose tilemap collision data changed since its shapes were built. */
+	#pollTilemaps() {
+		const colliders = this.#ctx.app.world.components(TilemapCollider2D);
+		for (let index = 0; index < colliders.length; index += 1) {
+			const collider = colliders[index];
+			if (collider !== void 0 && collider.needsRebuild()) this.markDirty(collider.entity);
+		}
+	}
+	/** Rebuilds every body marked dirty. */
+	#reconcile() {
+		if (this.#dirty.size === 0) return;
+		const pending = [...this.#dirty];
+		this.#dirty.clear();
+		for (const entity of pending) this.#rebuildEntity(entity);
+		this.#colliderSetChanged = true;
+	}
+	/**
+	* Tears an entity's body down and builds a new one from its current components.
+	*
+	* @param entity - The entity to rebuild.
+	*/
+	#rebuildEntity(entity) {
+		const existing = this.#byEntity.get(entity);
+		let carriedLinear = null;
+		let carriedAngular = 0;
+		if (existing !== void 0) {
+			if (existing.motion === BodyMotion2D.dynamic) {
+				carriedLinear = new Vec2();
+				readLinearVelocity(existing.body, carriedLinear);
+				carriedAngular = readAngularVelocity(existing.body);
+			}
+			this.#removeRecord(entity);
+		}
+		if (entity.isDestroyed || !entity.activeInHierarchy) return;
+		const controller = entity.getComponent(CharacterController2D);
+		const colliders = collidersOf(entity);
+		if (colliders.length === 0 && controller === null) return;
+		if (entity.parent !== null) this.#ctx.log.warn(`${Physics2DErrorCode.bodyOnChildEntity}: {entity} carries a 2D physics body but is not a root entity; Rapier writes its world pose.`, entity.name);
+		const record = this.#build(entity, entity.getComponent(Rigidbody2D), controller, colliders);
+		if (record === null) return;
+		this.#records.push(record);
+		if (record.motion === BodyMotion2D.dynamic && carriedLinear !== null) {
+			writeLinearVelocity(record.body, carriedLinear);
+			writeAngularVelocity(record.body, carriedAngular);
+		}
+	}
+	/**
+	* Builds one body from an entity's colliders and controller.
+	*
+	* @param entity - The entity.
+	* @param rigidbody - Its `Rigidbody2D`, or `null`.
+	* @param controller - Its `CharacterController2D`, or `null`.
+	* @param colliders - Its colliders, in component order.
+	* @returns The new record, or `null` when nothing produced a shape — a `TilemapCollider2D` whose
+	* tilemap has not published its geometry yet, say, which must not leave an empty body behind.
+	*/
+	#build(entity, rigidbody, controller, colliders) {
+		const transform = entity.transform;
+		transform.positionToRef(this.#scratchPose);
+		const rotation = toRadians(transform.rotation2D);
+		const layer = this.#clampLayer(entity.layer, entity.name);
+		const motion = motionOf(rigidbody, controller);
+		const body = createBody(this.#world, {
+			motion,
+			position: {
+				x: this.#scratchPose.x,
+				y: this.#scratchPose.y
+			},
+			rotation,
+			gravityScale: rigidbody?.gravityScale ?? 1,
+			linearDamping: rigidbody?.linearDamping ?? 0,
+			angularDamping: rigidbody?.angularDamping ?? 0,
+			freezeRotation: rigidbody?.freezeRotation ?? controller !== null,
+			additionalMass: 0,
+			startAsleep: false
+		});
+		const record = {
+			entity,
+			rigidbody,
+			controller,
+			body,
+			colliders: [],
+			owners: [],
+			controllerCollider: null,
+			motion,
+			interpolate: this.#shouldInterpolate(rigidbody, controller, motion),
+			layer,
+			collisionEvents: false,
+			previousPosition: new Vec2(this.#scratchPose.x, this.#scratchPose.y),
+			previousRotation: rotation,
+			currentPosition: new Vec2(this.#scratchPose.x, this.#scratchPose.y),
+			currentRotation: rotation,
+			preStepVelocity: new Vec2(),
+			staticVersion: transform.worldMatrixVersion,
+			reportedMove: false,
+			disconnects: []
+		};
+		this.#byEntity.set(entity, record);
+		this.#attachColliders(record, colliders, layer);
+		if (controller !== null) this.#attachController(record, controller, layer);
+		if (record.colliders.length === 0) {
+			this.#byEntity.delete(entity);
+			destroyBody(this.#world, body);
+			return null;
+		}
+		this.#applyMass(record);
+		this.#applyCollisionEvents(record);
+		this.#watchEntity(record);
+		return record;
+	}
+	/**
+	* Builds and registers every Rapier collider an entity's authored colliders stand for.
+	*
+	* @param record - The record being built.
+	* @param colliders - The authored colliders.
+	* @param layer - The entity's clamped layer.
+	*/
+	#attachColliders(record, colliders, layer) {
+		const defaults = this.#settings.defaultMaterial;
+		const shapes = [];
+		for (const collider of colliders) {
+			shapes.length = 0;
+			collider.collectShapes(record.entity.transform.lossyScale, shapes);
+			const effective = collider.layerOverride === "" ? layer : this.#layerIndex(collider.layerOverride);
+			const material = collider.resolveMaterial(defaults);
+			for (const collected of shapes) this.#addCollider(record, collider, collected, effective, material);
+		}
+	}
+	/**
+	* Creates one Rapier collider and binds it back to its author.
+	*
+	* @param record - The record it belongs to.
+	* @param owner - The authored collider, or `null` for a controller shape.
+	* @param collected - The geometry and its placement.
+	* @param layer - The layer to filter as.
+	* @param material - The surface.
+	* @returns The created collider, or `null` when Rapier refused the geometry.
+	*/
+	#addCollider(record, owner, collected, layer, material) {
+		const collider = createCollider(this.#world, record.body, collected.shape, {
+			offset: collected.offset,
+			rotation: collected.rotation,
+			sensor: owner?.isTrigger === true,
+			groups: interactionGroups(1 << layer, this.#collideMasks[layer] ?? ALL_LAYER_BITS),
+			friction: material.friction,
+			restitution: material.restitution,
+			frictionCombine: owner?.frictionCombine ?? "average",
+			restitutionCombine: owner?.restitutionCombine ?? "average",
+			events: owner?.isTrigger === true
+		});
+		if (collider === null) {
+			this.#ctx.log.warn(`${Physics2DErrorCode.colliderGeometryInvalid}: {entity} has a 2D collider whose geometry Rapier cannot build a shape from.`, record.entity.name);
+			return null;
+		}
+		const handle = colliderHandle(collider);
+		record.colliders.push(collider);
+		record.owners.push(owner);
+		this.#byCollider.set(handle, {
+			record,
+			owner,
+			collider
+		});
+		this.#colliderCount += 1;
+		if (collected.oneWay) this.#oneWay.set(handle, {
+			collider,
+			halfHeight: topOf(collected.shape) + collected.offset.y,
+			top: 0
+		});
+		return collider;
+	}
+	/**
+	* Builds a character controller's own shape and Rapier controller.
+	*
+	* @param record - The record being built.
+	* @param controller - The component.
+	* @param layer - The entity's clamped layer.
+	*/
+	#attachController(record, controller, layer) {
+		const half = Math.max(0, controller.height / 2 - controller.radius);
+		const shape = {
+			shape: controller.shape === "box" ? {
+				kind: "box",
+				halfWidth: controller.radius,
+				halfHeight: Math.max(controller.radius, controller.height / 2)
+			} : {
+				kind: "capsule",
+				halfHeight: half,
+				radius: controller.radius
+			},
+			offset: controller.offset,
+			rotation: 0,
+			oneWay: false
+		};
+		const collider = this.#addCollider(record, null, shape, layer, this.#settings.defaultMaterial);
+		record.controllerCollider = collider;
+		if (collider === null) return;
+		const rapierController = createController(this.#world, Math.max(controller.skinWidth, .001));
+		tuneController(rapierController, {
+			slopeLimit: toRadians(controller.slopeLimit),
+			slideLimit: toRadians(controller.slopeLimit),
+			stepOffset: controller.stepOffset,
+			stepMinWidth: AUTOSTEP_MIN_WIDTH,
+			snapToGround: controller.snapToGround,
+			pushBodies: controller.pushBodies
+		});
+		this.#controllers.set(colliderHandle(collider), rapierController);
+	}
+	/**
+	* Scales the colliders' densities so the body weighs exactly `Rigidbody2D.mass`.
+	*
+	* @param record - The record being built.
+	*/
+	#applyMass(record) {
+		const wanted = record.rigidbody?.mass ?? 0;
+		if (record.motion !== BodyMotion2D.dynamic || wanted <= 0) return;
+		const current = bodyMass(record.body);
+		if (current <= 0) return;
+		const density = wanted / current;
+		for (const collider of record.colliders) setColliderDensity(collider, density);
+		recomputeMass(record.body);
+	}
+	/**
+	* Keeps a record in step with its entity: component changes rebuild, destruction removes.
+	*
+	* @param record - The record to watch.
+	*/
+	#watchEntity(record) {
+		const entity = record.entity;
+		record.disconnects.push(entity.onComponentAdded.connect((component) => {
+			this.#onComponentChanged(record, component);
+		}), entity.onComponentRemoved.connect((component) => {
+			this.#onComponentChanged(record, component);
+		}), entity.onDestroyed.connect(() => {
+			this.#removeRecord(entity);
+		}));
+	}
+	/**
+	* Recomputes `collisionEvents` when a component joins or leaves the entity.
+	*
+	* @param record - The body record.
+	* @param component - The component that changed.
+	*/
+	#onComponentChanged(record, component) {
+		if (component instanceof Collider2D || component instanceof Rigidbody2D || component instanceof CharacterController2D) {
+			this.markDirty(record.entity);
+			return;
+		}
+		this.#applyCollisionEvents(record);
+	}
+	/**
+	* Pushes the effective `collisionEvents` value to every collider of a body.
+	*
+	* @param record - The body record.
+	*/
+	#applyCollisionEvents(record) {
+		const mode = record.rigidbody?.collisionEvents ?? "auto";
+		const enabled = mode === "on" ? true : mode === "off" ? false : this.#entityWantsEvents(record.entity);
+		if (enabled === record.collisionEvents) return;
+		record.collisionEvents = enabled;
+		for (let index = 0; index < record.colliders.length; index += 1) {
+			const collider = record.colliders[index];
+			const owner = record.owners[index];
+			if (collider !== void 0) setColliderEvents(collider, enabled || owner?.isTrigger === true);
+		}
+	}
+	/**
+	* Whether any script on an entity implements a physics callback.
+	*
+	* @param entity - The entity.
+	* @returns `true` when at least one does.
+	*/
+	#entityWantsEvents(entity) {
+		return this.#ctx.entityImplements(entity, "onCollisionEnter") || this.#ctx.entityImplements(entity, "onCollisionStay") || this.#ctx.entityImplements(entity, "onCollisionExit") || this.#ctx.entityImplements(entity, "onTriggerEnter") || this.#ctx.entityImplements(entity, "onTriggerExit");
+	}
+	/**
+	* Drops an entity's body immediately.
+	*
+	* @param entity - The entity whose body goes away.
+	*/
+	#removeRecord(entity) {
+		const record = this.#byEntity.get(entity);
+		if (record === void 0) return;
+		this.#teardown(record);
+		const index = this.#records.indexOf(record);
+		if (index >= 0) this.#records.splice(index, 1);
+		this.#byEntity.delete(entity);
+		this.#dirty.delete(entity);
+		this.#colliderSetChanged = true;
+	}
+	/**
+	* Releases one record's Rapier resources, signal connections, and index entries.
+	*
+	* @param record - The record to tear down.
+	*/
+	#teardown(record) {
+		for (const disconnect of record.disconnects) disconnect();
+		record.disconnects = [];
+		for (const collider of record.colliders) {
+			const handle = colliderHandle(collider);
+			const controller = this.#controllers.get(handle);
+			if (controller !== void 0) {
+				destroyController(this.#world, controller);
+				this.#controllers.delete(handle);
+			}
+			this.#byCollider.delete(handle);
+			this.#oneWay.delete(handle);
+			this.#dropPairs(handle);
+			this.#colliderCount -= 1;
+		}
+		record.colliders = [];
+		record.owners = [];
+		record.controllerCollider = null;
+		destroyBody(this.#world, record.body);
+	}
+	/**
+	* Forgets every touching pair a departing collider took part in.
+	*
+	* @param handle - The collider handle.
+	*/
+	#dropPairs(handle) {
+		for (const [key, pair] of this.#pairs) if (pair.first === handle || pair.second === handle) this.#pairs.delete(key);
+	}
+	/** Pushes every kinematic body's authored transform into Rapier before the step. */
+	#pushKinematicPoses() {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record === void 0 || record.motion !== BodyMotion2D.kinematic || record.controller !== null) continue;
+			const transform = record.entity.transform;
+			transform.positionToRef(this.#scratchPose);
+			setNextKinematicPose(record.body, this.#scratchVector.set(this.#scratchPose.x, this.#scratchPose.y), toRadians(transform.rotation2D));
+		}
+	}
+	/** Caches every one-way platform's world top, so the move filter needs no Rapier call. */
+	#refreshOneWayPlatforms() {
+		for (const platform of this.#oneWay.values()) {
+			readColliderTranslation(platform.collider, this.#filterScratch);
+			platform.top = this.#filterScratch.y + platform.halfHeight;
+		}
+	}
+	/**
+	* Remembers every event-reporting body's velocity before the solver runs, so a collision callback
+	* can report the speed the two bodies met at rather than the one they left with.
+	*/
+	#capturePreStepVelocities() {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record !== void 0 && record.collisionEvents) readLinearVelocity(record.body, record.preStepVelocity);
+		}
+	}
+	/**
+	* Hands every character controller its accumulated displacement and turns the resolved movement
+	* into a kinematic target.
+	*
+	* @param fixedDeltaSeconds - The fixed step.
+	*/
+	#moveControllers(fixedDeltaSeconds) {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			const component = record?.controller ?? null;
+			const collider = record?.controllerCollider ?? null;
+			if (record === void 0 || component === null || collider === null) continue;
+			const rapierController = this.#controllers.get(colliderHandle(collider));
+			if (rapierController === void 0) continue;
+			const desired = component.takePendingMove();
+			this.#filterDesiredY = desired.y;
+			this.#filterFeet = record.currentPosition.y + component.offset.y - halfHeightOf(component);
+			const grounded = computeControllerMovement(rapierController, collider, desired, interactionGroups(1 << record.layer, this.#collideMasks[record.layer] ?? ALL_LAYER_BITS), component.onOneWayPlatforms ? this.#oneWayFilter : null, this.#movement);
+			const normal = this.#collectControllerHits(rapierController, component);
+			component.applyStepResult(this.#movement, grounded, normal, fixedDeltaSeconds);
+			setNextKinematicPose(record.body, this.#scratchVector.set(record.currentPosition.x + this.#movement.x, record.currentPosition.y + this.#movement.y), record.currentRotation);
+		}
+	}
+	/**
+	* The one-way platform predicate, bound once so the per-step move allocates nothing.
+	*
+	* Rapier runs it from inside WebAssembly, so it reads only plain JavaScript state:
+	* {@link Physics2DRuntime.#refreshOneWayPlatforms} caches every platform's world top *before* the
+	* move, because calling back into Rapier (`collider.translation()`) from inside the callback is a
+	* re-entrant WebAssembly call and the obstacle is then never actually excluded (measured, S6.2).
+	*
+	* @param collider - The obstacle Rapier is considering.
+	* @returns `false` when the obstacle should be ignored this step.
+	*/
+	#oneWayFilter = (collider) => {
+		const platform = this.#oneWay.get(colliderHandle(collider));
+		if (platform === void 0) return true;
+		return this.#filterDesiredY <= 0 && this.#filterFeet >= platform.top - ONE_WAY_TOLERANCE;
+	};
+	/**
+	* Reports every obstacle a controller hit and returns the most upward-facing normal.
+	*
+	* @param rapierController - Rapier's controller.
+	* @param component - The component.
+	* @returns The ground normal, or `null` when nothing was hit.
+	*/
+	#collectControllerHits(rapierController, component) {
+		const count = controllerHitCount(rapierController);
+		let best = null;
+		let bestY = -2;
+		for (let index = 0; index < count; index += 1) {
+			if (!readControllerHit(rapierController, index, this.#controllerHit)) continue;
+			const normal = this.#controllerHit.normal;
+			if (normal.y > bestY) {
+				bestY = normal.y;
+				this.#groundNormal.set(normal.x, normal.y);
+				best = this.#groundNormal;
+			}
+			const binding = this.bindingOf(this.#controllerHit.collider);
+			const event = this.#characterCollision ??= {
+				other: null,
+				otherCollider: null,
+				point: this.#controllerHit.point,
+				normal: this.#controllerHit.normal
+			};
+			event.other = binding?.record.entity ?? null;
+			event.otherCollider = binding?.owner ?? null;
+			component.reportHit(event);
+		}
+		return best;
+	}
+	/** Snapshots every body's authoritative pose and writes it onto the entity. */
+	#snapshot() {
+		for (let index = 0; index < this.#records.length; index += 1) {
+			const record = this.#records[index];
+			if (record === void 0) continue;
+			record.previousPosition.copyFrom(record.currentPosition);
+			record.previousRotation = record.currentRotation;
+			record.currentRotation = readBodyPose(record.body, record.currentPosition);
+			if (record.motion === BodyMotion2D.static && record.rigidbody === null && record.controller === null) {
+				this.#checkStaticMove(record);
+				continue;
+			}
+			this.#writeTransform(record.entity, record.currentPosition, toDegrees(record.currentRotation));
+		}
+	}
+	/**
+	* Reports `IGX-1151` once for an implicit static body whose transform moved.
+	*
+	* @param record - The body record.
+	*/
+	#checkStaticMove(record) {
+		const version = record.entity.transform.worldMatrixVersion;
+		if (version === record.staticVersion || record.reportedMove) return;
+		record.entity.transform.positionToRef(this.#scratchPose);
+		if (Math.abs(this.#scratchPose.x - record.currentPosition.x) < STATIC_MOVE_EPSILON && Math.abs(this.#scratchPose.y - record.currentPosition.y) < STATIC_MOVE_EPSILON) {
+			record.staticVersion = version;
+			return;
+		}
+		record.staticVersion = version;
+		record.reportedMove = true;
+		this.#ctx.log.warn(`${Physics2DErrorCode.movedStaticBody}: {entity} has 2D colliders but no Rigidbody2D, and it moved after its body was placed.`, record.entity.name);
+	}
+	/**
+	* Writes a 2D pose onto an entity without disturbing its Z.
+	*
+	* @param entity - The entity.
+	* @param position - The world position in metres.
+	* @param rotationDegrees - The rotation in degrees counter-clockwise.
+	*/
+	#writeTransform(entity, position, rotationDegrees) {
+		const transform = entity.transform;
+		transform.positionToRef(this.#scratchPose);
+		this.#scratchPose.set(position.x, position.y, this.#scratchPose.z);
+		transform.position = this.#scratchPose;
+		transform.rotation2D = rotationDegrees;
+	}
+	/** Drains Rapier's event queue and delivers enter, stay, and exit to both participants. */
+	#dispatchEvents() {
+		this.#startedPairs.length = 0;
+		this.#endedPairs.length = 0;
+		drainCollisions(this.#queue, (event) => {
+			const key = pairKey(event.first, event.second);
+			if (!event.started) {
+				const existing = this.#pairs.get(key);
+				if (existing !== void 0) {
+					this.#pairs.delete(key);
+					this.#endedPairs.push(existing);
+				}
+				return;
+			}
+			const first = this.#byCollider.get(event.first);
+			const second = this.#byCollider.get(event.second);
+			if (first === void 0 || second === void 0) return;
+			const pair = {
+				first: event.first,
+				second: event.second,
+				sensor: isColliderSensor(first.collider) || isColliderSensor(second.collider),
+				entered: true
+			};
+			this.#pairs.set(key, pair);
+			this.#startedPairs.push(pair);
+		});
+		for (const pair of this.#endedPairs) this.#deliverPair(pair, "exit");
+		for (const pair of this.#startedPairs) this.#deliverPair(pair, "enter");
+		for (const pair of this.#pairs.values()) {
+			if (pair.entered) {
+				pair.entered = false;
+				continue;
+			}
+			this.#deliverPair(pair, "stay");
+		}
+	}
+	/**
+	* Delivers one pair's event to both participants.
+	*
+	* @param pair - The touching pair.
+	* @param phase - Which callback to deliver.
+	*/
+	#deliverPair(pair, phase) {
+		const first = this.#byCollider.get(pair.first);
+		const second = this.#byCollider.get(pair.second);
+		if (first === void 0 || second === void 0) return;
+		if (pair.sensor) {
+			if (phase === "stay") return;
+			this.#triggerEventCount += 1;
+			const kind = phase === "enter" ? "onTriggerEnter" : "onTriggerExit";
+			this.#deliverTrigger(first, second, kind);
+			this.#deliverTrigger(second, first, kind);
+			return;
+		}
+		this.#collisionEventCount += 1;
+		const kind = phase === "enter" ? "onCollisionEnter" : phase === "exit" ? "onCollisionExit" : "onCollisionStay";
+		this.#readContacts(pair, phase);
+		this.#deliverCollision(first, second, kind);
+		this.#deliverCollision(second, first, kind);
+	}
+	/**
+	* Fills the pooled contact point for a collision event.
+	*
+	* @param pair - The touching pair.
+	* @param phase - Which callback is being delivered; an exit has no contact left to read.
+	*/
+	#readContacts(pair, phase) {
+		this.#contactPoint.impulse = 0;
+		if (phase === "exit") return;
+		const first = this.#byCollider.get(pair.first);
+		const second = this.#byCollider.get(pair.second);
+		if (first === void 0 || second === void 0) return;
+		readContact(this.#world, first.collider, second.collider, this.#contact);
+		if (!this.#contact.touching) return;
+		this.#contactPoint.point.copyFrom(this.#contact.point);
+		this.#contactPoint.normal.copyFrom(this.#contact.normal);
+		this.#contactPoint.impulse = this.#contact.impulse;
+	}
+	/**
+	* Delivers one trigger callback to one entity.
+	*
+	* @param target - The binding whose scripts receive it.
+	* @param other - The other participant.
+	* @param kind - Which callback to deliver.
+	*/
+	#deliverTrigger(target, other, kind) {
+		if (target.record.entity.isDestroyed) return;
+		const event = this.#trigger ??= {
+			other: null,
+			otherCollider: null,
+			self: target.record.entity,
+			selfCollider: null
+		};
+		event.self = target.record.entity;
+		event.selfCollider = target.owner;
+		event.other = other.record.entity;
+		event.otherCollider = other.owner;
+		this.#ctx.dispatchScriptCallback(target.record.entity, kind, event);
+	}
+	/**
+	* Delivers one collision callback to one entity.
+	*
+	* @param target - The binding whose scripts receive it.
+	* @param other - The other participant.
+	* @param kind - Which callback to deliver.
+	*/
+	#deliverCollision(target, other, kind) {
+		if (target.record.entity.isDestroyed || !target.record.collisionEvents) return;
+		this.#relativeVelocity.set(target.record.preStepVelocity.x - other.record.preStepVelocity.x, target.record.preStepVelocity.y - other.record.preStepVelocity.y);
+		const collision = this.#collision ??= {
+			other: null,
+			otherCollider: null,
+			self: target.record.entity,
+			selfCollider: null,
+			contacts: this.#contacts,
+			relativeVelocity: this.#relativeVelocity
+		};
+		collision.self = target.record.entity;
+		collision.selfCollider = target.owner;
+		collision.other = other.record.entity;
+		collision.otherCollider = other.owner;
+		this.#ctx.dispatchScriptCallback(target.record.entity, kind, collision);
+	}
+	/**
+	* Whether a body's display pose is interpolated.
+	*
+	* @param rigidbody - The `Rigidbody2D`, or `null`.
+	* @param controller - The `CharacterController2D`, or `null`.
+	* @param motion - The motion type.
+	* @returns `true` when interpolation applies.
+	*/
+	#shouldInterpolate(rigidbody, controller, motion) {
+		if (!this.#settings.interpolation || motion === BodyMotion2D.static) return false;
+		if (controller !== null) return controller.interpolation === "interpolate";
+		return rigidbody !== null && rigidbody.interpolation === "interpolate";
+	}
+};
+/** How far below a one-way platform's top the character's feet may be and still land on it. */
+const ONE_WAY_TOLERANCE = .02;
+/**
+* The colliders that make up an entity's body: every enabled `Collider2D` on the entity itself.
+*
+* @param entity - The entity.
+* @returns The colliders, in component order.
+*/
+function collidersOf(entity) {
+	const found = [];
+	const components = entity.components;
+	for (let index = 0; index < components.length; index += 1) {
+		const component = components[index];
+		if (component instanceof Collider2D && component.enabled && !component.isDestroyed) found.push(component);
+	}
+	return found;
+}
+/**
+* The motion type a body takes.
+*
+* @param rigidbody - The component, or `null`.
+* @param controller - The character controller, or `null`.
+* @returns The motion type; a controller is always kinematic.
+*/
+function motionOf(rigidbody, controller) {
+	if (controller !== null) return BodyMotion2D.kinematic;
+	if (rigidbody === null || rigidbody.bodyType === "static") return BodyMotion2D.static;
+	return rigidbody.bodyType === "kinematic" ? BodyMotion2D.kinematic : BodyMotion2D.dynamic;
+}
+/**
+* How far a shape reaches above its own origin, which is what a one-way platform's top is measured
+* from.
+*
+* @param shape - The geometry.
+* @returns The half-height in metres.
+*/
+function topOf(shape) {
+	if (shape.kind === "box") return shape.halfHeight;
+	if (shape.kind === "circle") return shape.radius;
+	if (shape.kind === "capsule") return shape.halfHeight + shape.radius;
+	let top = 0;
+	for (let index = 1; index < shape.points.length; index += 2) top = Math.max(top, shape.points[index] ?? 0);
+	return top;
+}
+/**
+* Half a character controller's total height, including its caps.
+*
+* @param component - The controller.
+* @returns The half-height in metres.
+*/
+function halfHeightOf(component) {
+	return Math.max(component.radius, component.height / 2);
+}
+/**
+* The map key of one collider pair, order-independent.
+*
+* @param first - One handle.
+* @param second - The other.
+* @returns The key.
+*/
+function pairKey(first, second) {
+	return first < second ? `${String(first)}:${String(second)}` : `${String(second)}:${String(first)}`;
+}
+/**
+* The shortest signed angular difference between two angles, so interpolation never spins the long
+* way round.
+*
+* @param from - The start angle in radians.
+* @param to - The end angle in radians.
+* @returns The signed difference in `(-π, π]`.
+*/
+function shortestArc(from, to) {
+	const twoPi = Math.PI * 2;
+	return ((to - from + Math.PI) % twoPi + twoPi) % twoPi - Math.PI;
+}
+/**
+* A monotonic millisecond reading for the `stepMs` counter. It never feeds the simulation, so it
+* does not break the "no wall-clock reads" rule of `09-physics.md` §8.
+*
+* @returns Milliseconds since the process started.
+*/
+function now() {
+	return performance.now();
+}
+//#endregion
+//#region src/runtime/systems.ts
+/**
+* The three systems `docs/architecture/01-lifecycle-and-time.md` §3 step 4 and `09-physics.md` §1
+* put physics in the frame with — identical in 2D, except that Rapier is stepped directly and there
+* is no Babylon Lite simulation scene:
+*
+* ```
+* Systems(FixedUpdate, -100)  restore the authoritative pose of interpolated bodies
+* scripts.fixedUpdate(dt)     forces, velocities, CharacterController2D.move()
+* Systems(FixedUpdate,  100)  step Rapier, snapshot poses, dispatch collision and trigger events
+* Systems(PreRender,  -500)   write lerp(prev, cur, time.fixedStepAlpha)
+* ```
+*
+* Everything here is `@internal`.
+*/
+/** The `FixedUpdate` order the restore system runs at. */
+const PHYSICS_2D_RESTORE_ORDER = -100;
+/** The `PreRender` order the interpolation system runs at. */
+const PHYSICS_2D_INTERPOLATE_ORDER = -500;
+/**
+* Undoes the display pose the interpolation system wrote, so `fixedUpdate` and Rapier both see the
+* authoritative pose.
+*
+* @internal
+*/
+var Physics2DRestoreSystem = class {
+	/** The name diagnostics and error reports use. */
+	name = "physics2d-restore";
+	#host;
+	/**
+	* Binds the system to the runtime holder.
+	*
+	* @param host - The holder the runtime lands in.
+	*/
+	constructor(host) {
+		this.#host = host;
+	}
+	/** Restores every interpolated body's authoritative pose. */
+	update() {
+		this.#host.runtime?.restorePoses();
+	}
+};
+/**
+* Steps Rapier once, snapshots the poses, and dispatches the step's events.
+*
+* @internal
+*/
+var Physics2DStepSystem = class {
+	/** The name diagnostics and error reports use. */
+	name = "physics2d-step";
+	#host;
+	/**
+	* Binds the system to the runtime holder.
+	*
+	* @param host - The holder the runtime lands in.
+	*/
+	constructor(host) {
+		this.#host = host;
+	}
+	/**
+	* Runs one fixed step.
+	*
+	* @param ctx - The world, clock, phase, and fixed delta.
+	*/
+	update(ctx) {
+		this.#host.runtime?.step(ctx.dt);
+	}
+};
+/**
+* Writes the interpolated display pose once per frame.
+*
+* @internal
+*/
+var Physics2DInterpolationSystem = class {
+	/** The name diagnostics and error reports use. */
+	name = "physics2d-interpolate";
+	#host;
+	/**
+	* Binds the system to the runtime holder.
+	*
+	* @param host - The holder the runtime lands in.
+	*/
+	constructor(host) {
+		this.#host = host;
+	}
+	/**
+	* Writes `lerp(prev, cur, alpha)` into every interpolated body's transform.
+	*
+	* @param ctx - The world, clock, phase, and frame delta.
+	*/
+	update(ctx) {
+		this.#host.runtime?.interpolate(ctx.time.fixedStepAlpha);
+	}
+};
+//#endregion
+//#region src/service.ts
+/**
+* `app.physics2d` (`docs/architecture/11-2d-toolkit.md` §8, `09-physics.md` §5): gravity, the
+* queries, and the Rapier escape hatch.
+*
+* Every query is shape-accurate and reports the exact collider it hit, because Rapier's query
+* pipeline returns the `Collider` (`pipeline/world.d.ts`). The bounds-index approximations
+* `09-physics.md` §5 documents for Havok have no counterpart here.
+*/
+/** How far a ray travels when the caller names no distance, in metres. */
+const DEFAULT_RAY_DISTANCE = 1e4;
+/** Every layer bit Rapier can express. */
+const ALL_LAYERS = 65535;
+/**
+* The service behind `app.physics2d`.
+*
+* @example
+* ```ts
+* const hit = app.physics2d.raycast({ x: 0, y: 5 }, { x: 0, y: -1 }, 20);
+* if (hit !== null) {
+*   app.log.info(`ray hit ${hit.entity.name} at ${String(hit.point.y)}`);
+* }
+* ```
+*
+* @public
+*/
+var Physics2DService = class {
+	#host;
+	#gravity = new Vec2();
+	#point = new Vec2();
+	#normal = new Vec2();
+	#rayResult = {
+		hit: false,
+		collider: null,
+		distance: 0
+	};
+	#sweepResult = {
+		hit: false,
+		collider: null,
+		distance: 0
+	};
+	#hits = [];
+	#overlaps = [];
+	/**
+	* Wraps the holder the extension fills in from `onStart`.
+	*
+	* @param host - The holder the runtime lands in.
+	* @param settings - The resolved `physics2d` settings section.
+	*
+	* @internal
+	*/
+	constructor(host, settings) {
+		this.#host = host;
+		this.#gravity.set(settings.gravity.x, settings.gravity.y);
+	}
+	/**
+	* World gravity in metres per second squared.
+	*
+	* @returns A live view; writing to it does nothing, assign the property instead.
+	*/
+	get gravity() {
+		return this.#gravity;
+	}
+	/**
+	* Replaces world gravity, which every body feels from the next fixed step.
+	*
+	* @param value - The new acceleration vector.
+	*/
+	set gravity(value) {
+		this.#gravity.set(value.x, value.y);
+		this.#rt().setGravity(this.#gravity);
+	}
+	/**
+	* The Rapier handles.
+	*
+	* @returns The world.
+	*/
+	get rapier() {
+		return { world: this.#rt().world };
+	}
+	/**
+	* Casts a ray and returns the first entity it hits.
+	*
+	* @param origin - The world-space origin, in metres.
+	* @param direction - The direction; it is normalised for you.
+	* @param maxDistance - How far to travel; defaults to 10 km.
+	* @param options - Layer mask and trigger behaviour.
+	* @returns The hit, or `null` when the ray clears everything.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	*/
+	raycast(origin, direction, maxDistance = DEFAULT_RAY_DISTANCE, options) {
+		this.#requireStep("raycast");
+		const unit = normalize(direction);
+		if (unit === null) return null;
+		castRay(this.#rt().world, origin, unit, maxDistance, groupsOf(options), options?.hitTriggers === true, this.#point, this.#normal, this.#rayResult);
+		return this.#toHit(this.#rayResult.collider, this.#rayResult.distance, this.#point, this.#normal);
+	}
+	/**
+	* Casts a ray and returns every entity along it, nearest first.
+	*
+	* @param origin - The world-space origin.
+	* @param direction - The direction; it is normalised for you.
+	* @param maxDistance - How far to travel; defaults to 10 km.
+	* @param options - Layer mask and trigger behaviour.
+	* @returns The hits, in increasing distance. The array is reused between calls.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	*/
+	raycastAll(origin, direction, maxDistance = DEFAULT_RAY_DISTANCE, options) {
+		this.#requireStep("raycastAll");
+		this.#hits.length = 0;
+		const unit = normalize(direction);
+		if (unit === null) return this.#hits;
+		const runtime = this.#rt();
+		castRayAll(runtime.world, origin, unit, maxDistance, groupsOf(options), options?.hitTriggers === true, (collider, distance, normalX, normalY) => {
+			const binding = runtime.bindingOf(collider);
+			if (binding === null) return;
+			this.#hits.push({
+				entity: binding.record.entity,
+				collider: binding.owner,
+				point: new Vec2(origin.x + unit.x * distance, origin.y + unit.y * distance),
+				normal: new Vec2(normalX, normalY),
+				distance
+			});
+		});
+		this.#hits.sort(byDistance);
+		return this.#hits;
+	}
+	/**
+	* Lists the entities a circle overlaps.
+	*
+	* @param centre - The circle's world position.
+	* @param radius - Its radius in metres.
+	* @param options - Layer mask and trigger behaviour.
+	* @returns The overlapping entities, in Rapier's order. The array is reused between calls.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	*/
+	overlapCircle(centre, radius, options) {
+		return this.#overlap({
+			kind: "circle",
+			radius
+		}, centre, 0, options, "overlapCircle");
+	}
+	/**
+	* Lists the entities a box overlaps.
+	*
+	* @param centre - The box's world position.
+	* @param size - Its full width and height in metres.
+	* @param rotation - Its rotation in degrees counter-clockwise; defaults to `0`.
+	* @param options - Layer mask and trigger behaviour.
+	* @returns The overlapping entities. The array is reused between calls.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	*/
+	overlapBox(centre, size, rotation = 0, options) {
+		return this.#overlap({
+			kind: "box",
+			halfWidth: size.x / 2,
+			halfHeight: size.y / 2
+		}, centre, toRadians(rotation), options, "overlapBox");
+	}
+	/**
+	* Sweeps a circle and returns the first contact.
+	*
+	* @param centre - Where the sweep starts.
+	* @param radius - The circle's radius in metres.
+	* @param direction - The sweep direction; it is normalised for you.
+	* @param maxDistance - How far to sweep.
+	* @param options - Layer mask and trigger behaviour.
+	* @returns The hit, or `null`.
+	* @throws IgnifxError with code `IGX-1153` when no fixed step has run yet.
+	*/
+	shapeCast(centre, radius, direction, maxDistance, options) {
+		this.#requireStep("shapeCast");
+		const unit = normalize(direction);
+		if (unit === null) return null;
+		castShape(this.#rt().world, {
+			kind: "circle",
+			radius
+		}, centre, 0, unit, maxDistance, groupsOf(options), options?.hitTriggers === true, this.#point, this.#normal, this.#sweepResult);
+		const binding = this.#rt().bindingOf(this.#sweepResult.collider);
+		if (!this.#sweepResult.hit || binding === null) return null;
+		return {
+			entity: binding.record.entity,
+			collider: binding.owner,
+			point: this.#point.clone(),
+			normal: this.#normal.clone(),
+			distance: this.#sweepResult.distance,
+			fraction: maxDistance > 0 ? this.#sweepResult.distance / maxDistance : 0
+		};
+	}
+	/**
+	* Runs one overlap query.
+	*
+	* @param shape - The query geometry.
+	* @param centre - Its world position.
+	* @param rotation - Its rotation in radians.
+	* @param options - Layer mask and trigger behaviour.
+	* @param name - The query name, for the diagnostic.
+	* @returns The overlapping entities.
+	*/
+	#overlap(shape, centre, rotation, options, name) {
+		this.#requireStep(name);
+		this.#overlaps.length = 0;
+		const runtime = this.#rt();
+		overlapShape(runtime.world, shape, centre, rotation, groupsOf(options), options?.hitTriggers === true, (collider) => {
+			const entity = runtime.bindingOf(collider)?.record.entity ?? null;
+			if (entity !== null && !this.#overlaps.includes(entity)) this.#overlaps.push(entity);
+		});
+		return this.#overlaps;
+	}
+	/**
+	* Turns a Rapier collider and a distance into a public hit.
+	*
+	* @param collider - The collider that was hit, or `null`.
+	* @param distance - How far away it was.
+	* @param point - The contact point.
+	* @param normal - The contact normal.
+	* @returns The hit, or `null`.
+	*/
+	#toHit(collider, distance, point, normal) {
+		const binding = this.#rt().bindingOf(collider);
+		if (binding === null) return null;
+		return {
+			entity: binding.record.entity,
+			collider: binding.owner,
+			point: point.clone(),
+			normal: normal.clone(),
+			distance
+		};
+	}
+	/**
+	* The runtime, once `onStart` has built it.
+	*
+	* @returns The runtime.
+	* @throws IgnifxError with code `IGX-1150` when Rapier has not finished loading.
+	*/
+	#rt() {
+		const runtime = this.#host.runtime;
+		if (runtime === null) throw physics2DError(Physics2DErrorCode.rapierUnavailable, "The 2D physics world does not exist yet.", { hint: "app.physics2d is usable from the first frame onwards; await app.start() first." });
+		return runtime;
+	}
+	/**
+	* Refuses a query that ran before Rapier built its broadphase (spike S6.2).
+	*
+	* @param query - The query name, for the diagnostic.
+	* @throws IgnifxError with code `IGX-1153` when no step has completed.
+	*/
+	#requireStep(query) {
+		if (this.#rt().hasStepped) return;
+		throw physics2DError(Physics2DErrorCode.queryBeforeStep, `${query}() ran before the first fixed step.`, {
+			context: { query },
+			hint: "Step the app at least once (app.step(1 / 60)) before querying; Rapier builds its broadphase in the first step."
+		});
+	}
+};
+/**
+* The packed interaction word a query filters with: it belongs to every layer and collides with the
+* layers the caller named.
+*
+* @param options - The query options.
+* @returns The packed word.
+*/
+function groupsOf(options) {
+	const mask = options?.layerMask?.bits ?? ALL_LAYERS;
+	return interactionGroups(ALL_LAYERS, mask & ALL_LAYERS);
+}
+/**
+* Normalises a direction.
+*
+* @param direction - The direction.
+* @returns A fresh unit vector, or `null` when the direction is zero.
+*/
+function normalize(direction) {
+	const length = Math.hypot(direction.x, direction.y);
+	return length === 0 ? null : {
+		x: direction.x / length,
+		y: direction.y / length
+	};
+}
+/**
+* Orders two hits by distance.
+*
+* @param first - One hit.
+* @param second - The other.
+* @returns A negative number when `first` is nearer.
+*/
+function byDistance(first, second) {
+	return first.distance - second.distance;
+}
+//#endregion
+//#region src/settings.ts
+/**
+* The `physics2d` project settings section (`docs/architecture/11-2d-toolkit.md` §8,
+* `09-physics.md` §6). It mirrors the 3D `physics` section with a 2D gravity vector and Rapier's
+* solver knob in place of Havok's world velocity clamps, which Rapier has no equivalent of.
+*
+* `fixedDeltaTime` is **not** here: the fixed step is shared with the core `time` section and the
+* extension reads it from `app.time.fixedDeltaTime` on every step.
+*/
+/**
+* The section name as it appears in `ignifx.config.ts`.
+*
+* @public
+*/
+const PHYSICS_2D_SETTINGS_SECTION = "physics2d";
+/** Standard gravity in the 2D plane. */
+const DEFAULT_GRAVITY = Object.freeze({
+	x: 0,
+	y: -9.81
+});
+/** The default surface: ordinary friction, no bounce — the same numbers the 3D section uses. */
+const DEFAULT_MATERIAL = Object.freeze({
+	friction: .6,
+	restitution: 0
+});
+/** An empty matrix, which means "everything collides with everything". */
+const DEFAULT_COLLISION_MATRIX = Object.freeze({});
+/**
+* Builds the schema the `physics2d` section is validated against.
+*
+* @remarks
+* It is a function, not a module-level constant: every field kind is a function call, and module
+* scope holds declarations and immutable constants only (`CONSTITUTION.md` §3.5).
+*
+* @returns The schema.
+*
+* @public
+*/
+function physics2DSettingsSchema() {
+	return defineSchema({
+		gravity: vec2(DEFAULT_GRAVITY),
+		collisionMatrix: map(array(str())),
+		defaultMaterial: record({
+			friction: f32(DEFAULT_MATERIAL.friction, { min: 0 }),
+			restitution: f32(DEFAULT_MATERIAL.restitution, {
+				min: 0,
+				max: 1
+			})
+		}),
+		velocityIterations: u32(0),
+		interpolation: bool(true)
+	});
+}
+/**
+* The values used when a project omits the `physics2d` section.
+*
+* @returns A fresh defaults object.
+*
+* @public
+*/
+function defaultPhysics2DSettings() {
+	return {
+		gravity: DEFAULT_GRAVITY,
+		collisionMatrix: DEFAULT_COLLISION_MATRIX,
+		defaultMaterial: DEFAULT_MATERIAL,
+		velocityIterations: 0,
+		interpolation: true
+	};
+}
+//#endregion
+//#region src/extension.ts
+/**
+* Builds the 2D physics extension.
+*
+* @param options - Optionally, an already-instantiated Rapier module.
+* @returns The extension descriptor.
+*
+* @example
+* ```ts
+* const app = await createApp({ headless: true, extensions: [physics2d()] });
+* ```
+*
+* @public
+*/
+const physics2d = defineExtension((options = {}) => {
+	const host = new Physics2DHost();
+	let context = null;
+	return {
+		name: "@ignifx/physics-2d",
+		version: "0.0.0",
+		engine: ">=0.0.0 <1.0.0",
+		requires: [],
+		optional: ["@ignifx/2d", "@ignifx/devtools"],
+		register(ctx) {
+			context = ctx;
+			ctx.registerErrorCodes(PHYSICS_2D_ERROR_MESSAGES);
+			ctx.registerSettings(PHYSICS_2D_SETTINGS_SECTION, physics2DSettingsSchema(), defaultPhysics2DSettings());
+			ctx.registerComponents(PHYSICS_2D_COMPONENTS);
+			ctx.registerAssetLoader(createPhysicsMaterial2DLoader());
+			const settings = ctx.settings(PHYSICS_2D_SETTINGS_SECTION);
+			const service = new Physics2DService(host, settings);
+			ctx.registerService(Physics2DHostKey, host);
+			ctx.registerService(Physics2DService, service);
+			ctx.defineAppProperty("physics2d", () => service);
+			ctx.registerSystem(new Physics2DRestoreSystem(host), {
+				phase: Phase.FixedUpdate,
+				order: PHYSICS_2D_RESTORE_ORDER
+			});
+			ctx.registerSystem(new Physics2DStepSystem(host), {
+				phase: Phase.FixedUpdate,
+				order: 100
+			});
+			ctx.registerSystem(new Physics2DInterpolationSystem(host), {
+				phase: Phase.PreRender,
+				order: PHYSICS_2D_INTERPOLATE_ORDER
+			});
+		},
+		async onStart(app) {
+			const ctx = context;
+			if (ctx === null) return;
+			if (app.world.lite.simulationScene !== null) throw physics2DError(Physics2DErrorCode.bothPhysicsExtensions, "A world uses either physics() or physics2d(), and this one registered both.", {
+				context: { extension: "@ignifx/physics-2d" },
+				hint: "Remove physics() from a 2D game, or physics2d() from a 3D one."
+			});
+			const settings = ctx.settings(PHYSICS_2D_SETTINGS_SECTION);
+			const initialize = options.initialize ?? defaultInitialize;
+			try {
+				await initialize();
+			} catch (cause) {
+				throw physics2DError(Physics2DErrorCode.rapierUnavailable, "The Rapier 2D WebAssembly module could not be instantiated.", {
+					cause,
+					hint: "Reinstall @dimforge/rapier2d-compat; its WebAssembly is inlined and needs no serving."
+				});
+			}
+			const world = createWorld(settings.gravity);
+			const counters = app.diagnostics.registerGroup(PHYSICS_2D_DIAGNOSTICS_GROUP, PHYSICS_2D_DIAGNOSTICS_COUNTERS);
+			host.runtime = new Physics2DRuntime({
+				ctx,
+				settings,
+				world,
+				counters
+			});
+			seedExistingBodies(app, host);
+		},
+		dispose() {
+			host.runtime?.dispose();
+			host.runtime = null;
+			context = null;
+		}
+	};
+});
+/**
+* Instantiates Rapier's WebAssembly module, which is what `Physics2DOptions.initialize` replaces.
+*
+* @returns A promise that settles once Rapier is usable.
+*/
+async function defaultInitialize() {
+	await loadRapier();
+}
+/** Every component this extension registers, in a stable order. */
+const PHYSICS_2D_COMPONENTS = Object.freeze([
+	Rigidbody2D,
+	BoxCollider2D,
+	CircleCollider2D,
+	CapsuleCollider2D,
+	PolygonCollider2D,
+	EdgeCollider2D,
+	TilemapCollider2D,
+	CharacterController2D
+]);
+/** The collider classes the seed pass walks, in registration order. */
+const COLLIDER_2D_TYPES = Object.freeze([
+	BoxCollider2D,
+	CircleCollider2D,
+	CapsuleCollider2D,
+	PolygonCollider2D,
+	EdgeCollider2D,
+	TilemapCollider2D
+]);
+/**
+* Marks every collider and controller that already exists when the runtime is built.
+*
+* @remarks
+* A component attached before `onStart` — from a scene the `assets.preload` list pulled in, say —
+* called `markDirty` while the runtime was still `null`. This is the catch-up pass that makes those
+* bodies exist, and it walks the component store in registration order so body creation order stays
+* deterministic (`09-physics.md` §8).
+*
+* @param app - The app being started.
+* @param host - The holder the runtime landed in.
+*/
+function seedExistingBodies(app, host) {
+	const runtime = host.runtime;
+	if (runtime === null) return;
+	for (const type of COLLIDER_2D_TYPES) {
+		const components = app.world.components(type);
+		for (let index = 0; index < components.length; index += 1) {
+			const collider = components[index];
+			if (collider !== void 0) runtime.markDirty(collider.entity);
+		}
+	}
+	const controllers = app.world.components(CharacterController2D);
+	for (let index = 0; index < controllers.length; index += 1) {
+		const controller = controllers[index];
+		if (controller !== void 0) runtime.markDirty(controller.entity);
+	}
+}
+//#endregion
+//#region src/schemas.ts
+/**
+* The documentation harness's view of everything `@ignifx/physics-2d` declares
+* (`docs/architecture/16-docs-harness-and-skill.md` §3, `scripts/README.md`).
+*
+* The `ignifx.physicsmaterial` **file format** is deliberately absent: `@ignifx/physics` already
+* documents it and this package reads the very same document (`material.ts`), so describing it
+* twice would render the same table on the formats page twice — the harness keeps the first
+* declaration and drops the rest (`scripts/lib/schema-source.ts`).
+*/
+/**
+* Describes every component this package declares.
+*
+* @returns The records, keyed by namespaced type id.
+*
+* @example
+* ```ts
+* const schemas = describeSchemas();
+* schemas["ignifx/Rigidbody2D"].fields["mass"].default; // 1
+* ```
+*
+* @public
+*/
+function describeSchemas() {
+	return {
+		"ignifx/Rigidbody2D": describeSchema("ignifx/Rigidbody2D", Rigidbody2D.schema, { description: "Makes an entity's 2D colliders a dynamic, kinematic, or static Rapier body." }),
+		"ignifx/BoxCollider2D": describeSchema("ignifx/BoxCollider2D", BoxCollider2D.schema, { description: "An axis-aligned box, sized in local metres and scaled by the entity." }),
+		"ignifx/CircleCollider2D": describeSchema("ignifx/CircleCollider2D", CircleCollider2D.schema, { description: "A circle; the larger scale axis wins." }),
+		"ignifx/CapsuleCollider2D": describeSchema("ignifx/CapsuleCollider2D", CapsuleCollider2D.schema, { description: "A capsule standing along X or Y." }),
+		"ignifx/PolygonCollider2D": describeSchema("ignifx/PolygonCollider2D", PolygonCollider2D.schema, { description: "The convex hull of a point list, in local metres." }),
+		"ignifx/EdgeCollider2D": describeSchema("ignifx/EdgeCollider2D", EdgeCollider2D.schema, { description: "An open chain of line segments — a platformer's ground contour." }),
+		"ignifx/TilemapCollider2D": describeSchema("ignifx/TilemapCollider2D", TilemapCollider2D.schema, { description: "The merged collision surface of a Tilemap, rebuilt when its tiles change." }),
+		"ignifx/CharacterController2D": describeSchema("ignifx/CharacterController2D", CharacterController2D.schema, { description: "A kinematic character with collide-and-slide, slopes, autostep, and snap-to-ground." })
+	};
+}
+//#endregion
+export { BODY_TYPES_2D, BoxCollider2D, CAPSULE_DIRECTIONS_2D, CHARACTER_SHAPES_2D, COLLISION_EVENT_MODES_2D, COMBINE_RULES, CapsuleCollider2D, CharacterController2D, CircleCollider2D, Collider2D, EdgeCollider2D, INTERPOLATION_MODES_2D, PHYSICS_2D_DIAGNOSTICS_COUNTERS, PHYSICS_2D_DIAGNOSTICS_GROUP, PHYSICS_2D_ERROR_MESSAGES, PHYSICS_2D_SETTINGS_SECTION, PHYSICS_MATERIAL_2D_ASSET_TYPE, PHYSICS_MATERIAL_2D_FILE_EXTENSION, PHYSICS_MATERIAL_2D_FILE_FORMAT, PHYSICS_MATERIAL_2D_FORMAT_VERSION, Physics2DErrorCode, Physics2DService, PhysicsMaterial2D, PolygonCollider2D, Rigidbody2D, TilemapCollider2D, collider2DFields, createPhysicsMaterial2DLoader, defaultPhysics2DSettings, describeSchemas, parsePhysicsMaterial2D, physics2DError, physics2DSettingsSchema, physics2d };
+
+//# sourceMappingURL=index.js.map