murow 0.1.1 → 0.1.3

package/dist/types/core/hitbox/hitbox.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hitbox — a named set of collision shapes in model-local space.
+ *
+ * Declared once and shared across every prefab/instance that uses it. Pure
+ * data: no GPU, no per-instance state. The renderer picks against it; game
+ * logic and a headless server run authoritative hit tests against the same
+ * object. Shapes are scaled by instance scale at test time.
+ *
+ * The mode parameter (`'2d'` | `'3d'`) gates which shapes `add` accepts and
+ * accumulates the part-name union so consumers can narrow `hit.part`.
+ */
+export type Shape3D = {
+    readonly shape: 'sphere';
+    readonly radius: number;
+    readonly offset?: readonly [number, number, number];
+} | {
+    readonly shape: 'box';
+    readonly size: readonly [number, number, number];
+    readonly offset?: readonly [number, number, number];
+} | {
+    readonly shape: 'cylinder';
+    readonly radius: number;
+    readonly height: number;
+    readonly offset?: readonly [number, number, number];
+};
+export type Shape2D = {
+    readonly shape: 'circle';
+    readonly radius: number;
+    readonly offset?: readonly [number, number];
+} | {
+    readonly shape: 'rect';
+    readonly size: readonly [number, number];
+    readonly offset?: readonly [number, number];
+} | {
+    readonly shape: 'capsule';
+    readonly radius: number;
+    readonly length: number;
+    readonly offset?: readonly [number, number];
+};
+export type ShapeForMode<M extends '2d' | '3d'> = M extends '3d' ? Shape3D : Shape2D;
+export type HitboxPart<M extends '2d' | '3d'> = {
+    readonly name: string;
+} & ShapeForMode<M>;
+export declare class Hitbox<M extends '2d' | '3d' = '3d', Names extends string = never> {
+    readonly mode: M;
+    readonly parts: readonly HitboxPart<M>[];
+    constructor(mode: M, parts?: readonly HitboxPart<M>[]);
+    /** Add a named shape. Returns a new Hitbox whose type carries the added name. */
+    add<const N extends string>(name: N, shape: ShapeForMode<M>): Hitbox<M, Names | N>;
+}

package/dist/types/core/hitbox/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hitbox';
+export * from './hitbox-library';
+export * from './test';

package/dist/types/core/hitbox/test.d.ts

@@ -0,0 +1,44 @@
+import type { Ray3D } from '../ray/ray-3d';
+import type { Hitbox, HitboxPart } from './hitbox';
+/** Nearest part struck plus where. The `point` is filled in 3D only. */
+export interface PartHit {
+    part: string;
+    distance: number;
+    point: [number, number, number];
+}
+/**
+ * A 3D part resolved to world space: its center after offset, and the
+ * half-extents after per-axis scale. Single-radius shapes (sphere,
+ * cylinder) inflate by the largest relevant axis so they enclose a
+ * non-uniformly scaled visual rather than clipping inside it. The single
+ * source of placement truth shared by picking and debug rendering.
+ */
+export interface PlacedPart {
+    cx: number;
+    cy: number;
+    cz: number;
+    hx: number;
+    hy: number;
+    hz: number;
+}
+/** Place a 3D part at world center `(cx,cy,cz)` grown by scale `(sx,sy,sz)`. Reused output. */
+export declare function placePart3D(part: HitboxPart<'3d'>, cx: number, cy: number, cz: number, sx: number, sy: number, sz: number): PlacedPart;
+/**
+ * Entry-test a ray against a 3D hitbox placed at world center `(cx,cy,cz)`
+ * and grown by per-axis scale `(sx,sy,sz)`. Returns the nearest part the
+ * ray enters (a reused object, valid until the next call) or `null`.
+ */
+export declare function testHitbox3D(ray: Ray3D, hitbox: Hitbox<'3d'>, cx: number, cy: number, cz: number, sx: number, sy: number, sz: number): PartHit | null;
+/**
+ * Point-test against a 2D hitbox at center `(cx,cy)`, scaled `(sx,sy)`,
+ * rotated by `rot` radians. The world point is rotated into the hitbox's
+ * local frame, then tested against each part. Returns the first part
+ * containing the point (a reused object) or `null`.
+ */
+export declare function testHitbox2D(hitbox: Hitbox<'2d'>, cx: number, cy: number, sx: number, sy: number, rot: number, wx: number, wy: number): PartHit | null;
+/**
+ * Point inside a sprite's rendered quad: an `sx` by `sy` rect centered at
+ * `(cx,cy)`, rotated by `rot`. The default pick bound for a sprite with no
+ * declared hitbox.
+ */
+export declare function pointInQuad2D(cx: number, cy: number, sx: number, sy: number, rot: number, wx: number, wy: number): boolean;

package/dist/types/core/index.d.ts

@@ -7,9 +7,15 @@ export * from './driver';
 export * from './navmesh';
 export * from './pooled-codec';
 export * from './prediction';
+export * from './clock';
+export * from './timeline';
 export * from './input';
 export * from './free-list';
 export * from './sparse-batcher';
+export * from './slot-map';
+export * from './state-machine';
 export * from './simple-rng';
 export * from './ray';
+export * from './raycast';
+export * from './hitbox';
 export * from '../renderer';

package/dist/types/core/prediction/prediction.d.ts

@@ -1,65 +1,42 @@
 /**
- * @template T
- * @description
- * Tracks client-side intents that have been sent to the server but not yet confirmed.
- * Used for prediction and reconciliation in a server-authoritative architecture.
+ * Bounded, sequence-ordered log of locally-applied commands awaiting
+ * confirmation. Records are pushed in ascending sequence; `dropThrough`
+ * removes everything the authority has confirmed.
  */
-export declare class IntentTracker<T> {
-    tracker: Map<number, T[]>;
+export declare class PredictionLog<Cmd> {
+    private capacity;
+    private entries;
+    constructor(capacity?: number);
     get size(): number;
-    /**
-     * Adds a new intent for a specific tick.
-     * @param {number} tick - The tick number associated with the intent.
-     * @param {T} intent - The intent data.
-     */
-    track(tick: number, intent: T): T;
-    /**
-     * Removes all intents up to and including a given tick.
-     * Returns the remaining intents in ascending tick order.
-     * @param {number} tick - The tick up to which intents should be dropped.
-     * @returns {T[]} Array of remaining intents.
-     */
-    dropUpTo(tick: number): T[];
-    /**
-     * Returns all currently tracked intents in ascending tick order.
-     * @returns {T[]}
-     */
-    values(): T[];
+    /** Record a command with its sequence. Commands must be recorded in ascending sequence. */
+    record(sequence: number, cmd: Cmd): void;
+    /** Drop every entry with sequence <= the confirmed sequence. */
+    dropThrough(sequence: number): void;
+    /** The commands still awaiting confirmation, in order. */
+    pending(): Cmd[];
+    clear(): void;
+}
+export interface ReconcilerOptions<Cmd, Ctx> {
+    /** Max unconfirmed commands kept; older ones are dropped. Default 64. */
+    bufferSize?: number;
+    /** Load authoritative state. Runs before confirmed commands are dropped. */
+    restore: (ctx: Ctx) => void;
+    /** Re-apply the still-unconfirmed commands on top of the restored state. */
+    replay: (cmds: Cmd[], ctx: Ctx) => void;
 }
 /**
- * @template T,U
- * @description
- * Handles client-side reconciliation of authoritative snapshots with unconfirmed intents.
- * Used for prediction correction in server-authoritative multiplayer games.
+ * Client-side rollback-replay: record locally-applied commands, and when the
+ * authority confirms up to a sequence, restore its state, drop the confirmed
+ * commands, and replay the rest. Domain-agnostic; the caller supplies what a
+ * command is, how to restore, and how to replay via callbacks.
  */
-export declare class Reconciliator<T, U> {
-    private options;
-    tracker: IntentTracker<T>;
-    /**
-     * @param {Object} options - Callbacks for applying snapshot state and replaying intents.
-     * @param {(snapshotState: U) => void} options.onLoadState - Called to load authoritative snapshot state.
-     * @param {(remainingIntents: T[]) => void} options.onReplay - Called to reapply remaining intents for prediction.
-     */
-    constructor(options: {
-        onLoadState: (snapshotState: U) => void;
-        onReplay: (remainingIntents: T[]) => void;
-    });
-    /**
-     * Adds a new intent to the tracker.
-     * @param {number} tick - Tick number associated with the intent.
-     * @param {T} intent - The intent data.
-     */
-    trackIntent(tick: number, intent: T): void;
-    /**
-     * Called when an authoritative snapshot is received from the server.
-     * Resets client state and replays unconfirmed intents.
-     * @param {Object} snapshot - The snapshot from the server.
-     * @param {number} snapshot.tick - Tick number of the snapshot.
-     * @param {U} snapshot.state - The authoritative state.
-     */
-    onSnapshot(snapshot: {
-        tick: number;
-        state: U;
-    }): void;
-    replay(intents: T[]): void;
+export declare class Reconciler<Cmd, Ctx = void> {
+    private log;
+    private restore;
+    private replay;
+    constructor(opts: ReconcilerOptions<Cmd, Ctx>);
+    record(sequence: number, cmd: Cmd): void;
+    get pending(): number;
+    clear(): void;
+    reconcile(ackSequence: number, ctx: Ctx): void;
 }

package/dist/types/core/ray/ray-3d.d.ts

@@ -35,7 +35,27 @@ export declare class Ray3D {
      */
     intersectsAABB(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): number | null;
     /**
-     * Intersection with a triangle using the Möller–Trumbore algorithm.
+     * Sphere entry for picking: `t` to the nearest front-facing surface,
+     * or `null`. Unlike `intersectsSphere`, an origin inside the sphere or
+     * a sphere entirely behind the origin return `null` -- you only pick
+     * surfaces facing you.
+     */
+    entrySphere(cx: number, cy: number, cz: number, r: number): number | null;
+    /**
+     * Axis-aligned box entry for picking, given center and half-extents.
+     * `t` to the front face, or `null`. Origin-inside and fully-behind
+     * both return `null` (see `entrySphere`).
+     */
+    entryBox(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number): number | null;
+    /**
+     * Y-axis-aligned cylinder entry for picking: center `(cx,cy,cz)`,
+     * radius `r`, total height `h` (spans `cy +- h/2`). Side = 2D
+     * ray-vs-circle in XZ keeping in-range Y; caps = the two disk planes.
+     * Nearest candidate, or `null`; origin-inside is rejected.
+     */
+    entryCylinder(cx: number, cy: number, cz: number, r: number, h: number): number | null;
+    /**
+     * Intersection with a triangle using the Möller-Trumbore algorithm.
      * Returns `t` at the hit point, `null` if no hit.
      */
     intersectsTriangle(ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): number | null;

package/dist/types/core/raycast/hit-buffer.d.ts

@@ -0,0 +1,43 @@
+export interface BufferedHit<H, Point extends number[]> {
+    handle: H;
+    distance: number;
+    point: Point;
+    /** Name of the hitbox part struck, or `null` for a default-bound (sphere/box/quad) hit. */
+    part: string | null;
+}
+type Filter<H> = (handle: H) => boolean;
+export declare class HitBuffer<H, Point extends number[]> {
+    private handles;
+    private parts;
+    private keys;
+    private distances;
+    private px;
+    private py;
+    private pz;
+    private order;
+    count: number;
+    private capacity;
+    private sorted;
+    private readonly dims;
+    private nearestHit;
+    constructor(dims: 2 | 3);
+    private makeHit;
+    reset(): void;
+    /**
+     * `key` orders the hit (ascending = nearer); `distance` is the value
+     * the public hit reports. They differ only when ordering isn't by
+     * distance (e.g. 2D layer). `distance` defaults to `key`.
+     */
+    push(handle: H, key: number, x: number, y: number, z?: number, distance?: number, part?: string | null): void;
+    nearest(filter: Filter<H> | undefined, cap: number): BufferedHit<H, Point> | null;
+    collectInto(out: BufferedHit<H, Point>[], filter: Filter<H> | undefined, cap: number): void;
+    /**
+     * True if any live hit's handle matches `id` — comparing the handle
+     * directly when it is a number, or its `.id` when it is an object.
+     */
+    containsId(id: number): boolean;
+    private fill;
+    private grow;
+    private ensureSorted;
+}
+export {};

package/dist/types/core/raycast/index.d.ts

@@ -0,0 +1,2 @@
+export * from './hit-buffer';
+export * from './raycaster';

package/dist/types/core/raycast/raycaster.d.ts

@@ -0,0 +1,54 @@
+import type { Ray3D } from '../ray/ray-3d';
+import type { Hitbox } from '../hitbox/hitbox';
+import { type BufferedHit } from './hit-buffer';
+/** Per-axis column accessors. Each returns the field arrays for a frame's worth of entities. */
+interface Transform3D {
+    position: () => {
+        x: ArrayLike<number>;
+        y: ArrayLike<number>;
+        z: ArrayLike<number>;
+    };
+    scale: () => {
+        x: ArrayLike<number>;
+        y: ArrayLike<number>;
+        z: ArrayLike<number>;
+    };
+}
+interface Lookup {
+    /** Candidate ids to test this cast (e.g. an ECS query result). */
+    query: () => readonly number[];
+    /** Resolve an id to its hitbox, or `null` to skip it. */
+    hitbox: (id: number) => Hitbox<'3d'> | null;
+}
+type Hit = BufferedHit<number, [number, number, number]>;
+interface QueryOptions {
+    filter?: (id: number) => boolean;
+    maxDistance?: number;
+}
+/**
+ * Raycaster — casts a ray against a set of entities and ranks the hits.
+ *
+ * Source-agnostic: `lookup` supplies the candidate ids and their hitboxes,
+ * `configure` supplies how to read each id's transform. Both carry all
+ * world knowledge as closures, so the raycaster depends on neither an ECS
+ * nor a renderer. Owns a reused hit buffer; `cast` is allocation-free per
+ * entity. The same instance can be exported from shared code and wired to
+ * a sim world on the server and a render world on the client.
+ */
+export declare class Raycaster {
+    private buf;
+    private resultBuffer;
+    private _lookup;
+    private _transform;
+    /** Wire the candidate source: which ids to test and how to resolve each id's hitbox. */
+    lookup(lookup: Lookup): this;
+    /** Wire the transform source: how to read each id's position and scale. */
+    configure(transform: Transform3D): this;
+    /** Cast `ray` against the configured source, populating the hit buffer. Chains to `hit`/`hitAll`. */
+    cast(ray: Ray3D): this;
+    /** Nearest hit, or null. Pool-backed; valid until the next cast. */
+    hit(opts?: QueryOptions): Hit | null;
+    /** All hits, nearest first. Reused array; do not retain across casts. */
+    hitAll(opts?: QueryOptions): readonly Hit[];
+}
+export {};

package/dist/types/core/slot-map/index.d.ts

@@ -0,0 +1 @@
+export * from "./slot-map";

package/dist/types/core/slot-map/slot-map.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A branded integer id. Use `as SlotId<'light'>` (or your own brand) to keep
+ * a light id from being passed where an instance id is expected. Purely a
+ * compile-time tag — at runtime it is a plain number.
+ */
+export type SlotId<Brand extends string = string> = number & {
+    readonly __slot?: Brand;
+};
+/**
+ * Dense slot set. Slots are allocated from a fixed-capacity FreeList; the id
+ * returned by `add` IS the slot and stays stable until freed. Live slots are
+ * kept in a packed array (`activeSlots`) for cache-friendly iteration with no
+ * per-call allocation, and a sparse `Int32Array` maps slot -> dense position
+ * (`-1` when absent) for O(1) membership and removal.
+ */
+export declare class SlotMap {
+    private readonly freeList;
+    /** Packed live slots, valid for `[0, size)`. Iterate this. */
+    private readonly dense;
+    /** slot -> index into `dense`, or `-1` if the slot is not live. */
+    private readonly sparse;
+    private _size;
+    private readonly _capacity;
+    constructor(capacity: number);
+    /**
+     * Allocate a slot and add it to the live set.
+     * @returns the slot, or `-1` if the pool is exhausted.
+     */
+    add(): number;
+    /**
+     * Remove a slot from the live set and return it to the pool. Keeps `dense`
+     * packed by swapping the last live slot into the freed position and fixing
+     * its sparse entry. No-op if the slot is not live.
+     */
+    remove(slot: number): void;
+    /** Whether `slot` is currently live. O(1). */
+    has(slot: number): boolean;
+    /**
+     * The packed live-slot array. Valid for indices `[0, size)`; entries past
+     * `size` are stale. Reused across calls — do not retain.
+     */
+    get activeSlots(): Uint32Array;
+    /** Number of live slots. Iterate `activeSlots` over `[0, size)`. */
+    get size(): number;
+    /** Configured capacity (max simultaneously live slots). */
+    get capacity(): number;
+    /** Whether another slot can be allocated. */
+    hasAvailable(): boolean;
+    /**
+     * Iterate live slots in packed order. Zero allocations. Removing the
+     * current slot inside the callback is safe (swap-and-pop), but the
+     * swapped-in slot then occupies the current index — guard accordingly or
+     * iterate `activeSlots` manually if you need full control.
+     */
+    forEach(fn: (slot: number, index: number) => void): void;
+    /** Empty the set, returning every slot to the pool. */
+    clear(): void;
+}
+/**
+ * Dense object set keyed by an external id. Wraps a SlotMap (slot lifecycle +
+ * dense iteration) and a slot-indexed object array, plus a sparse id -> slot
+ * map so the external id need not equal the slot. The typed, tested
+ * replacement for `Map<id, T>` collections you iterate every frame.
+ *
+ * `capacity` caps how many items can be live at once. `maxId` sizes the id
+ * lookup table and defaults to `capacity`; pass it when ids come from a larger
+ * space than the store holds (e.g. a 256-slot archetype store keyed by ECS
+ * entity ids drawn from `maxEntities`). Ids must be non-negative integers
+ * below `maxId`. If your identity is a string or otherwise non-integer, keep a
+ * `Map<string, number>` at the boundary that translates it to a dense id once.
+ */
+export declare class SlotStore<TId extends number, T> {
+    private readonly slots;
+    /** slot -> stored item. */
+    private readonly items;
+    /** external id -> slot, or `-1` if the id is not present. Sized by maxId. */
+    private readonly idToSlot;
+    /** slot -> external id (so dense iteration can report the id). */
+    private readonly slotToId;
+    private readonly _maxId;
+    constructor(capacity: number, maxId?: number);
+    /**
+     * Store `item` under `id`. Allocates a slot. Throws if `id` is already
+     * present or the pool is exhausted.
+     * @returns the allocated slot.
+     */
+    add(id: TId, item: T): number;
+    /** Remove the item stored under `id`. No-op if absent or out of range. */
+    remove(id: TId): void;
+    /** The item stored under `id`, or `null` if absent or out of range. O(1). */
+    get(id: TId): T | null;
+    /** Whether `id` is present. O(1). */
+    has(id: TId): boolean;
+    /** The stable slot for `id`, or `-1` if absent or out of range. */
+    slotOf(id: TId): number;
+    /** Number of stored items. */
+    get size(): number;
+    /** Configured capacity. */
+    get capacity(): number;
+    /** Whether another item can be added. */
+    hasAvailable(): boolean;
+    /**
+     * Iterate stored items in packed order. Zero allocations. The callback
+     * receives the item, its external id, and its slot.
+     */
+    forEach(fn: (item: T, id: TId, slot: number) => void): void;
+    /** Remove every item. */
+    clear(): void;
+}

package/dist/types/core/state-machine/index.d.ts

@@ -0,0 +1 @@
+export * from "./state-machine";

package/dist/types/core/state-machine/state-machine.d.ts

@@ -0,0 +1,114 @@
+import { EventSystem } from "../events";
+import { SimpleRNG } from "../simple-rng";
+import type { Field } from "../binary-codec";
+type Schema = Record<string, Field<any>>;
+type StatesSpec = Record<string, Schema>;
+type FieldValue<F> = F extends Field<infer T, any> ? T : never;
+type SchemaValues<Sc extends Schema> = {
+    -readonly [K in keyof Sc]: FieldValue<Sc[K]>;
+};
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type StateFields<S extends StatesSpec> = UnionToIntersection<{
+    [K in keyof S]: SchemaValues<S[K]>;
+}[keyof S]>;
+/**
+ * Per-entity cursor over the machine's columns. Reused for the entity's
+ * lifetime; reading a field returns that entity's value, writing sets it.
+ */
+export type Handle<S extends StatesSpec> = HandleBase<S> & StateFields<S>;
+interface HandleBase<S extends StatesSpec> {
+    readonly id: number;
+    readonly state: keyof S & string;
+    readonly stateId: number;
+    readonly ticksInState: number;
+    is(state: keyof S & string): boolean;
+    change(to: (keyof S & string) | number, payload?: number): void;
+}
+interface Handlers<H> {
+    enter?(handle: H, payload: number): void;
+    update?(handle: H): void;
+    exit?(handle: H): void;
+}
+interface ChangeEvent {
+    id: number;
+    from: number;
+    to: number;
+}
+type ChangeEvents = [["change", ChangeEvent]];
+interface StateMachineOptions<S extends StatesSpec> {
+    initial: keyof S & string;
+    states: S;
+    capacity?: number;
+    maxId?: number;
+    rng?: SimpleRNG;
+}
+/**
+ * Fixed-capacity, zero-GC state machine over many entities. State and
+ * per-state data live in binary columns indexed by a stable slot; one machine
+ * definition drives every entity. Behavior is registered per state with `add`
+ * and runs during `tick`. Depends only on `SlotStore`, `EventSystem`,
+ * `SimpleRNG`, and `BinaryCodec` fields.
+ */
+export declare class StateMachine<S extends StatesSpec> {
+    /** State name to numeric id. */
+    readonly id: {
+        readonly [K in keyof S & string]: number;
+    };
+    readonly rng: SimpleRNG;
+    /** Transition channel, emitted whenever any entity changes state. */
+    readonly events: EventSystem<ChangeEvents>;
+    private readonly names;
+    private readonly initialId;
+    private readonly store;
+    private readonly stateCol;
+    private readonly prevCol;
+    private readonly enteredCol;
+    private readonly cols;
+    private readonly fieldsByState;
+    private readonly enterFns;
+    private readonly updateFns;
+    private readonly exitFns;
+    private readonly Handle;
+    private now;
+    private ticking;
+    private readonly dead;
+    private readonly ev;
+    constructor(opts: StateMachineOptions<S>);
+    /** Number of live entities. */
+    get size(): number;
+    /**
+     * Register behavior for a state. Cumulative: calling `add` again for the
+     * same state appends another set of handlers. Returns the machine for
+     * chaining.
+     */
+    add(state: keyof S & string, handlers: Handlers<Handle<S>>): this;
+    /** Register an entity by id, in the initial state. Returns its handle. */
+    spawn(id: number): Handle<S>;
+    /** The handle for `id`, or `null` if absent. */
+    of(id: number): Handle<S> | null;
+    has(id: number): boolean;
+    /** Remove an entity. Deferred to the end of the pass if called during `tick`. */
+    remove(id: number): void;
+    /**
+     * Advance every entity by one step. Runs the current state's `update`
+     * handlers in registration order; the first that transitions ends that
+     * entity's chain for this step.
+     */
+    tick(): void;
+    /**
+     * Write an entity's state id and current-state fields into `dv` at
+     * `offset`. Returns the offset past the written bytes.
+     */
+    serialize(id: number, dv: DataView, offset: number): number;
+    /**
+     * Load an entity's state id and fields from `dv` at `offset`, re-anchoring
+     * its `ticksInState`. Returns the offset past the read bytes.
+     */
+    restore(id: number, dv: DataView, offset: number): number;
+    /** Serialized byte size of an entity in its current state. */
+    byteSize(id: number): number;
+    private readonly step;
+    private transition;
+    private buildHandle;
+}
+export {};

package/dist/types/core/timeline/index.d.ts

@@ -0,0 +1 @@
+export { Timeline, type TimelineEntry } from './timeline';

package/dist/types/core/timeline/timeline.d.ts

@@ -0,0 +1,34 @@
+export interface TimelineEntry<S> {
+    tick: number;
+    receivedAt: number;
+    sample: S;
+}
+/**
+ * A bounded, tick-ordered ring of timestamped samples. Inserts in tick order
+ * (dedup by tick), prunes to capacity, and drops history when a wall-clock gap
+ * exceeds the stale window. Knows nothing about what a sample contains.
+ */
+export declare class Timeline<S> {
+    private entries;
+    private _latestReceivedAt;
+    capacity: number;
+    staleWindow: number;
+    constructor(capacity: number, staleWindowMs: number);
+    get length(): number;
+    get latestReceivedAt(): number;
+    at(index: number): TimelineEntry<S>;
+    newest(): TimelineEntry<S> | undefined;
+    oldest(): TimelineEntry<S> | undefined;
+    setStaleWindow(staleWindowMs: number): void;
+    clear(): void;
+    /**
+     * Insert a sample in tick order. Returns true if a wall-clock gap beyond
+     * the stale window dropped the existing history first.
+     */
+    record(tick: number, receivedAt: number, sample: S): boolean;
+    /**
+     * Indices `[a, b]` of the consecutive entries straddling `tick`
+     * (`entries[a].tick <= tick <= entries[b].tick`), or null if none.
+     */
+    straddle(tick: number): [number, number] | null;
+}

package/dist/types/game/loop/loop.d.ts

@@ -29,6 +29,7 @@ export declare class GameLoop<T extends GameLoopType = DriverType> {
     private _tickData;
     private _skipData;
     private _renderData;
+    private _scheduler;
     constructor(options: GameLoopOptions<T>);
     step(deltaTime: number): void;
     /**
@@ -47,10 +48,39 @@ export declare class GameLoop<T extends GameLoopType = DriverType> {
      * Stops the game ticker and emits a 'stop' event.
      */
     stop(): void;
+    /**
+     * Registers a callback to run on a fixed tick interval.
+     *
+     * The unit methods resolve to a tick count from the loop's `tickRate`, so
+     * every schedule fires in lockstep with the simulation regardless of unit.
+     *
+     * @example
+     * const id = loop.every(2).seconds(spawnWave);
+     * loop.clearSchedule(id);
+     */
+    every(count: number): ScheduleBuilder;
+    /**
+     * Cancels a single schedule by the id returned from `every`.
+     */
+    clearSchedule(id: number): boolean;
+    /**
+     * Cancels every registered schedule.
+     */
+    clearSchedules(): void;
+}
+interface ScheduleBuilder {
+    ticks(cb: () => void): number;
+    seconds(cb: () => void): number;
+    milliseconds(cb: () => void): number;
 }
 interface GameLoopOptions<T extends GameLoopType> {
     tickRate: number;
     type: T;
+    /**
+     * Maximum number of simultaneously live schedules registered via `every`.
+     * Defaults to 32.
+     */
+    maxSchedules?: number;
     onTick?: (deltaTime: number, tick: number, input: ReturnType<InputManager["snapshot"]>) => void;
     onRender?: (deltaTime: number, alpha: number, input: ReturnType<InputManager["peek"]>) => void;
 }