@codexo/exojs-physics 0.13.0

package/dist/esm/PhysicsBody.js

@@ -0,0 +1,186 @@
+import { Vector } from '@codexo/exojs';
+import { Collider } from './Collider.js';
+import { createTransform, setTransform, applyTransform } from './math.js';
+
+/**
+ * A rigid body: a world transform plus mass properties aggregated from its
+ * colliders. In this collision/query release a body holds and reports its
+ * transform and mass but is not integrated — it moves only via
+ * {@link setTransform} (game-driven / kinematic). Forces, impulses and gravity
+ * integration arrive with the dynamics solver.
+ */
+class PhysicsBody {
+    id;
+    type;
+    /** Linear damping (inert until dynamics ship). */
+    linearDamping;
+    /** Angular damping (inert until dynamics ship). */
+    angularDamping;
+    /** Per-body gravity multiplier (inert until dynamics ship). */
+    gravityScale;
+    /** When `true`, rotational inertia is treated as infinite. */
+    fixedRotation;
+    /** Total mass (0 for static/kinematic). */
+    mass = 0;
+    /** Inverse mass (`0` = immovable). */
+    invMass = 0;
+    /** Rotational inertia about the centre of mass (0 for static/kinematic or fixed rotation). */
+    inertia = 0;
+    /** Inverse rotational inertia (`0` = no angular response). */
+    invInertia = 0;
+    _owner;
+    _transform;
+    _colliders = [];
+    _comX = 0;
+    _comY = 0;
+    _massReady = false;
+    _destroyed = false;
+    constructor(owner, id, options = {}) {
+        this.id = id;
+        this.type = options.type ?? 'dynamic';
+        this._owner = owner;
+        this._transform = createTransform(options.position?.x ?? 0, options.position?.y ?? 0, options.angle ?? 0);
+        this.linearDamping = options.linearDamping ?? 0;
+        this.angularDamping = options.angularDamping ?? 0;
+        this.gravityScale = options.gravityScale ?? 1;
+        this.fixedRotation = options.fixedRotation ?? false;
+    }
+    /** World X. */
+    get x() {
+        return this._transform.x;
+    }
+    /** World Y. */
+    get y() {
+        return this._transform.y;
+    }
+    /** Rotation in radians. */
+    get angle() {
+        return this._transform.angle;
+    }
+    /** A fresh `Vector` copy of the body's world position. */
+    get position() {
+        return new Vector(this._transform.x, this._transform.y);
+    }
+    /** The body's world transform (read-only; mutate via {@link setTransform}). */
+    get transform() {
+        return this._transform;
+    }
+    /** The body's colliders (read-only view). */
+    get colliders() {
+        return this._colliders;
+    }
+    /** Centre of mass in body-local space (relative to the body origin). */
+    get centerOfMassX() {
+        return this._comX;
+    }
+    /** Centre of mass in body-local space (relative to the body origin). */
+    get centerOfMassY() {
+        return this._comY;
+    }
+    /**
+     * `true` when the body is ready to simulate. Static/kinematic bodies are
+     * always ready (infinite-mass semantics); a dynamic body is ready only once
+     * it has at least one positive-density collider.
+     */
+    get isMassReady() {
+        return this.type !== 'dynamic' || this._massReady;
+    }
+    /** `true` after the owning world has destroyed this body. */
+    get destroyed() {
+        return this._destroyed;
+    }
+    /** Attach a new collider, recomputing mass and synchronising world geometry. */
+    createCollider(options) {
+        if (this._destroyed) {
+            throw new Error('PhysicsBody: cannot create a collider on a destroyed body.');
+        }
+        // Collider imports PhysicsBody type-only (erased), so this value import is
+        // one-directional — no runtime cycle.
+        const collider = new Collider(this._owner._allocateColliderId(), this, options);
+        this._colliders.push(collider);
+        this._recomputeMass();
+        collider.synchronize(this._transform);
+        this._owner._registerCollider(collider);
+        return collider;
+    }
+    /**
+     * Set the body's world transform. Resets the body's cached collider geometry
+     * immediately so subsequent queries see the new placement. Returns `this`.
+     */
+    setTransform(position, angle = this._transform.angle) {
+        if (this._destroyed) {
+            throw new Error('PhysicsBody: cannot move a destroyed body.');
+        }
+        setTransform(this._transform, position.x, position.y, angle);
+        for (const collider of this._colliders) {
+            collider.synchronize(this._transform);
+        }
+        return this;
+    }
+    /** Refresh every collider's world geometry from the current transform. */
+    synchronizeColliders() {
+        for (const collider of this._colliders) {
+            collider.synchronize(this._transform);
+        }
+    }
+    /** Internal: detach a collider (called by the world during destruction). */
+    _removeCollider(collider) {
+        const index = this._colliders.indexOf(collider);
+        if (index !== -1) {
+            this._colliders.splice(index, 1);
+            this._recomputeMass();
+        }
+    }
+    /** Internal: mark destroyed (called by the world). */
+    _markDestroyed() {
+        this._destroyed = true;
+    }
+    /** Recompute mass, centre of mass and rotational inertia from the colliders. */
+    _recomputeMass() {
+        if (this.type !== 'dynamic') {
+            this.mass = 0;
+            this.invMass = 0;
+            this.inertia = 0;
+            this.invInertia = 0;
+            this._comX = 0;
+            this._comY = 0;
+            this._massReady = false;
+            return;
+        }
+        let mass = 0;
+        let cx = 0;
+        let cy = 0;
+        let inertiaOrigin = 0;
+        const point = { x: 0, y: 0 };
+        for (const collider of this._colliders) {
+            const shape = collider.shape;
+            const m = collider.density * shape.area;
+            if (m <= 0) {
+                continue;
+            }
+            // Shape centroid expressed in body-local space (offset + local rotation).
+            applyTransform(collider.localTransform, shape.centroidX, shape.centroidY, point);
+            mass += m;
+            cx += m * point.x;
+            cy += m * point.y;
+            // Parallel-axis to the body origin: I_origin += I_centroid + m·d².
+            inertiaOrigin += collider.density * shape.unitInertia + m * (point.x * point.x + point.y * point.y);
+        }
+        if (mass > 0) {
+            cx /= mass;
+            cy /= mass;
+        }
+        this.mass = mass;
+        this.invMass = mass > 0 ? 1 / mass : 0;
+        this._comX = cx;
+        this._comY = cy;
+        // Shift inertia from the body origin to the centre of mass.
+        const inertiaCom = inertiaOrigin - mass * (cx * cx + cy * cy);
+        this.inertia = this.fixedRotation ? 0 : inertiaCom;
+        this.invInertia = this.fixedRotation || inertiaCom <= 0 ? 0 : 1 / inertiaCom;
+        this._massReady = mass > 0;
+    }
+}
+
+export { PhysicsBody };
+//# sourceMappingURL=PhysicsBody.js.map

package/dist/esm/PhysicsBody.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicsBody.js","sources":["../../../src/PhysicsBody.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/PhysicsWorld.d.ts

@@ -0,0 +1,126 @@
+import type { SceneNode } from '@codexo/exojs';
+import { Signal, Vector } from '@codexo/exojs';
+import type { Aabb } from './Aabb';
+import type { PhysicsBackend } from './backend/PhysicsBackend';
+import type { BindingOptions, PhysicsBinding } from './binding/PhysicsBinding';
+import type { Collider, ColliderOptions } from './Collider';
+import type { CollisionEvent, SensorEvent } from './events';
+import type { BodyOptions, BodyOwner } from './PhysicsBody';
+import { PhysicsBody } from './PhysicsBody';
+import type { QueryFilter, RayHit } from './query/QueryEngine';
+import type { Shape } from './shapes/Shape';
+import { TimeStepper } from './TimeStepper';
+import type { VectorLike } from './types';
+/** Construction options for a {@link PhysicsWorld}. */
+export interface PhysicsWorldOptions {
+    /** Gravity in px/s² (+Y down). Stored; applied once the dynamics solver ships. Default `(0, 0)`. */
+    gravity?: VectorLike;
+    /** Fixed timestep in seconds. Default `1 / 60`. */
+    fixedDelta?: number;
+    /** Maximum sub-steps per `step` (spiral-of-death guard). Default `8`. */
+    maxSubSteps?: number;
+    /** Solver velocity iterations (stored for forward-compat). Default `8`. */
+    velocityIterations?: number;
+    /** Solver position iterations (stored for forward-compat). Default `3`. */
+    positionIterations?: number;
+    /** Interpolate bound nodes between sub-steps (no effect until dynamics integrate). Default `true`. */
+    interpolation?: boolean;
+}
+/** {@link PhysicsWorld.createStaticCollider} options: a collider plus its static body placement. */
+export interface StaticColliderOptions extends ColliderOptions {
+    /** World position of the implicit static body. Default `(0, 0)`. */
+    position?: VectorLike;
+    /** Rotation (radians) of the implicit static body. Default `0`. */
+    angle?: number;
+}
+/**
+ * The collision/query world: owns bodies, colliders, the detection backend,
+ * bindings, the query engine and the fixed-step accumulator. Stepped by the
+ * caller (commonly from a `Scene.update`), it runs broad- and narrow-phase
+ * detection, fires immutable contact/sensor events, and writes bound node
+ * transforms. It holds **no module-level state**, so any number of worlds run
+ * in isolation (gate I-1).
+ *
+ * This release performs collision detection, sensors, events, queries and
+ * binding; bodies move only via {@link PhysicsBody.setTransform}. Gravity,
+ * forces and impulse integration arrive with the dynamics solver.
+ */
+export declare class PhysicsWorld implements BodyOwner {
+    /** Fires when two solid colliders begin touching. Argument is an immutable snapshot. */
+    readonly onCollisionStart: Signal<[CollisionEvent]>;
+    /** Fires when two solid colliders stop touching (or one is destroyed). */
+    readonly onCollisionEnd: Signal<[CollisionEvent]>;
+    /** Fires when a collider enters a sensor. */
+    readonly onSensorEnter: Signal<[SensorEvent]>;
+    /** Fires when a collider leaves a sensor. */
+    readonly onSensorExit: Signal<[SensorEvent]>;
+    /** World gravity (px/s², +Y down). Stored until dynamics ship. */
+    readonly gravity: Vector;
+    /** The fixed-step accumulator. */
+    readonly timeStepper: TimeStepper;
+    /** Whether bound nodes interpolate between sub-steps (no effect until dynamics). */
+    readonly interpolation: boolean;
+    /** Solver velocity iterations (stored for forward-compat). */
+    readonly velocityIterations: number;
+    /** Solver position iterations (stored for forward-compat). */
+    readonly positionIterations: number;
+    private readonly _backend;
+    private readonly _bodies;
+    private readonly _colliders;
+    private readonly _bindings;
+    private readonly _query;
+    private readonly _commands;
+    private _nextBodyId;
+    private _nextColliderId;
+    private _dispatching;
+    private _destroyed;
+    constructor(options?: PhysicsWorldOptions);
+    /** Live bodies (read-only view). */
+    get bodies(): readonly PhysicsBody[];
+    /** Live colliders (read-only view). */
+    get colliders(): readonly Collider[];
+    /** Create a body. Safe to call inside an event callback (deferred to end of step). */
+    createBody(options?: BodyOptions): PhysicsBody;
+    /** Sugar: an explicit static body carrying a single collider. The body is addressable via `collider.body`. */
+    createStaticCollider(options: StaticColliderOptions): Collider;
+    /** Destroy a body and its colliders. Deferred when called inside a callback. */
+    destroyBody(body: PhysicsBody): void;
+    /** Destroy a single collider, recomputing its body's mass. Deferred when called inside a callback. */
+    destroyCollider(collider: Collider): void;
+    /**
+     * Advance the world by `frameDeltaSeconds`. Accumulates into fixed sub-steps,
+     * runs detection, dispatches events, then writes bound node transforms.
+     */
+    step(frameDeltaSeconds: number): void;
+    /** Link a body to a scene node; the node tracks the body after each step. */
+    bind(body: PhysicsBody, node: SceneNode, options?: BindingOptions): PhysicsBinding;
+    /** Remove a body↔node link. */
+    unbind(body: PhysicsBody): void;
+    /** Colliders containing `point`. Fresh array. */
+    queryPoint(point: VectorLike, filter?: QueryFilter): Collider[];
+    /** Colliders whose AABB overlaps `bounds`. Writes into `out` (cleared) if given. */
+    queryAabb(bounds: Aabb, filter?: QueryFilter, out?: Collider[]): Collider[];
+    /** Invoke `callback` for each collider whose AABB overlaps `bounds`. Allocation-free. */
+    forEachAabbHit(bounds: Aabb, filter: QueryFilter | undefined, callback: (collider: Collider) => void): void;
+    /** Nearest collider hit by the ray, or `null`. */
+    rayCast(origin: VectorLike, direction: VectorLike, filter?: QueryFilter, maxDistance?: number): RayHit | null;
+    /** All collider hits along the ray, sorted by distance. Writes into `out` (cleared) if given. */
+    rayCastAll(origin: VectorLike, direction: VectorLike, filter?: QueryFilter, out?: RayHit[], maxDistance?: number): RayHit[];
+    /** Colliders overlapping `shape` placed at `position`/`angle`. Fresh array. */
+    overlapShape(shape: Shape, position: VectorLike, filter?: QueryFilter, angle?: number): Collider[];
+    /** Release every body, collider, binding and backend resource. */
+    destroy(): void;
+    _allocateColliderId(): number;
+    _registerCollider(collider: Collider): void;
+    /** The detection backend (internal; consumed by the debug draw layer). */
+    get backend(): PhysicsBackend;
+    private _dispatchEvents;
+    /** Run `command` now, or queue it when inside an event dispatch (deferred to end of step). */
+    private _defer;
+    private _drainCommands;
+    private _removeBody;
+    private _teardownBody;
+    private _removeCollider;
+    private _detachCollider;
+    private _assertAlive;
+}

package/dist/esm/PhysicsWorld.js

@@ -0,0 +1,253 @@
+import { Signal, Vector } from '@codexo/exojs';
+import { NativePhysicsBackend } from './backend/NativePhysicsBackend.js';
+import { BindingRegistry } from './binding/BindingRegistry.js';
+import { PhysicsBody } from './PhysicsBody.js';
+import { QueryEngine } from './query/QueryEngine.js';
+import { TimeStepper } from './TimeStepper.js';
+
+/**
+ * The collision/query world: owns bodies, colliders, the detection backend,
+ * bindings, the query engine and the fixed-step accumulator. Stepped by the
+ * caller (commonly from a `Scene.update`), it runs broad- and narrow-phase
+ * detection, fires immutable contact/sensor events, and writes bound node
+ * transforms. It holds **no module-level state**, so any number of worlds run
+ * in isolation (gate I-1).
+ *
+ * This release performs collision detection, sensors, events, queries and
+ * binding; bodies move only via {@link PhysicsBody.setTransform}. Gravity,
+ * forces and impulse integration arrive with the dynamics solver.
+ */
+class PhysicsWorld {
+    /** Fires when two solid colliders begin touching. Argument is an immutable snapshot. */
+    onCollisionStart = new Signal();
+    /** Fires when two solid colliders stop touching (or one is destroyed). */
+    onCollisionEnd = new Signal();
+    /** Fires when a collider enters a sensor. */
+    onSensorEnter = new Signal();
+    /** Fires when a collider leaves a sensor. */
+    onSensorExit = new Signal();
+    /** World gravity (px/s², +Y down). Stored until dynamics ship. */
+    gravity;
+    /** The fixed-step accumulator. */
+    timeStepper;
+    /** Whether bound nodes interpolate between sub-steps (no effect until dynamics). */
+    interpolation;
+    /** Solver velocity iterations (stored for forward-compat). */
+    velocityIterations;
+    /** Solver position iterations (stored for forward-compat). */
+    positionIterations;
+    _backend = new NativePhysicsBackend();
+    _bodies = [];
+    _colliders = [];
+    _bindings = new BindingRegistry();
+    _query;
+    _commands = [];
+    _nextBodyId = 1;
+    _nextColliderId = 1;
+    _dispatching = false;
+    _destroyed = false;
+    constructor(options = {}) {
+        this.gravity = new Vector(options.gravity?.x ?? 0, options.gravity?.y ?? 0);
+        this.timeStepper = new TimeStepper({ fixedDelta: options.fixedDelta, maxSubSteps: options.maxSubSteps });
+        this.interpolation = options.interpolation ?? true;
+        this.velocityIterations = options.velocityIterations ?? 8;
+        this.positionIterations = options.positionIterations ?? 3;
+        this._query = new QueryEngine(this._colliders);
+    }
+    /** Live bodies (read-only view). */
+    get bodies() {
+        return this._bodies;
+    }
+    /** Live colliders (read-only view). */
+    get colliders() {
+        return this._colliders;
+    }
+    // ── lifecycle ──────────────────────────────────────────────────────────
+    /** Create a body. Safe to call inside an event callback (deferred to end of step). */
+    createBody(options) {
+        this._assertAlive();
+        const body = new PhysicsBody(this, this._nextBodyId++, options);
+        this._defer(() => {
+            if (!body.destroyed) {
+                this._bodies.push(body);
+            }
+        });
+        return body;
+    }
+    /** Sugar: an explicit static body carrying a single collider. The body is addressable via `collider.body`. */
+    createStaticCollider(options) {
+        const body = this.createBody({ type: 'static', position: options.position, angle: options.angle });
+        return body.createCollider(options);
+    }
+    /** Destroy a body and its colliders. Deferred when called inside a callback. */
+    destroyBody(body) {
+        this._defer(() => this._removeBody(body));
+    }
+    /** Destroy a single collider, recomputing its body's mass. Deferred when called inside a callback. */
+    destroyCollider(collider) {
+        this._defer(() => this._removeCollider(collider));
+    }
+    // ── stepping ───────────────────────────────────────────────────────────
+    /**
+     * Advance the world by `frameDeltaSeconds`. Accumulates into fixed sub-steps,
+     * runs detection, dispatches events, then writes bound node transforms.
+     */
+    step(frameDeltaSeconds) {
+        this._assertAlive();
+        const steps = this.timeStepper.advance(frameDeltaSeconds);
+        if (steps > 0) {
+            // Without dynamics, geometry is unchanged across sub-steps, so a single
+            // detection pass per frame suffices; the dynamics solver will run per
+            // sub-step here.
+            for (const body of this._bodies) {
+                body.synchronizeColliders();
+            }
+            this._backend.detect(this._colliders);
+            this._dispatchEvents();
+        }
+        this._bindings.sync();
+        this._drainCommands();
+    }
+    // ── binding ────────────────────────────────────────────────────────────
+    /** Link a body to a scene node; the node tracks the body after each step. */
+    bind(body, node, options) {
+        return this._bindings.bind(body, node, options);
+    }
+    /** Remove a body↔node link. */
+    unbind(body) {
+        this._bindings.unbind(body);
+    }
+    // ── queries ────────────────────────────────────────────────────────────
+    /** Colliders containing `point`. Fresh array. */
+    queryPoint(point, filter) {
+        return this._query.queryPoint(point, filter);
+    }
+    /** Colliders whose AABB overlaps `bounds`. Writes into `out` (cleared) if given. */
+    queryAabb(bounds, filter, out) {
+        return this._query.queryAabb(bounds, filter, out);
+    }
+    /** Invoke `callback` for each collider whose AABB overlaps `bounds`. Allocation-free. */
+    forEachAabbHit(bounds, filter, callback) {
+        this._query.forEachAabbHit(bounds, filter, callback);
+    }
+    /** Nearest collider hit by the ray, or `null`. */
+    rayCast(origin, direction, filter, maxDistance) {
+        return this._query.rayCast(origin, direction, filter, maxDistance);
+    }
+    /** All collider hits along the ray, sorted by distance. Writes into `out` (cleared) if given. */
+    rayCastAll(origin, direction, filter, out, maxDistance) {
+        return this._query.rayCastAll(origin, direction, filter, out, maxDistance);
+    }
+    /** Colliders overlapping `shape` placed at `position`/`angle`. Fresh array. */
+    overlapShape(shape, position, filter, angle) {
+        return this._query.overlapShape(shape, position, filter, angle);
+    }
+    /** Release every body, collider, binding and backend resource. */
+    destroy() {
+        if (this._destroyed) {
+            return;
+        }
+        this._destroyed = true;
+        for (const body of this._bodies) {
+            body._markDestroyed();
+        }
+        this._bodies.length = 0;
+        this._colliders.length = 0;
+        this._commands.length = 0;
+        this._bindings.clear();
+        this._backend.destroy();
+        this.onCollisionStart.destroy();
+        this.onCollisionEnd.destroy();
+        this.onSensorEnter.destroy();
+        this.onSensorExit.destroy();
+    }
+    // ── BodyOwner ──────────────────────────────────────────────────────────
+    _allocateColliderId() {
+        return this._nextColliderId++;
+    }
+    _registerCollider(collider) {
+        this._defer(() => {
+            if (!collider.destroyed) {
+                this._colliders.push(collider);
+            }
+        });
+    }
+    // ── internals ──────────────────────────────────────────────────────────
+    /** The detection backend (internal; consumed by the debug draw layer). */
+    get backend() {
+        return this._backend;
+    }
+    _dispatchEvents() {
+        const graph = this._backend.contactGraph;
+        this._dispatching = true;
+        for (const event of graph.collisionEnd) {
+            this.onCollisionEnd.dispatch(event);
+        }
+        for (const event of graph.sensorExit) {
+            this.onSensorExit.dispatch(event);
+        }
+        for (const event of graph.collisionStart) {
+            this.onCollisionStart.dispatch(event);
+        }
+        for (const event of graph.sensorEnter) {
+            this.onSensorEnter.dispatch(event);
+        }
+        this._dispatching = false;
+    }
+    /** Run `command` now, or queue it when inside an event dispatch (deferred to end of step). */
+    _defer(command) {
+        if (this._dispatching) {
+            this._commands.push(command);
+        }
+        else {
+            command();
+        }
+    }
+    _drainCommands() {
+        if (this._commands.length === 0) {
+            return;
+        }
+        const commands = this._commands.splice(0, this._commands.length);
+        for (const command of commands) {
+            command();
+        }
+    }
+    _removeBody(body) {
+        const index = this._bodies.indexOf(body);
+        if (index === -1) {
+            // Never added (created and destroyed within the same dispatch) — still
+            // tear down its colliders and mark it dead.
+            this._teardownBody(body);
+            return;
+        }
+        this._bodies.splice(index, 1);
+        this._teardownBody(body);
+    }
+    _teardownBody(body) {
+        for (const collider of body.colliders) {
+            this._detachCollider(collider);
+        }
+        this._bindings.unbind(body);
+        body._markDestroyed();
+    }
+    _removeCollider(collider) {
+        this._detachCollider(collider);
+        collider.body._removeCollider(collider);
+    }
+    _detachCollider(collider) {
+        const index = this._colliders.indexOf(collider);
+        if (index !== -1) {
+            this._colliders.splice(index, 1);
+        }
+        this._backend.removeCollider(collider);
+        collider._markDestroyed();
+    }
+    _assertAlive() {
+        if (this._destroyed) {
+            throw new Error('PhysicsWorld: the world has been destroyed.');
+        }
+    }
+}
+
+export { PhysicsWorld };
+//# sourceMappingURL=PhysicsWorld.js.map

package/dist/esm/PhysicsWorld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicsWorld.js","sources":["../../../src/PhysicsWorld.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/TimeStepper.d.ts

@@ -0,0 +1,39 @@
+/** Construction options for {@link TimeStepper}. */
+export interface TimeStepperOptions {
+    /** Fixed simulation timestep in seconds. Default `1 / 60`. Must be > 0. */
+    fixedDelta?: number;
+    /** Maximum sub-steps consumed per `advance` call (spiral-of-death guard). Default `8`. Must be ≥ 1. */
+    maxSubSteps?: number;
+}
+/**
+ * Fixed-timestep accumulator (package-owned; no engine clock dependency). Each
+ * frame, {@link advance} adds the variable frame delta to an internal
+ * accumulator and reports how many whole fixed sub-steps to run
+ * (`floor(accumulator / fixedDelta)`), clamped to {@link maxSubSteps}. When the
+ * clamp trips, the backlog beyond the clamp is discarded so a slow frame cannot
+ * cascade into an unbounded catch-up (the "spiral of death").
+ *
+ * {@link alpha} is the leftover fraction of a step `[0, 1)`, for interpolating
+ * bound transforms between sub-steps.
+ *
+ * The stepper holds no mutable module-level state — two stepper instances are
+ * fully independent (world isolation, gate I-1).
+ */
+export declare class TimeStepper {
+    readonly fixedDelta: number;
+    readonly maxSubSteps: number;
+    private _accumulator;
+    constructor(options?: TimeStepperOptions);
+    /** Unconsumed accumulated time (seconds) currently held, always `< fixedDelta` after an `advance`. */
+    get accumulator(): number;
+    /** Interpolation fraction in `[0, 1)` = `accumulator / fixedDelta`. */
+    get alpha(): number;
+    /**
+     * Accumulate `frameDeltaSeconds` and return the number of fixed sub-steps to
+     * run this frame. Non-finite or non-positive deltas contribute nothing and
+     * return `0`.
+     */
+    advance(frameDeltaSeconds: number): number;
+    /** Clear the accumulator (e.g. after a teleport or a pause). */
+    reset(): void;
+}