@jgengine/core 0.10.0 → 0.12.0

package/dist/orders/orderKinds.js

@@ -0,0 +1,197 @@
+/**
+ * The reusable order verbs every commandable game re-derives -- move, stop,
+ * hold, attack-move, targeted action, patrol -- built as ordinary
+ * `OrderKind`s over two narrow world adapters, not baked into the queue (#912).
+ * Each factory takes a configurable `kind` string, so a game re-skins a verb
+ * ("harvest", "board") without the engine ever knowing the name. Movement,
+ * target acquisition, pursuit/leash, and completion predicates compose here;
+ * effect execution stays game-side, driven off the intent each kind writes into
+ * `order.state`.
+ */
+const RUNNING = { status: "running" };
+const COMPLETED = { status: "completed" };
+const DEFAULT_ARRIVE = 0.6;
+function gone() {
+    return { status: "failed", reason: "mover has no position (despawned)" };
+}
+/**
+ * The plain "go here" verb: step toward a point each tick, complete on arrival,
+ * fail if the entity despawns. The completion predicate is arrival within
+ * `arriveRadius`.
+ *
+ * @capability move-order go-to-point order that completes on arrival, composed over a motion adapter
+ */
+export function defineMoveOrder(config = {}) {
+    const arriveDefault = config.arriveRadius ?? DEFAULT_ARRIVE;
+    return {
+        kind: config.kind ?? "move",
+        validate: (payload) => (Array.isArray(payload.point) ? null : { reason: "move order requires a point." }),
+        start: () => ({ ok: true }),
+        update(order, ctx) {
+            if (ctx.position() === null)
+                return gone();
+            const arriveRadius = order.payload.arriveRadius ?? arriveDefault;
+            const result = ctx.moveToward(order.payload.point, { arriveRadius, speedScale: order.payload.speedScale });
+            return result.arrived ? COMPLETED : RUNNING;
+        },
+        finish: (_order, ctx) => ctx.halt(),
+    };
+}
+/**
+ * Stop: halt immediately and complete the same tick — the interrupt that clears
+ * a unit's intent to standstill.
+ *
+ * @capability stop-order halt-and-complete order that brings a unit to an immediate standstill
+ */
+export function defineStopOrder(config = {}) {
+    return {
+        kind: config.kind ?? "stop",
+        start(_order, ctx) {
+            ctx.halt();
+            return { ok: true };
+        },
+        update: () => COMPLETED,
+    };
+}
+/**
+ * Hold position: stand ground indefinitely (never completes on its own) until
+ * preempted or canceled — the "guard here" verb.
+ *
+ * @capability hold-order stand-ground order that holds position until preempted or canceled
+ */
+export function defineHoldOrder(config = {}) {
+    return {
+        kind: config.kind ?? "hold",
+        start(_order, ctx) {
+            ctx.halt();
+            return { ok: true };
+        },
+        update(_order, ctx) {
+            return ctx.position() === null ? gone() : RUNNING;
+        },
+    };
+}
+/**
+ * Attack-move: advance toward a destination but break off to engage any hostile
+ * acquired within `aggroRadius`, pursuing it to `attackRange` and writing the
+ * engagement intent into `order.state` for the game to act on. Completes on
+ * reaching the destination with nothing to engage.
+ *
+ * @capability attack-move-order advance-and-engage order that pursues hostiles en route and completes at its destination
+ */
+export function defineAttackMoveOrder(config = {}) {
+    const arriveDefault = config.arriveRadius ?? DEFAULT_ARRIVE;
+    const aggroDefault = config.aggroRadius ?? 6;
+    const attackDefault = config.attackRange ?? 1.5;
+    return {
+        kind: config.kind ?? "attack-move",
+        validate: (payload) => (Array.isArray(payload.point) ? null : { reason: "attack-move order requires a point." }),
+        start(order) {
+            order.state = { engaging: null, inRange: false };
+            return { ok: true };
+        },
+        update(order, ctx) {
+            const position = ctx.position();
+            if (position === null)
+                return gone();
+            const state = order.state;
+            const attackRange = order.payload.attackRange ?? attackDefault;
+            // Keep the current target if it is still alive, else re-acquire.
+            let targetPos = state.engaging !== null ? ctx.positionOf(state.engaging) : null;
+            if (targetPos === null) {
+                const acquired = ctx.acquire(order.payload.aggroRadius ?? aggroDefault);
+                state.engaging = acquired;
+                targetPos = acquired !== null ? ctx.positionOf(acquired) : null;
+            }
+            if (state.engaging !== null && targetPos !== null) {
+                const result = ctx.moveToward(targetPos, { arriveRadius: attackRange, speedScale: order.payload.speedScale });
+                state.inRange = result.arrived;
+                return RUNNING;
+            }
+            state.engaging = null;
+            state.inRange = false;
+            const result = ctx.moveToward(order.payload.point, {
+                arriveRadius: order.payload.arriveRadius ?? arriveDefault,
+                speedScale: order.payload.speedScale,
+            });
+            return result.arrived ? COMPLETED : RUNNING;
+        },
+        finish: (_order, ctx) => ctx.halt(),
+    };
+}
+/**
+ * Targeted action: pursue one specific target until within `range`, writing the
+ * engagement intent into `order.state`. Completes when the target is gone
+ * (despawned/dead), so the game's effect loop runs while `inRange` is true.
+ *
+ * @capability targeted-order pursue-a-target order with leash/standoff that ends when the target is gone
+ */
+export function defineTargetedOrder(config = {}) {
+    const rangeDefault = config.range ?? 1.5;
+    return {
+        kind: config.kind ?? "targeted",
+        validate: (payload) => (typeof payload.targetId === "string" && payload.targetId !== "" ? null : { reason: "targeted order requires a targetId." }),
+        start(order) {
+            order.state = { engaging: order.payload.targetId, inRange: false };
+            return { ok: true };
+        },
+        update(order, ctx) {
+            if (ctx.position() === null)
+                return gone();
+            const state = order.state;
+            const targetPos = ctx.positionOf(order.payload.targetId);
+            if (targetPos === null)
+                return COMPLETED; // target gone -> objective resolved
+            const range = order.payload.range ?? rangeDefault;
+            const result = ctx.moveToward(targetPos, { arriveRadius: range, speedScale: order.payload.speedScale });
+            state.inRange = result.arrived;
+            return RUNNING;
+        },
+        finish: (_order, ctx) => ctx.halt(),
+    };
+}
+/**
+ * Patrol: walk a waypoint route, advancing the serialized `index` as each point
+ * is reached. Loops forever by default, or completes at the last waypoint when
+ * `loop` is `false`.
+ *
+ * @capability patrol-order waypoint-route order that cycles a path, looping or completing at the end
+ */
+export function definePatrolOrder(config = {}) {
+    const arriveDefault = config.arriveRadius ?? DEFAULT_ARRIVE;
+    return {
+        kind: config.kind ?? "patrol",
+        validate: (payload) => Array.isArray(payload.waypoints) && payload.waypoints.length > 0 ? null : { reason: "patrol order requires at least one waypoint." },
+        start(order) {
+            order.state = { index: 0 };
+            return { ok: true };
+        },
+        update(order, ctx) {
+            if (ctx.position() === null)
+                return gone();
+            const state = order.state;
+            const waypoints = order.payload.waypoints;
+            const loop = order.payload.loop ?? true;
+            const target = waypoints[state.index];
+            if (target === undefined)
+                return COMPLETED;
+            const result = ctx.moveToward(target, {
+                arriveRadius: order.payload.arriveRadius ?? arriveDefault,
+                speedScale: order.payload.speedScale,
+            });
+            if (!result.arrived)
+                return RUNNING;
+            const next = state.index + 1;
+            if (next >= waypoints.length) {
+                if (!loop)
+                    return COMPLETED;
+                state.index = 0;
+            }
+            else {
+                state.index = next;
+            }
+            return RUNNING;
+        },
+        finish: (_order, ctx) => ctx.halt(),
+    };
+}

package/dist/orders/orderQueue.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Composable entity orders: a serializable command queue with lifecycle,
+ * preemption, and pluggable order kinds (#912). Player- or AI-issued intent
+ * ("move here", "attack that", "patrol this route") becomes reusable data
+ * instead of a hard-coded RTS verb kit. The queue owns issue -> activate ->
+ * tick -> complete/cancel lifecycle and deterministic preemption policy; each
+ * order KIND owns what "running" means, composed over narrow world adapters.
+ * Engine code never branches on `move`, `attack`, or any game verb -- kinds are
+ * looked up by string in a registry, so a game adds a verb by registering data.
+ */
+/** XZ+Y position triple, matching the engine heading convention used across `movement`/`scene`. */
+export type OrderVec3 = readonly [number, number, number];
+/** Lifecycle phase of a single order. `queued` waits behind the active order; `active` is ticking; `completed`/`canceled` are terminal. */
+export type OrderPhase = "queued" | "active" | "completed" | "canceled";
+/**
+ * Why an order left the queue without completing. `replaced`/`preempted` come
+ * from a newer order taking over; `requested` from explicit `cancelActive`;
+ * `invalid` when the kind's `start` rejects; `failed` when `update` reports
+ * failure; `cleared` from a full `clear`/`cancelAll`.
+ */
+export type OrderCancelReason = "replaced" | "preempted" | "requested" | "invalid" | "failed" | "cleared";
+/**
+ * One issued order. Fully serializable: `kind` is a registry key (not a
+ * closure), `payload` is the caller's plain data, and `state` is the kind's own
+ * plain progress scratch (e.g. a patrol waypoint index) written during
+ * `start`/`update`. Never holds functions, so the whole queue round-trips
+ * through `JSON`/`structuredClone`.
+ */
+export interface Order<TPayload = unknown> {
+    /** Stable id, caller-supplied or generated deterministically by the queue. */
+    readonly id: string;
+    /** Registry key selecting the order kind. */
+    readonly kind: string;
+    /** Caller data the kind interprets (destination, target id, waypoints, ...). */
+    readonly payload: TPayload;
+    /** Current lifecycle phase; the queue owns transitions. */
+    phase: OrderPhase;
+    /** When `true`, preemption policies may not cancel this order mid-flight; a replacing order waits until it finishes. */
+    uninterruptible: boolean;
+    /** Optional authority tag (which player/AI issued it) carried for replication/audit; the queue does not interpret it. */
+    issuer?: string;
+    /** Kind-owned serializable progress; `undefined` until the kind activates. */
+    state?: unknown;
+    /** Set once `phase === "canceled"`. */
+    cancelReason?: OrderCancelReason;
+}
+/** A kind's refusal of a payload (from `validate`) — surfaced to the issuer as a rejection reason. */
+export interface OrderRejection {
+    reason: string;
+}
+/** Result of a kind's `start`: `ok:false` skips the order and cancels it with reason `invalid`. The kind seeds `order.state` directly when `ok:true`. */
+export type OrderStartResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Result of a kind's `update` tick. `running` keeps the order active; the
+ * completion predicate lives in the kind (returns `completed`); `failed` cancels
+ * the order (reason `failed`) so the queue advances to the next one.
+ */
+export type OrderProgress = {
+    status: "running";
+} | {
+    status: "completed";
+} | {
+    status: "failed";
+    reason: string;
+};
+/** Terminal outcome handed to a kind's `finish` cleanup hook. */
+export interface OrderOutcome {
+    phase: "completed" | "canceled";
+    reason?: OrderCancelReason;
+}
+/**
+ * The composition seam for one order verb. `TCtx` is the game's world adapter
+ * (movement, targeting, effects) shared by every kind in a registry; `TPayload`
+ * is this verb's caller data. `start` seeds `order.state`, `update` advances it
+ * and reports lifecycle, and `finish` releases anything the kind held. Kinds are
+ * pure over their injected `ctx` -- no globals, no direct scene reach.
+ */
+export interface OrderKind<TCtx, TPayload = unknown> {
+    /** The registry key; also the default `Order.kind` for issues of this verb. */
+    readonly kind: string;
+    /** Reject a malformed payload before it ever queues. */
+    validate?(payload: TPayload): OrderRejection | null;
+    /** Called once when the order becomes active. Seed `order.state` here; return `ok:false` to skip it. */
+    start(order: Order<TPayload>, ctx: TCtx): OrderStartResult;
+    /** Advance one tick. Read/write `order.state`; drive the world through `ctx`; report lifecycle. */
+    update(order: Order<TPayload>, ctx: TCtx, dt: number): OrderProgress;
+    /** Cleanup hook on completion or cancellation (stop movement, drop reservations). */
+    finish?(order: Order<TPayload>, ctx: TCtx, outcome: OrderOutcome): void;
+}
+/** Registry of order kinds keyed by verb string; the queue dispatches through it so engine code never switches on a verb. */
+export interface OrderRegistry<TCtx> {
+    /** Register a kind under `kind.kind`; throws on a duplicate key. */
+    define<TPayload>(kind: OrderKind<TCtx, TPayload>): void;
+    has(kind: string): boolean;
+    /** Look up a kind, or `null` if unregistered. */
+    get(kind: string): OrderKind<TCtx, unknown> | null;
+    /** All registered verb keys, in insertion order. */
+    kinds(): string[];
+}
+/**
+ * How a newly issued order interacts with what's already queued.
+ * `replace` preempts the active order and clears pending; `append` queues it
+ * behind everything (shift-queue); `front` makes it the next to run without
+ * touching the active order; `reject` refuses it while anything is queued.
+ */
+export type OrderQueuePolicy = "replace" | "append" | "front" | "reject";
+/** A request to issue an order; `policy` defaults to `replace`, `id` is generated when omitted. */
+export interface OrderRequest<TPayload = unknown> {
+    kind: string;
+    payload: TPayload;
+    id?: string;
+    policy?: OrderQueuePolicy;
+    uninterruptible?: boolean;
+    issuer?: string;
+}
+/** Outcome of `issue`: `accepted` entered the queue, `queued` entered behind an uninterruptible/active order, `rejected` was refused (validation or `reject` policy). */
+export type OrderIssueResult<TPayload = unknown> = {
+    status: "accepted";
+    order: Order<TPayload>;
+} | {
+    status: "queued";
+    order: Order<TPayload>;
+} | {
+    status: "rejected";
+    reason: string;
+};
+/** Serializable snapshot of a queue: the active order plus the pending list, in order. */
+export interface OrderQueueState<TPayload = unknown> {
+    active: Order<TPayload> | null;
+    pending: Order<TPayload>[];
+}
+/** A lifecycle event emitted synchronously as orders move through the queue. */
+export interface OrderEvent {
+    type: "issued" | "activated" | "completed" | "canceled";
+    orderId: string;
+    kind: string;
+    reason?: OrderCancelReason;
+}
+/** What one `tick` did this frame, for tests and game reactions (play a bark on activation, flash on completion). Bounded per tick. */
+export interface OrderTickReport<TPayload = unknown> {
+    active: Order<TPayload> | null;
+    activated: string[];
+    completed: string[];
+    canceled: {
+        id: string;
+        reason: OrderCancelReason;
+    }[];
+}
+/** Construction options for a queue. */
+export interface OrderQueueOptions<TPayload = unknown> {
+    /** Deterministic id source for orders issued without an `id`; defaults to a monotonic `order-<n>` counter. */
+    genId?: () => string;
+    /** Synchronous lifecycle observer (analytics, HUD, replication). */
+    onEvent?: (event: OrderEvent) => void;
+    /** Initial state (e.g. a deserialized snapshot) to load on construction. */
+    initial?: OrderQueueState<TPayload>;
+}
+/**
+ * A per-entity order queue: one commandable unit's lifecycle of intent. The
+ * game ticks it with its world adapter; it activates, advances, completes, and
+ * cancels orders and enforces preemption policy. State is serializable for save
+ * and host-authoritative replication.
+ */
+export interface OrderQueue<TCtx, TPayload = unknown> {
+    /** Queue or preempt an order per its policy; validates the payload through the kind. */
+    issue<T extends TPayload = TPayload>(request: OrderRequest<T>): OrderIssueResult<T>;
+    /** Advance the active order one step (activating the next pending order as needed) and report transitions. */
+    tick(ctx: TCtx, dt: number): OrderTickReport<TPayload>;
+    /** The active order, or `null` when idle. */
+    active(): Order<TPayload> | null;
+    /** The pending orders, in run order (a copy). */
+    pending(): Order<TPayload>[];
+    /** No active order and nothing pending. */
+    isIdle(): boolean;
+    /** Force-cancel the active order (explicit cleanup ignores `uninterruptible`); needs `ctx` to run the kind's `finish`. */
+    cancelActive(ctx: TCtx, reason?: OrderCancelReason): void;
+    /** Cancel the active order and drop every pending order. */
+    cancelAll(ctx: TCtx, reason?: OrderCancelReason): void;
+    /** Hard reset: cancel everything with reason `cleared`. */
+    clear(ctx: TCtx): void;
+    /** Plain-data snapshot for save/replication (deep-cloned; safe to serialize). */
+    serialize(): OrderQueueState<TPayload>;
+    /** Replace queue contents from a (possibly deserialized) snapshot; the active order keeps its `state`. */
+    load(state: OrderQueueState<TPayload>): void;
+}
+/**
+ * Build an empty order-kind registry. Register the built-in compositions from
+ * `orders/orderKinds` or your own verbs, then hand it to `createOrderQueue`.
+ * One registry is shared by many per-entity queues.
+ *
+ * @capability order-registry register order verbs (move/attack/custom) as data so engine code never branches on a verb
+ */
+export declare function createOrderRegistry<TCtx>(): OrderRegistry<TCtx>;
+/**
+ * Create a per-entity order queue over a shared kind registry. The queue owns
+ * the deterministic lifecycle and preemption policy; the kinds own behavior.
+ * Nothing here is random or unbounded: id generation is injected, activation is
+ * bounded by the pending count, and a single `tick` advances at most the active
+ * order plus one activation.
+ *
+ * @capability order-queue serializable per-entity command queue with lifecycle, preemption, and pluggable order kinds
+ */
+export declare function createOrderQueue<TCtx, TPayload = unknown>(registry: OrderRegistry<TCtx>, options?: OrderQueueOptions<TPayload>): OrderQueue<TCtx, TPayload>;

package/dist/orders/orderQueue.js

@@ -0,0 +1,211 @@
+/**
+ * Composable entity orders: a serializable command queue with lifecycle,
+ * preemption, and pluggable order kinds (#912). Player- or AI-issued intent
+ * ("move here", "attack that", "patrol this route") becomes reusable data
+ * instead of a hard-coded RTS verb kit. The queue owns issue -> activate ->
+ * tick -> complete/cancel lifecycle and deterministic preemption policy; each
+ * order KIND owns what "running" means, composed over narrow world adapters.
+ * Engine code never branches on `move`, `attack`, or any game verb -- kinds are
+ * looked up by string in a registry, so a game adds a verb by registering data.
+ */
+/**
+ * Build an empty order-kind registry. Register the built-in compositions from
+ * `orders/orderKinds` or your own verbs, then hand it to `createOrderQueue`.
+ * One registry is shared by many per-entity queues.
+ *
+ * @capability order-registry register order verbs (move/attack/custom) as data so engine code never branches on a verb
+ */
+export function createOrderRegistry() {
+    const kinds = new Map();
+    return {
+        define(kind) {
+            if (kinds.has(kind.kind))
+                throw new Error(`Order kind "${kind.kind}" is already defined.`);
+            kinds.set(kind.kind, kind);
+        },
+        has(kind) {
+            return kinds.has(kind);
+        },
+        get(kind) {
+            return kinds.get(kind) ?? null;
+        },
+        kinds() {
+            return [...kinds.keys()];
+        },
+    };
+}
+function cloneOrder(order) {
+    return structuredClone(order);
+}
+/**
+ * Create a per-entity order queue over a shared kind registry. The queue owns
+ * the deterministic lifecycle and preemption policy; the kinds own behavior.
+ * Nothing here is random or unbounded: id generation is injected, activation is
+ * bounded by the pending count, and a single `tick` advances at most the active
+ * order plus one activation.
+ *
+ * @capability order-queue serializable per-entity command queue with lifecycle, preemption, and pluggable order kinds
+ */
+export function createOrderQueue(registry, options = {}) {
+    const onEvent = options.onEvent;
+    let counter = 0;
+    const genId = options.genId ?? (() => `order-${++counter}`);
+    let active = options.initial ? options.initial.active : null;
+    let pending = options.initial ? [...options.initial.pending] : [];
+    function emit(type, order, reason) {
+        onEvent?.({ type, orderId: order.id, kind: order.kind, reason });
+    }
+    function markCanceled(order, reason) {
+        order.phase = "canceled";
+        order.cancelReason = reason;
+        emit("canceled", order, reason);
+    }
+    function finishActive(ctx, outcome) {
+        if (active === null)
+            return;
+        const kind = registry.get(active.kind);
+        kind?.finish?.(active, ctx, outcome);
+    }
+    /** Pull pending orders forward until one activates or the queue drains. Bounded by the pending length at entry. */
+    function activateNext(ctx, report) {
+        let budget = pending.length;
+        while (active === null && budget > 0) {
+            budget -= 1;
+            const next = pending.shift();
+            if (next === undefined)
+                return;
+            const kind = registry.get(next.kind);
+            if (kind === null) {
+                markCanceled(next, "invalid");
+                report.canceled.push({ id: next.id, reason: "invalid" });
+                continue;
+            }
+            const started = kind.start(next, ctx);
+            if (!started.ok) {
+                markCanceled(next, "invalid");
+                report.canceled.push({ id: next.id, reason: "invalid" });
+                continue;
+            }
+            next.phase = "active";
+            active = next;
+            emit("activated", next);
+            report.activated.push(next.id);
+        }
+    }
+    return {
+        issue(request) {
+            const kind = registry.get(request.kind);
+            if (kind === null)
+                return { status: "rejected", reason: `Unknown order kind "${request.kind}".` };
+            const rejection = kind.validate?.(request.payload) ?? null;
+            if (rejection)
+                return { status: "rejected", reason: rejection.reason };
+            const policy = request.policy ?? "replace";
+            if (policy === "reject" && (active !== null || pending.length > 0)) {
+                return { status: "rejected", reason: "Queue is busy and policy is reject." };
+            }
+            const order = {
+                id: request.id ?? genId(),
+                kind: request.kind,
+                payload: request.payload,
+                phase: "queued",
+                uninterruptible: request.uninterruptible ?? false,
+                ...(request.issuer !== undefined ? { issuer: request.issuer } : {}),
+            };
+            emit("issued", order);
+            if (policy === "replace") {
+                // Preempt the active order unless it is protected; a protected order
+                // finishes first and the newcomer waits at the front of the queue.
+                for (const queued of pending)
+                    markCanceled(queued, "replaced");
+                pending = [];
+                if (active !== null && !active.uninterruptible) {
+                    markCanceled(active, "replaced");
+                    active = null;
+                }
+                pending.push(order);
+                return { status: active !== null ? "queued" : "accepted", order: order };
+            }
+            if (policy === "front") {
+                pending.unshift(order);
+                return { status: active !== null ? "queued" : "accepted", order: order };
+            }
+            // append (and the empty-queue reject case)
+            pending.push(order);
+            return { status: active !== null || pending.length > 1 ? "queued" : "accepted", order: order };
+        },
+        tick(ctx, dt) {
+            const report = { active: null, activated: [], completed: [], canceled: [] };
+            if (active === null)
+                activateNext(ctx, report);
+            if (active !== null) {
+                const kind = registry.get(active.kind);
+                if (kind === null) {
+                    markCanceled(active, "invalid");
+                    report.canceled.push({ id: active.id, reason: "invalid" });
+                    active = null;
+                    activateNext(ctx, report);
+                }
+                else {
+                    const progress = kind.update(active, ctx, dt);
+                    if (progress.status === "completed") {
+                        finishActive(ctx, { phase: "completed" });
+                        active.phase = "completed";
+                        emit("completed", active);
+                        report.completed.push(active.id);
+                        active = null;
+                        activateNext(ctx, report);
+                    }
+                    else if (progress.status === "failed") {
+                        finishActive(ctx, { phase: "canceled", reason: "failed" });
+                        markCanceled(active, "failed");
+                        report.canceled.push({ id: active.id, reason: "failed" });
+                        active = null;
+                        activateNext(ctx, report);
+                    }
+                }
+            }
+            report.active = active;
+            return report;
+        },
+        active() {
+            return active;
+        },
+        pending() {
+            return [...pending];
+        },
+        isIdle() {
+            return active === null && pending.length === 0;
+        },
+        cancelActive(ctx, reason = "requested") {
+            if (active === null)
+                return;
+            finishActive(ctx, { phase: "canceled", reason });
+            markCanceled(active, reason);
+            active = null;
+        },
+        cancelAll(ctx, reason = "requested") {
+            for (const queued of pending)
+                markCanceled(queued, reason);
+            pending = [];
+            if (active !== null) {
+                finishActive(ctx, { phase: "canceled", reason });
+                markCanceled(active, reason);
+                active = null;
+            }
+        },
+        clear(ctx) {
+            this.cancelAll(ctx, "cleared");
+        },
+        serialize() {
+            return {
+                active: active ? cloneOrder(active) : null,
+                pending: pending.map(cloneOrder),
+            };
+        },
+        load(state) {
+            active = state.active ? cloneOrder(state.active) : null;
+            pending = state.pending.map(cloneOrder);
+        },
+    };
+}

package/dist/physics/drivableVehicle.d.ts

@@ -0,0 +1,31 @@
+import type { AxisInput } from "../input/axisInput.js";
+import type { KinematicVehicle, KinematicVehicleModifiers, KinematicVehicleStep } from "./kinematicVehicle.js";
+/** World-space `[x, y, z]` for a drivable vehicle's resolved pose. */
+export type DrivableVehiclePosition = readonly [number, number, number];
+/** Options for {@link tickDrivableVehicle} — ground snapping and per-tick tuning modifiers. */
+export interface DrivableVehicleOptions {
+    /** Resamples world-space Y each tick (terrain height, a ramp, a bridge deck); omit to keep the sim's own flat `y`. */
+    groundHeight?: (x: number, z: number) => number;
+    modifiers?: KinematicVehicleModifiers;
+}
+/** A `setPose`-ready patch — spread straight into `entities.setPose(vehicleId, drive.pose)`. */
+export interface DrivableVehiclePose {
+    position: DrivableVehiclePosition;
+    rotationY: number;
+    rotationX: number;
+    rotationZ: number;
+    dt: number;
+}
+/** {@link tickDrivableVehicle}'s result — the ready-to-apply pose patch plus the raw sim step for HUD/telemetry reads. */
+export interface DrivableVehicleStep {
+    pose: DrivableVehiclePose;
+    step: KinematicVehicleStep;
+}
+/**
+ * Connects an `AxisInput` sample straight through a {@link KinematicVehicle} to a scene entity's pose
+ * for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
+ * game hand-rolled. Ground-snaps the result when `groundHeight` is given (terrain-following cars, not
+ * just flat racetracks). Pair with `scene/vehicleSeat` for who is allowed to drive and where the camera
+ * points; this function only steps the sim and shapes the pose patch, nothing else.
+ */
+export declare function tickDrivableVehicle(vehicle: KinematicVehicle, dt: number, axis: AxisInput, options?: DrivableVehicleOptions): DrivableVehicleStep;

package/dist/physics/drivableVehicle.js

@@ -0,0 +1,16 @@
+/**
+ * Connects an `AxisInput` sample straight through a {@link KinematicVehicle} to a scene entity's pose
+ * for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
+ * game hand-rolled. Ground-snaps the result when `groundHeight` is given (terrain-following cars, not
+ * just flat racetracks). Pair with `scene/vehicleSeat` for who is allowed to drive and where the camera
+ * points; this function only steps the sim and shapes the pose patch, nothing else.
+ */
+export function tickDrivableVehicle(vehicle, dt, axis, options = {}) {
+    const step = vehicle.tick(dt, axis, options.modifiers);
+    const [x, y, z] = step.position;
+    const resolvedY = options.groundHeight === undefined ? y : options.groundHeight(x, z);
+    return {
+        pose: { position: [x, resolvedY, z], rotationX: step.bodyPitch, rotationY: step.heading, rotationZ: step.bodyRoll, dt },
+        step,
+    };
+}