@ignifx/physics-2d 0.0.0 → 0.2.0

package/dist/index.d.ts

@@ -1 +1,1686 @@
-export {}
+import { AssetHandle, AssetLoader, Component, ComponentHooks, DiagnosticsGroup, Disconnect, Entity, ErrorContext, Extension, ExtensionContext, IgnifxError, JsonValue, LayerMask, MutableVec2, Schema, SchemaDescription, Signal, Vec2, Vec2Like } from "@ignifx/core";
+import { Collider, EventQueue, RigidBody, World } from "@dimforge/rapier2d-compat";
+import { TilemapCollisionData } from "@ignifx/2d";
+//#region src/settings.d.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
+ */
+export declare const PHYSICS_2D_SETTINGS_SECTION = "physics2d";
+/**
+ * A surface, either as the `physics2d.defaultMaterial` setting or inline on a collider.
+ *
+ * @public
+ */
+interface Physics2DMaterialValues {
+  /** The friction coefficient. */
+  readonly friction: number;
+  /** How much of the approach speed is returned, `0` to `1`. */
+  readonly restitution: number;
+}
+/**
+ * The resolved `physics2d` settings section.
+ *
+ * @example
+ * ```ts
+ * // ignifx.config.ts
+ * export default {
+ *   layers: { layers: ["Default", "Player", "Enemy"] },
+ *   physics2d: {
+ *     gravity: { x: 0, y: -9.81 },
+ *     collisionMatrix: { Player: ["Default", "Enemy"], Enemy: ["Default"] },
+ *   },
+ * };
+ * ```
+ *
+ * @public
+ */
+interface Physics2DSettings {
+  /** World gravity in metres per second squared; +Y is up (`11-2d-toolkit.md` §3). */
+  readonly gravity: Vec2Like;
+  /**
+   * Which layers each layer collides with. A layer the map does not mention collides with
+   * everything, which is what makes the default project need no matrix at all.
+   */
+  readonly collisionMatrix: Readonly<Record<string, readonly string[]>>;
+  /** The surface a collider with no material of its own uses. */
+  readonly defaultMaterial: Physics2DMaterialValues;
+  /** How many iterations Rapier's constraint solver runs; `0` leaves Rapier's own default (4). */
+  readonly velocityIterations: number;
+  /** Whether dynamic bodies and character controllers interpolate between fixed steps. */
+  readonly interpolation: boolean;
+}
+/**
+ * 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
+ */
+export declare function physics2DSettingsSchema(): Schema;
+/**
+ * The values used when a project omits the `physics2d` section.
+ *
+ * @returns A fresh defaults object.
+ *
+ * @public
+ */
+export declare function defaultPhysics2DSettings(): Physics2DSettings;
+//#endregion
+//#region src/material.d.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
+ */
+export declare const PHYSICS_MATERIAL_2D_ASSET_TYPE = "physicsmaterial";
+/**
+ * The address suffix that selects the loader.
+ *
+ * @public
+ */
+export declare const PHYSICS_MATERIAL_2D_FILE_EXTENSION = ".physicsmaterial.json";
+/**
+ * The `format` string every physics-material document declares.
+ *
+ * @public
+ */
+export declare const PHYSICS_MATERIAL_2D_FILE_FORMAT = "ignifx.physicsmaterial";
+/**
+ * The file format version; `1` before ignifx 1.0.
+ *
+ * @public
+ */
+export declare 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
+ */
+export declare class PhysicsMaterial2D implements Physics2DMaterialValues {
+  /** The asset type token, so `asset(PhysicsMaterial2D)` fields resolve. */
+  static assetType: string;
+  /** A human-readable name, used in diagnostics. */
+  readonly name: string;
+  /** The friction coefficient. */
+  readonly friction: number;
+  /** How much of the approach speed is returned, `0` to `1`. */
+  readonly restitution: number;
+  /**
+   * Wraps parsed values.
+   *
+   * @param name - A human-readable name.
+   * @param values - Friction and restitution.
+   */
+  constructor(name: string, values: Physics2DMaterialValues);
+  /**
+   * 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: string, values: Partial<Physics2DMaterialValues>): PhysicsMaterial2D;
+}
+/**
+ * Builds the loader for `.physicsmaterial.json` files.
+ *
+ * @returns The loader, ready for `ctx.registerAssetLoader`.
+ *
+ * @public
+ */
+export declare function createPhysicsMaterial2DLoader(): AssetLoader<PhysicsMaterial2D>;
+/**
+ * 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
+ */
+export declare function parsePhysicsMaterial2D(address: string, document: JsonValue): PhysicsMaterial2D;
+//#endregion
+//#region src/lite/rapier/world.d.ts
+/**
+ * The Rapier 2D adapter (`docs/architecture/11-2d-toolkit.md` §8, ADR-0006). Everything the runtime
+ * needs from `@dimforge/rapier2d-compat` is a function here, so the rest of `src/` never imports the
+ * backend (`ignifx/no-lite-outside-adapter`, coding standards §4).
+ *
+ * ## Facts measured against `@dimforge/rapier2d-compat@0.20.0` (spike S6.2)
+ *
+ * - **The broadphase is only built by `World.step`.** Before the first step, `castRay` returns
+ *   `null` and `KinematicCharacterController.computeColliderMovement` reports the full requested
+ *   motion with no obstacles; a collider created after the last step is invisible until the next
+ *   one. {@link primeWorld} runs a zero-length step, which builds the broadphase without
+ *   integrating — but it is *not* free of side effects on a running simulation (a settled pile
+ *   hashes differently), so the runtime primes only when the collider set changed.
+ * - **`InteractionGroups` is one 32-bit number**: membership in the high 16 bits, filter in the low
+ *   16 (`geometry/interaction_groups.d.ts`). Sixteen layers, not thirty-two.
+ * - **`ActiveCollisionTypes.DEFAULT` excludes non-dynamic pairs**, so a kinematic character never
+ *   reports entering a static sensor. Colliders that want events are given
+ *   `ActiveCollisionTypes.ALL`.
+ */
+/**
+ * Rapier's physics world.
+ *
+ * @internal
+ */
+type RapierWorld = World;
+/**
+ * One Rapier rigid body.
+ *
+ * @internal
+ */
+type RapierBody = RigidBody;
+/**
+ * One Rapier collider.
+ *
+ * @internal
+ */
+type RapierCollider = Collider;
+/**
+ * How a body moves, in the three flavours ignifx exposes.
+ *
+ * @internal
+ */
+declare const BodyMotion2D: {
+  /** Simulated by the solver. */
+  readonly dynamic: "dynamic";
+  /** Moved by the game, pushes dynamic bodies, ignores forces. */
+  readonly kinematic: "kinematic";
+  /** Never moves. */
+  readonly static: "static";
+};
+/**
+ * The union of {@link BodyMotion2D}.
+ *
+ * @internal
+ */
+type BodyMotion2D = (typeof BodyMotion2D)[keyof typeof BodyMotion2D];
+/**
+ * A collision shape, described in metres in the body's local frame.
+ *
+ * @internal
+ */
+type RapierShape2D = {
+  readonly kind: "box";
+  readonly halfWidth: number;
+  readonly halfHeight: number;
+} | {
+  readonly kind: "circle";
+  readonly radius: number;
+} | {
+  readonly kind: "capsule";
+  readonly halfHeight: number;
+  readonly radius: number;
+} | {
+  readonly kind: "polygon";
+  readonly points: Float32Array;
+} | {
+  readonly kind: "polyline";
+  readonly points: Float32Array;
+};
+//#endregion
+//#region src/components/collider.d.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
+ */
+export declare const COMBINE_RULES: readonly ["average", "min", "multiply", "max"];
+/**
+ * The union of {@link COMBINE_RULES}.
+ *
+ * @public
+ */
+type CombineRule = (typeof COMBINE_RULES)[number];
+/**
+ * One Rapier shape a collider stands for, positioned in the body's local frame.
+ *
+ * @internal
+ */
+interface CollectedShape2D {
+  /** The geometry. */
+  readonly shape: RapierShape2D;
+  /** Where it sits relative to the entity origin, in metres. */
+  readonly offset: Vec2Like;
+  /** How it is turned about that point, in radians counter-clockwise. */
+  readonly rotation: number;
+  /** Whether it is solid only when a character controller comes down onto it. */
+  readonly oneWay: boolean;
+}
+/**
+ * The fields every 2D collider declares.
+ *
+ * @returns The shared field declarations, ready to spread into a collider's own schema.
+ *
+ * @public
+ */
+export declare function collider2DFields(): Schema;
+/**
+ * The base class of every 2D collider.
+ *
+ * @public
+ */
+export declare abstract class Collider2D extends Component implements ComponentHooks {
+  /** Several colliders on one entity make one compound body. */
+  static allowMultiple: boolean;
+  /** The shape's offset from the entity origin, in local metres. */
+  offset: Vec2Like;
+  /** When `true` the shape reports overlaps and resolves no contacts. */
+  isTrigger: boolean;
+  /** A `.physicsmaterial.json` reference; wins over {@link Collider2D.inlineMaterial}. */
+  material: AssetHandle<PhysicsMaterial2D> | null;
+  /** An inline surface, used when {@link Collider2D.material} is `null`. */
+  inlineMaterial: Physics2DMaterialValues | null;
+  /** How this surface's friction combines with the one it touches. */
+  frictionCombine: CombineRule;
+  /** How this surface's restitution combines with the one it touches. */
+  restitutionCombine: CombineRule;
+  /**
+   * Whether this is a one-way platform: a `CharacterController2D` with
+   * `onOneWayPlatforms` passes up through it and lands on it coming down. Rigid bodies are
+   * unaffected — one-way support is a character-controller feature in the MVP.
+   */
+  oneWay: boolean;
+  /** The name of the layer this collider filters as, or `""` to use `entity.layer`. */
+  layerOverride: string;
+  /** Applies the shared defaults. A concrete collider calls `super()` and then applies its own. */
+  constructor();
+  /** Marks the entity's body for a rebuild at the start of the next fixed step. */
+  onAttach(): void;
+  /** Marks the entity's body for a rebuild, which removes this collider from it. */
+  onDetach(): void;
+  /**
+   * 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(): void;
+  /**
+   * 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: Physics2DMaterialValues): Physics2DMaterialValues;
+  /**
+   * Appends the Rapier shapes this collider stands for.
+   *
+   * @param scale - The entity's lossy scale in the 2D plane.
+   * @param out - The list to append to.
+   *
+   * @internal
+   */
+  abstract collectShapes(scale: Vec2Like, out: CollectedShape2D[]): void;
+}
+//#endregion
+//#region src/events.d.ts
+/**
+ * The payloads the five physics callbacks receive in 2D (`docs/architecture/11-2d-toolkit.md` §8,
+ * `09-physics.md` §4).
+ *
+ * ## The callbacks are the 3D names
+ *
+ * `11-2d-toolkit.md` §8 writes them as `onCollisionEnter2D`/`onTriggerEnter2D`. The kernel's
+ * `PhysicsCallbackName` union has five members and no `2D` variants
+ * (`packages/core/src/lifecycle/callbacks.ts`), and a world uses either `physics()` or
+ * `physics2d()` — never both, which is what `IGX-1101` enforces. So a 2D game implements
+ * `onCollisionEnter`, `onCollisionStay`, `onCollisionExit`, `onTriggerEnter`, and `onTriggerExit`,
+ * and receives the 2D payloads below. §8 is corrected accordingly.
+ *
+ * ## Identities are native
+ *
+ * Rapier reports **both** colliders of every event (`pipeline/event_queue.d.ts`,
+ * `drainCollisionEvents`), so `other` is never `null` for a live body and the ADR-0013 waiver that
+ * 3D physics needs has no counterpart here.
+ *
+ * Every payload is **pooled**: the same instances are reused for every event of a step, so a script
+ * that needs a value after its callback returns must copy it out (coding standards §7).
+ */
+/**
+ * One contact point of a 2D collision. Pooled with its owning {@link Collision2D}.
+ *
+ * @public
+ */
+interface ContactPoint2D {
+  /** The world-space contact point, in metres. */
+  readonly point: Vec2Like;
+  /** The world-space contact normal, pointing away from the other collider. */
+  readonly normal: Vec2Like;
+  /** The magnitude of the impulse Rapier's solver applied; `0` for a contact that just ended. */
+  readonly impulse: number;
+}
+/**
+ * What a script's `onTriggerEnter`/`onTriggerExit` is handed in a 2D world.
+ *
+ * @example
+ * ```ts
+ * class Coin extends Script implements ScriptCallbacks {
+ *   static typeId = "mygame/Coin";
+ *   onTriggerEnter(trigger: TriggerEvent2D): void {
+ *     if (trigger.other?.tags.has("player") === true) {
+ *       this.entity.destroy();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+interface TriggerEvent2D {
+  /** The entity that entered or left, or `null` when its body is already gone. */
+  readonly other: Entity | null;
+  /** The exact collider on the other entity — Rapier reports shape identity, unlike Havok. */
+  readonly otherCollider: Collider2D | null;
+  /** The entity whose script is being called. */
+  readonly self: Entity;
+  /** The collider on this entity that took part. */
+  readonly selfCollider: Collider2D | null;
+}
+/**
+ * What a script's `onCollisionEnter`/`onCollisionStay`/`onCollisionExit` is handed in a 2D world.
+ *
+ * @public
+ */
+interface Collision2D {
+  /** The entity that was hit, or `null` when its body is already gone. */
+  readonly other: Entity | null;
+  /** The exact collider on the other entity. */
+  readonly otherCollider: Collider2D | null;
+  /** The entity whose script is being called. */
+  readonly self: Entity;
+  /** The collider on this entity that took part. */
+  readonly selfCollider: Collider2D | null;
+  /** The contacts of this event. Pooled; valid only during the callback. */
+  readonly contacts: readonly ContactPoint2D[];
+  /** The relative velocity of the two bodies at the contact, in metres per second. */
+  readonly relativeVelocity: Vec2Like;
+}
+/**
+ * What `CharacterController2D.onCollided` reports: one obstacle the character hit this step.
+ *
+ * @public
+ */
+interface CharacterCollision2D {
+  /** The entity that was hit, or `null` when it is not an ignifx body. */
+  readonly other: Entity | null;
+  /** The collider that was hit, or `null`. */
+  readonly otherCollider: Collider2D | null;
+  /** The world-space contact point. */
+  readonly point: Vec2Like;
+  /** The world-space outward normal on the obstacle. */
+  readonly normal: Vec2Like;
+}
+//#endregion
+//#region src/components/rigidbody.d.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
+ */
+export declare const BODY_TYPES_2D: readonly ["dynamic", "kinematic", "static"];
+/**
+ * The union of {@link BODY_TYPES_2D}.
+ *
+ * @public
+ */
+type BodyType2D = (typeof BODY_TYPES_2D)[number];
+/**
+ * Whether a body's display pose is interpolated between fixed steps.
+ *
+ * @public
+ */
+export declare const INTERPOLATION_MODES_2D: readonly ["none", "interpolate"];
+/**
+ * The union of {@link INTERPOLATION_MODES_2D}.
+ *
+ * @public
+ */
+type InterpolationMode2D = (typeof INTERPOLATION_MODES_2D)[number];
+/**
+ * Whether collision callbacks are delivered for this body.
+ *
+ * @public
+ */
+export declare const COLLISION_EVENT_MODES_2D: readonly ["auto", "on", "off"];
+/**
+ * The union of {@link COLLISION_EVENT_MODES_2D}.
+ *
+ * @public
+ */
+type CollisionEventMode2D = (typeof COLLISION_EVENT_MODES_2D)[number];
+/**
+ * The Rapier objects a `Rigidbody2D` owns. Unstable escape hatch
+ * (`docs/architecture/00-overview.md` §3).
+ *
+ * @public
+ */
+interface Rigidbody2DRapierHandles {
+  /** The Rapier body, or `null` before the first fixed step has built it. */
+  readonly body: RapierBody | null;
+}
+/**
+ * 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
+ */
+export declare class Rigidbody2D extends Component implements ComponentHooks {
+  #private;
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** One body per entity. */
+  static allowMultiple: boolean;
+  /** The serialized field declarations (ADR-0004). */
+  static schema: Schema;
+  bodyType: BodyType2D;
+  mass: number;
+  gravityScale: number;
+  linearDamping: number;
+  angularDamping: number;
+  freezeRotation: boolean;
+  interpolation: InterpolationMode2D;
+  collisionEvents: CollisionEventMode2D;
+  /** Applies the schema defaults, exactly as `Component.define` would. */
+  constructor();
+  /** Marks the entity's body for a rebuild at the start of the next fixed step. */
+  onAttach(): void;
+  /** Marks the entity's body for a rebuild, which turns it back into an implicit static body. */
+  onDetach(): void;
+  /**
+   * 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(): void;
+  /**
+   * The Rapier handles this component owns.
+   *
+   * @returns The body, or `null` before the first fixed step built it.
+   */
+  get rapier(): Rigidbody2DRapierHandles;
+  /**
+   * The body's linear velocity in metres per second.
+   *
+   * @returns A freshly allocated vector; use {@link Rigidbody2D.linearVelocityToRef} in hot code.
+   */
+  get linearVelocity(): Vec2;
+  /**
+   * Replaces the body's linear velocity.
+   *
+   * @param value - Metres per second, world space.
+   */
+  set linearVelocity(value: Vec2Like);
+  /**
+   * Reads the linear velocity without allocating.
+   *
+   * @param out - The vector to write.
+   * @returns `out`.
+   */
+  linearVelocityToRef(out: MutableVec2): MutableVec2;
+  /**
+   * The body's angular velocity.
+   *
+   * @returns Degrees per second, counter-clockwise — the same unit as `Transform.rotation2D`.
+   */
+  get angularVelocity(): number;
+  /**
+   * Replaces the body's angular velocity.
+   *
+   * @param value - Degrees per second, counter-clockwise.
+   */
+  set angularVelocity(value: number);
+  /**
+   * The mass Rapier computed for the body, in kilograms.
+   *
+   * @returns The mass, or `0` before the body exists.
+   */
+  get computedMass(): number;
+  /**
+   * 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: Vec2Like, point?: Vec2Like): void;
+  /**
+   * Applies an instantaneous impulse.
+   *
+   * @param impulse - Newton-seconds, world space.
+   * @param point - Where to apply it; defaults to the centre of mass.
+   */
+  addImpulse(impulse: Vec2Like, point?: Vec2Like): void;
+  /**
+   * Applies a torque for one fixed step.
+   *
+   * @param torque - Newton-metres, positive counter-clockwise.
+   */
+  addTorque(torque: number): void;
+  /**
+   * 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: Vec2Like, rotation?: number): void;
+}
+//#endregion
+//#region src/components/character-controller.d.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
+ */
+export declare const CHARACTER_SHAPES_2D: readonly ["capsule", "box"];
+/**
+ * The union of {@link CHARACTER_SHAPES_2D}.
+ *
+ * @public
+ */
+type CharacterShape2D = (typeof CHARACTER_SHAPES_2D)[number];
+/**
+ * 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
+ */
+export declare class CharacterController2D extends Component implements ComponentHooks {
+  #private;
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** One controller per entity. */
+  static allowMultiple: boolean;
+  /** The serialized field declarations (ADR-0004). */
+  static schema: Schema;
+  shape: CharacterShape2D;
+  radius: number;
+  height: number;
+  offset: Vec2Like;
+  slopeLimit: number;
+  stepOffset: number;
+  snapToGround: number;
+  skinWidth: number;
+  onOneWayPlatforms: boolean;
+  pushBodies: boolean;
+  interpolation: InterpolationMode2D;
+  /** Applies the schema defaults. */
+  constructor();
+  /** Creates the Rapier controller at the start of the next fixed step. */
+  onAttach(): void;
+  /** Releases the Rapier controller and its collider. */
+  onDetach(): void;
+  /** Rebuilds the capsule or box at the start of the next fixed step. */
+  rebuild(): void;
+  /**
+   * 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: Vec2Like): void;
+  /**
+   * 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(): Vec2;
+  /**
+   * Whether the character ended the last step on walkable ground.
+   *
+   * @returns Rapier's `computedGrounded` from the last move.
+   */
+  get isGrounded(): boolean;
+  /**
+   * The most upward-facing normal of the obstacles the last move touched.
+   *
+   * @returns A live view; copy it if you keep it.
+   */
+  get groundNormal(): Vec2;
+  /**
+   * Emitted once per obstacle the character hit during a step.
+   *
+   * @returns The signal, created on first access.
+   */
+  get onCollided(): Signal<CharacterCollision2D>;
+  /**
+   * Teleports the character, clearing any pending motion and the interpolation history.
+   *
+   * @param position - The new world position of the entity, in metres.
+   */
+  teleport(position: Vec2Like): void;
+  /**
+   * The displacement requested so far this step, consumed by the step system.
+   *
+   * @returns A live view of the accumulator.
+   *
+   * @internal
+   */
+  takePendingMove(): Vec2;
+  /**
+   * 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: Vec2Like, grounded: boolean, normal: Vec2Like | null, deltaSeconds: number): void;
+  /**
+   * Emits `onCollided` if anything is listening.
+   *
+   * @param collision - The obstacle to report.
+   *
+   * @internal
+   */
+  reportHit(collision: CharacterCollision2D): void;
+}
+//#endregion
+//#region src/components/colliders.d.ts
+/**
+ * The axis a 2D capsule stands along.
+ *
+ * @public
+ */
+export declare const CAPSULE_DIRECTIONS_2D: readonly ["x", "y"];
+/**
+ * The union of {@link CAPSULE_DIRECTIONS_2D}.
+ *
+ * @public
+ */
+type CapsuleDirection2D = (typeof CAPSULE_DIRECTIONS_2D)[number];
+/**
+ * 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
+ */
+export declare class BoxCollider2D extends Collider2D {
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** The serialized field declarations (ADR-0004). */
+  static schema: Schema;
+  size: Vec2Like;
+  /** Applies this collider's defaults on top of the shared ones. */
+  constructor();
+  /**
+   * Appends this collider's Rapier shape.
+   *
+   * @param scale - The entity's lossy 2D scale.
+   * @param out - The list to append to.
+   *
+   * @internal
+   */
+  collectShapes(scale: Vec2Like, out: CollectedShape2D[]): void;
+}
+/**
+ * A circle collider. Non-uniform scale is not representable as a circle, so the larger scale axis
+ * wins — the same rule Unity applies.
+ *
+ * @public
+ */
+export declare class CircleCollider2D extends Collider2D {
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** The serialized field declarations. */
+  static schema: Schema;
+  radius: number;
+  /** Applies this collider's defaults on top of the shared ones. */
+  constructor();
+  /**
+   * Appends this collider's Rapier shape.
+   *
+   * @param scale - The entity's lossy 2D scale.
+   * @param out - The list to append to.
+   *
+   * @internal
+   */
+  collectShapes(scale: Vec2Like, out: CollectedShape2D[]): void;
+}
+/**
+ * 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
+ */
+export declare class CapsuleCollider2D extends Collider2D {
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** The serialized field declarations. */
+  static schema: Schema;
+  radius: number;
+  height: number;
+  direction: CapsuleDirection2D;
+  /** Applies this collider's defaults on top of the shared ones. */
+  constructor();
+  /**
+   * Appends this collider's Rapier shape.
+   *
+   * @param scale - The entity's lossy 2D scale.
+   * @param out - The list to append to.
+   *
+   * @internal
+   */
+  collectShapes(scale: Vec2Like, out: CollectedShape2D[]): void;
+}
+/**
+ * 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
+ */
+export declare class PolygonCollider2D extends Collider2D {
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** The serialized field declarations. */
+  static schema: Schema;
+  points: Vec2Like[];
+  /** Applies this collider's defaults on top of the shared ones. */
+  constructor();
+  /**
+   * 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: Vec2Like, out: CollectedShape2D[]): void;
+}
+/**
+ * An open chain of line segments — a platformer's ground contour.
+ *
+ * @public
+ */
+export declare class EdgeCollider2D extends Collider2D {
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** The serialized field declarations. */
+  static schema: Schema;
+  points: Vec2Like[];
+  /** Applies this collider's defaults on top of the shared ones. */
+  constructor();
+  /**
+   * 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: Vec2Like, out: CollectedShape2D[]): void;
+}
+//#endregion
+//#region src/components/tilemap-collider.d.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
+ */
+export declare class TilemapCollider2D extends Collider2D {
+  #private;
+  /** The namespaced registration id. */
+  static typeId: string;
+  /** The serialized field declarations; the geometry itself comes from the tilemap asset. */
+  static schema: Schema;
+  /** Applies the shared defaults. */
+  constructor();
+  /**
+   * The merged chunk geometry this collider builds shapes from.
+   *
+   * @returns The data, or `null` when none has been supplied.
+   */
+  get collisionData(): TilemapCollisionData | null;
+  /**
+   * Replaces the tilemap geometry and schedules a rebuild.
+   *
+   * @param value - The merged chunk geometry, or `null` to drop the shapes.
+   */
+  set collisionData(value: TilemapCollisionData | null);
+  /**
+   * 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(): boolean;
+  /**
+   * 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: Vec2Like, out: CollectedShape2D[]): void;
+}
+//#endregion
+//#region src/errors.d.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
+ */
+export declare const Physics2DErrorCode: {
+  /** Both `physics()` and `physics2d()` are registered on one world (`11-2d-toolkit.md` §8). */
+  readonly bothPhysicsExtensions: "IGX-1101";
+  /** The Rapier WebAssembly module could not be instantiated. */
+  readonly rapierUnavailable: "IGX-1150";
+  /** An entity with 2D colliders but no `Rigidbody2D` moved after its static body was placed. */
+  readonly movedStaticBody: "IGX-1151";
+  /** A collider's layer index is outside the sixteen Rapier's interaction groups can express. */
+  readonly layerOutOfRange: "IGX-1152";
+  /** A query ran before the first completed fixed step, so Rapier has no broadphase yet. */
+  readonly queryBeforeStep: "IGX-1153";
+  /** A `.physicsmaterial.json` file is not an `ignifx.physicsmaterial` document this build reads. */
+  readonly invalidMaterialFile: "IGX-1154";
+  /** The `physics2d.collisionMatrix` setting names a layer the project does not declare. */
+  readonly unknownLayer: "IGX-1155";
+  /** A collider's geometry is degenerate: too few points, or a hull Rapier refused to build. */
+  readonly colliderGeometryInvalid: "IGX-1156";
+  /** A 2D body was built for an entity that has a parent, whose pose is not world space. */
+  readonly bodyOnChildEntity: "IGX-1157";
+};
+/**
+ * The union of the codes the `Physics2DErrorCode` table declares.
+ *
+ * @public
+ */
+export type Physics2DErrorCode = (typeof Physics2DErrorCode)[keyof typeof Physics2DErrorCode];
+/**
+ * The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
+ *
+ * @public
+ */
+export declare const PHYSICS_2D_ERROR_MESSAGES: Readonly<Record<string, string>>;
+/**
+ * Options accepted by {@link physics2DError}.
+ *
+ * @public
+ */
+interface Physics2DErrorOptions {
+  /** Identifiers that locate the failure. */
+  readonly context?: ErrorContext;
+  /** One sentence telling the developer what to do about it. */
+  readonly hint?: string;
+  /** The failure being wrapped, when there is one. */
+  readonly cause?: unknown;
+}
+/**
+ * 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
+ */
+export declare function physics2DError(code: Physics2DErrorCode, message: string, options?: Physics2DErrorOptions): IgnifxError;
+//#endregion
+//#region src/queries.d.ts
+/**
+ * The query vocabulary of `app.physics2d` (`docs/architecture/11-2d-toolkit.md` §8,
+ * `09-physics.md` §5).
+ *
+ * Unlike the 3D service, every 2D query is **shape-accurate and identity-carrying**: Rapier's
+ * `castRayAndGetNormal`, `intersectionsWithShape`, and `castShape` all return the `Collider` that
+ * was hit (`pipeline/world.d.ts`), so no bounds index is needed and the corrections `09-physics.md`
+ * §5 records for 3D do not apply here.
+ */
+/**
+ * Options every 2D query accepts.
+ *
+ * @public
+ */
+interface QueryOptions2D {
+  /** Which layers the query may hit. Defaults to everything. */
+  readonly layerMask?: LayerMask;
+  /** Whether trigger volumes count as hits. Defaults to `false`. */
+  readonly hitTriggers?: boolean;
+}
+/**
+ * What a 2D ray or shape query hit.
+ *
+ * @remarks
+ * The object is freshly allocated per hit, so it is safe to keep. `raycastAll` returns a **reused**
+ * array of freshly allocated hits.
+ *
+ * @public
+ */
+interface RaycastHit2D {
+  /** The entity that was hit. */
+  readonly entity: Entity;
+  /** The collider that was hit. */
+  readonly collider: Collider2D | null;
+  /** The world-space contact point, in metres. */
+  readonly point: Vec2Like;
+  /** The world-space surface normal. */
+  readonly normal: Vec2Like;
+  /** The distance from the ray origin, in metres. */
+  readonly distance: number;
+}
+/**
+ * What a 2D shape sweep hit.
+ *
+ * @public
+ */
+interface ShapeCastHit2D {
+  /** The entity the swept shape hit. */
+  readonly entity: Entity;
+  /** The collider it hit. */
+  readonly collider: Collider2D | null;
+  /** The world-space contact point on the hit collider. */
+  readonly point: Vec2Like;
+  /** The world-space contact normal. */
+  readonly normal: Vec2Like;
+  /** The distance travelled before contact, in metres. */
+  readonly distance: number;
+  /** How far along the sweep the contact occurs, in `[0, 1]`. */
+  readonly fraction: number;
+}
+//#endregion
+//#region src/runtime/body-record.d.ts
+/**
+ * One entity's 2D physics representation. The runtime keeps these in creation order, which is the
+ * iteration order every per-step loop uses — body creation order is what decides Rapier's internal
+ * ordering, so keeping it stable is part of determinism (`docs/architecture/09-physics.md` §8).
+ *
+ * @internal
+ */
+interface BodyRecord2D {
+  /** The entity the body belongs to. */
+  readonly entity: Entity;
+  /** The `Rigidbody2D`, or `null` for an implicit static body or a bare controller. */
+  rigidbody: Rigidbody2D | null;
+  /** The `CharacterController2D`, or `null`. */
+  controller: CharacterController2D | null;
+  /** The Rapier body. */
+  body: RapierBody;
+  /** Every Rapier collider the record owns, in creation order. */
+  colliders: RapierCollider[];
+  /** The ignifx collider each Rapier collider came from; `null` for the controller's own shape. */
+  owners: (Collider2D | null)[];
+  /** The controller's own collider, which is what `computeColliderMovement` moves. */
+  controllerCollider: RapierCollider | null;
+  /** How the body moves. */
+  motion: BodyMotion2D;
+  /** Whether the display pose is interpolated between fixed steps. */
+  interpolate: boolean;
+  /** The layer the filter word was built from, so a runtime change is noticed. */
+  layer: number;
+  /** Whether the record's colliders currently raise events. */
+  collisionEvents: boolean;
+  /** The position at the end of the previous fixed step. */
+  readonly previousPosition: Vec2;
+  /** The rotation in radians at the end of the previous fixed step. */
+  previousRotation: number;
+  /** The authoritative position at the end of the last fixed step. */
+  readonly currentPosition: Vec2;
+  /** The authoritative rotation in radians at the end of the last fixed step. */
+  currentRotation: number;
+  /**
+   * The linear velocity as it was *before* the last step's solver ran, which is the impact speed a
+   * collision callback wants — reading it afterwards reports the resolved velocity, which for a
+   * landing body is zero.
+   */
+  readonly preStepVelocity: Vec2;
+  /** `Transform.worldMatrixVersion` when an implicit static body was placed (`IGX-1151`). */
+  staticVersion: number;
+  /** Whether the `IGX-1151` diagnostic has already been reported for this body. */
+  reportedMove: boolean;
+  /** Signal connections the record owns, dropped when it is torn down. */
+  disconnects: Disconnect[];
+}
+//#endregion
+//#region src/runtime/runtime.d.ts
+/**
+ * The per-app 2D physics runtime: the Rapier world, the bodies, the character controllers, the
+ * event drain, and the three things the systems ask it to do each frame — restore, step,
+ * interpolate (`docs/architecture/11-2d-toolkit.md` §8, `09-physics.md` §1).
+ *
+ * Everything here is `@internal`; the public surface is `Physics2DService`, `Rigidbody2D`, the 2D
+ * colliders, and `CharacterController2D`.
+ */
+/** What the extension hands the runtime. */
+interface Physics2DRuntimeOptions {
+  /** The extension registration surface; the physics kernel hooks live on it. */
+  readonly ctx: ExtensionContext;
+  /** The resolved `physics2d` settings section. */
+  readonly settings: Physics2DSettings;
+  /** The Rapier world. */
+  readonly world: RapierWorld;
+  /** The `physics2d` diagnostics group. */
+  readonly counters: DiagnosticsGroup;
+}
+/**
+ * The counters `09-physics.md` §9 and `11-2d-toolkit.md` §8 name for 2D.
+ *
+ * @public
+ */
+export declare const PHYSICS_2D_DIAGNOSTICS_COUNTERS: readonly string[];
+/**
+ * The diagnostics group name.
+ *
+ * @public
+ */
+export declare const PHYSICS_2D_DIAGNOSTICS_GROUP = "physics2d";
+/** Which ignifx collider a Rapier collider belongs to. */
+interface ColliderBinding {
+  /** The record that owns it. */
+  readonly record: BodyRecord2D;
+  /** The authored collider, or `null` for a character controller's own shape. */
+  readonly owner: Collider2D | null;
+  /** The Rapier collider itself, which the event and contact paths need. */
+  readonly collider: RapierCollider;
+}
+/**
+ * The per-app 2D physics runtime.
+ *
+ * @internal
+ */
+declare class Physics2DRuntime {
+  #private;
+  /**
+   * 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: Physics2DRuntimeOptions);
+  /**
+   * The Rapier world, for the query and escape-hatch paths.
+   *
+   * @returns The world handle.
+   */
+  get world(): RapierWorld;
+  /**
+   * 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(): boolean;
+  /**
+   * Every body, in creation order.
+   *
+   * @returns The records.
+   */
+  get records(): readonly BodyRecord2D[];
+  /**
+   * The resolved settings.
+   *
+   * @returns The `physics2d` section.
+   */
+  get settings(): Physics2DSettings;
+  /**
+   * Replaces world gravity.
+   *
+   * @param gravity - The new acceleration vector.
+   */
+  setGravity(gravity: Vec2Like): void;
+  /**
+   * 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: Entity): void;
+  /**
+   * Marks a character controller's entity for a rebuild.
+   *
+   * @param component - The controller component.
+   */
+  markControllerDirty(component: CharacterController2D): void;
+  /**
+   * Drops a character controller's body, which is what detaching the component does.
+   *
+   * @param component - The controller component.
+   */
+  releaseController(component: CharacterController2D): void;
+  /**
+   * The Rapier body of an entity, for the escape hatch.
+   *
+   * @param entity - The entity.
+   * @returns The body handle, or `null`.
+   */
+  bodyHandleOf(entity: Entity): BodyRecord2D["body"] | null;
+  /**
+   * The record an entity owns.
+   *
+   * @param entity - The entity.
+   * @returns The record, or `null`.
+   */
+  recordOf(entity: Entity): BodyRecord2D | 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: RapierCollider | null): ColliderBinding | 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: Entity): number;
+  /**
+   * 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: Entity, out: MutableVec2): void;
+  /**
+   * Reads a body's angular velocity.
+   *
+   * @param entity - The entity.
+   * @returns Degrees per second, counter-clockwise.
+   */
+  readAngular(entity: Entity): number;
+  /**
+   * Sets a body's linear velocity.
+   *
+   * @param entity - The entity.
+   * @param velocity - Metres per second.
+   */
+  setLinearVelocity(entity: Entity, velocity: Vec2Like): void;
+  /**
+   * Sets a body's angular velocity.
+   *
+   * @param entity - The entity.
+   * @param velocity - Degrees per second.
+   */
+  setAngularVelocity(entity: Entity, velocity: number): void;
+  /**
+   * 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: Entity, force: Vec2Like, point: Vec2Like | null): void;
+  /**
+   * 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: Entity, impulse: Vec2Like, point: Vec2Like | null): void;
+  /**
+   * Applies a torque for one fixed step.
+   *
+   * @param entity - The entity.
+   * @param torque - Newton-metres, positive counter-clockwise.
+   */
+  addTorque(entity: Entity, torque: number): void;
+  /**
+   * 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: Entity, position: Vec2Like, rotationDegrees: number): void;
+  /**
+   * Teleports a character controller.
+   *
+   * @param component - The controller component.
+   * @param position - The new world position.
+   */
+  teleportController(component: CharacterController2D, position: Vec2Like): void;
+  /**
+   * Restores the authoritative pose of every interpolated body, undoing the display pose the
+   * `PreRender` system wrote (`09-physics.md` §1).
+   */
+  restorePoses(): void;
+  /**
+   * Runs one fixed step: reconcile, push kinematic poses, move controllers, step Rapier, snapshot,
+   * dispatch events.
+   *
+   * @param fixedDeltaSeconds - The fixed step in seconds.
+   */
+  step(fixedDeltaSeconds: number): void;
+  /**
+   * Writes the interpolated display pose of every interpolated body.
+   *
+   * @param alpha - `time.fixedStepAlpha`, in `[0, 1)`.
+   */
+  interpolate(alpha: number): void;
+  /** Tears every body down and releases the Rapier world. */
+  dispose(): void;
+}
+//#endregion
+//#region src/runtime/host.d.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
+ */
+declare class Physics2DHost {
+  /** The runtime, or `null` until `onStart` has built it. */
+  runtime: Physics2DRuntime | null;
+}
+//#endregion
+//#region src/service.d.ts
+/**
+ * The Rapier objects the 2D physics extension owns. Unstable escape hatch
+ * (`docs/architecture/00-overview.md` §3).
+ *
+ * @public
+ */
+interface Physics2DRapierHandles {
+  /** Rapier's `World`. */
+  readonly world: RapierWorld;
+}
+/**
+ * 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
+ */
+export declare class Physics2DService {
+  #private;
+  /**
+   * 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: Physics2DHost, settings: Physics2DSettings);
+  /**
+   * World gravity in metres per second squared.
+   *
+   * @returns A live view; writing to it does nothing, assign the property instead.
+   */
+  get gravity(): Vec2;
+  /**
+   * Replaces world gravity, which every body feels from the next fixed step.
+   *
+   * @param value - The new acceleration vector.
+   */
+  set gravity(value: Vec2Like);
+  /**
+   * The Rapier handles.
+   *
+   * @returns The world.
+   */
+  get rapier(): Physics2DRapierHandles;
+  /**
+   * 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: Vec2Like, direction: Vec2Like, maxDistance?: number, options?: QueryOptions2D): RaycastHit2D | null;
+  /**
+   * 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: Vec2Like, direction: Vec2Like, maxDistance?: number, options?: QueryOptions2D): readonly RaycastHit2D[];
+  /**
+   * 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: Vec2Like, radius: number, options?: QueryOptions2D): readonly Entity[];
+  /**
+   * 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: Vec2Like, size: Vec2Like, rotation?: number, options?: QueryOptions2D): readonly Entity[];
+  /**
+   * 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: Vec2Like, radius: number, direction: Vec2Like, maxDistance: number, options?: QueryOptions2D): ShapeCastHit2D | null;
+}
+//#endregion
+//#region src/extension.d.ts
+/**
+ * The `@ignifx/physics-2d` extension (`docs/architecture/11-2d-toolkit.md` §8,
+ * `04-extensions.md` §1).
+ *
+ * ## Why `@ignifx/2d` is optional rather than required
+ *
+ * `00-overview.md` §2 draws `@ignifx/physics-2d` above `@ignifx/2d`, and the layering rule allows
+ * the dependency. At runtime the only thing this package needs from the toolkit is the
+ * `TilemapCollisionData` **type**, which is erased at build time, so a platformer that draws its own
+ * graphics can register `physics2d()` on its own. The manifest therefore declares
+ * `requires: []` and `optional: ["@ignifx/2d"]`, and `package.json` makes `@ignifx/2d` an optional
+ * peer dependency.
+ *
+ * ## Why the world is built in `onStart`
+ *
+ * `register` runs before `createApp` builds the `World` (`packages/core/src/app/app.ts`,
+ * `initialize`), and the Rapier world needs the world's layer table; Rapier's WebAssembly module
+ * also has to be instantiated, which is asynchronous. So `register` declares everything against a
+ * {@link Physics2DHost} holder and `onStart` fills the holder in.
+ *
+ * ## One physics extension per world
+ *
+ * `11-2d-toolkit.md` §8: "A world uses either `physics()` or `physics2d()`; registering both throws
+ * `IGX-1101`". `@ignifx/physics` publishes its Havok simulation scene through
+ * `ExtensionContext.setSimulationScene`, so `app.world.lite.simulationScene !== null` at `onStart`
+ * is the test — and it needs no dependency on `@ignifx/physics`, which this package must not have.
+ */
+/**
+ * What `physics2d()` accepts.
+ *
+ * @public
+ */
+interface Physics2DOptions {
+  /**
+   * Replaces the step that instantiates Rapier's WebAssembly module. The default awaits
+   * `RAPIER.init()`, which decodes the base64 payload the `-compat` build inlines; a host that has
+   * already preloaded the module, or a test that wants to observe the failure path, supplies its
+   * own.
+   */
+  readonly initialize?: () => Promise<void>;
+}
+declare module "@ignifx/core" {
+  interface App {
+    /** 2D physics: gravity, queries, and the Rapier escape hatch. */
+    readonly physics2d: Physics2DService;
+  }
+}
+/**
+ * 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
+ */
+export declare const physics2d: (options?: Physics2DOptions) => Extension;
+//#endregion
+//#region src/schemas.d.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
+ */
+export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
+//#endregion
+export type { BodyType2D, CapsuleDirection2D, CharacterCollision2D, CharacterShape2D, Collision2D, CollisionEventMode2D, CombineRule, ContactPoint2D, InterpolationMode2D, Physics2DErrorOptions, Physics2DMaterialValues, Physics2DOptions, Physics2DRapierHandles, Physics2DSettings, QueryOptions2D, RaycastHit2D, Rigidbody2DRapierHandles, ShapeCastHit2D, TriggerEvent2D };
+//# sourceMappingURL=index.d.ts.map