@jgengine/core 0.9.0 → 0.11.0

package/dist/nav/pathFollow.js

@@ -4,6 +4,115 @@ export function pathFromNav(points, elevation = 0, offset = 0) {
     }
     return points.map((point) => [point[0], elevation.sampleHeight(point[0], point[1]) + offset, point[1]]);
 }
+function pathSegments(waypoints, loop) {
+    const count = waypoints.length;
+    const segments = [];
+    const limit = loop ? count : count - 1;
+    for (let i = 0; i < limit; i += 1) {
+        const from = waypoints[i];
+        const dest = (i + 1) % count;
+        const to = waypoints[dest];
+        segments.push({ from, to, len: Math.hypot(to[0] - from[0], to[1] - from[1], to[2] - from[2]), dest });
+    }
+    return segments;
+}
+function distanceForProgress(target, total, segments) {
+    if (target.kind === "distance")
+        return target.value;
+    if (target.kind === "normalized")
+        return target.value * total;
+    let distance = 0;
+    for (let i = 0; i < target.index && i < segments.length; i += 1)
+        distance += segments[i].len;
+    const seg = segments[target.index];
+    if (seg !== undefined)
+        distance += seg.len * target.fraction;
+    return distance;
+}
+/**
+ * Total world-distance of a path — sum of every segment, including the wrap segment back to the
+ * first waypoint when `loop` is set. Zero for a degenerate (0- or 1-waypoint) path.
+ *
+ * @capability path-length total polyline distance for progress math and seeding
+ */
+export function pathLength(config) {
+    return pathSegments(config.waypoints, config.loop ?? false).reduce((sum, seg) => sum + seg.len, 0);
+}
+/**
+ * Place a follower at a semantic {@link PathProgress} without simulating from the start — the seek
+ * adapter behavior lifecycles use to seed distributed phases and restore serialized routes. Pure;
+ * returns a fresh {@link PathFollowState} whose `heading` gives travel direction. Looping paths wrap
+ * the distance; non-looping paths clamp to `[0, pathLength]` and report `done` at the end.
+ *
+ * @capability path-follow-seek jump a path-follower to normalized/distance/segment progress
+ */
+export function pathFollowSeek(config, target) {
+    const { waypoints } = config;
+    const loop = config.loop ?? false;
+    const count = waypoints.length;
+    if (count <= 1)
+        return createPathFollow(config);
+    const segments = pathSegments(waypoints, loop);
+    const total = segments.reduce((sum, seg) => sum + seg.len, 0);
+    if (total <= EPSILON)
+        return createPathFollow(config);
+    const requested = distanceForProgress(target, total, segments);
+    const positioned = loop ? ((requested % total) + total) % total : Math.max(0, Math.min(total, requested));
+    let acc = 0;
+    for (let i = 0; i < segments.length; i += 1) {
+        const seg = segments[i];
+        const last = i === segments.length - 1;
+        if (positioned < acc + seg.len || last) {
+            const along = Math.max(0, Math.min(seg.len, positioned - acc));
+            const t = seg.len > EPSILON ? along / seg.len : 0;
+            const position = [
+                seg.from[0] + (seg.to[0] - seg.from[0]) * t,
+                seg.from[1] + (seg.to[1] - seg.from[1]) * t,
+                seg.from[2] + (seg.to[2] - seg.from[2]) * t,
+            ];
+            const heading = Math.atan2(seg.to[0] - seg.from[0], seg.to[2] - seg.from[2]);
+            const done = !loop && positioned >= total - EPSILON;
+            return {
+                position,
+                target: done ? count - 1 : seg.dest,
+                heading,
+                done,
+                distanceTravelled: loop ? requested : positioned,
+            };
+        }
+        acc += seg.len;
+    }
+    return createPathFollow(config);
+}
+/**
+ * Read a follower's current progress in every semantic form — the inverse of {@link pathFollowSeek},
+ * for editor/debug inspection and progress HUDs. Pure and allocation-light.
+ *
+ * @capability path-follow-progress read normalized/distance/segment progress from follow state
+ */
+export function pathFollowProgress(config, state) {
+    const loop = config.loop ?? false;
+    const segments = pathSegments(config.waypoints, loop);
+    const total = segments.reduce((sum, seg) => sum + seg.len, 0);
+    let segment = segments.findIndex((seg) => seg.dest === state.target);
+    if (segment < 0)
+        segment = 0;
+    const seg = segments[segment];
+    let fraction = 0;
+    if (seg !== undefined && seg.len > EPSILON) {
+        const along = Math.hypot(state.position[0] - seg.from[0], state.position[1] - seg.from[1], state.position[2] - seg.from[2]);
+        fraction = Math.max(0, Math.min(1, along / seg.len));
+    }
+    let traversed = fraction * (seg?.len ?? 0);
+    for (let i = 0; i < segment; i += 1)
+        traversed += segments[i].len;
+    return {
+        distance: state.distanceTravelled,
+        normalized: total > EPSILON ? traversed / total : 0,
+        segment,
+        fraction,
+    };
+}
 export function createPathFollow(config) {
     const first = config.waypoints[0];
     const start = first ?? [0, 0, 0];

package/dist/orders/orderKinds.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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`.
+ */
+import type { OrderKind, OrderVec3 } from "./orderQueue.js";
+/** Result of one movement step, from the game's motion adapter. */
+export interface OrderMoveResult {
+    /** The mover reached the point within its arrive radius this step. */
+    arrived: boolean;
+    /** Remaining distance to the point after the step. */
+    distance: number;
+}
+/**
+ * Narrow motion adapter an order kind drives. The game implements it over its
+ * own controller/motor (`scene.moveToward`, a nav follower, physics) for one
+ * entity; the kind never touches the scene directly.
+ */
+export interface OrderMover {
+    /** Current position, or `null` if the entity is gone (despawned) -- the kind then fails cleanly. */
+    position(): OrderVec3 | null;
+    /** Step toward `point` this tick and report arrival/remaining distance. */
+    moveToward(point: OrderVec3, options?: {
+        speedScale?: number;
+        arriveRadius?: number;
+    }): OrderMoveResult;
+    /** Stop moving (release throttle / clear steering) — used by stop/hold and on cancel. */
+    halt(): void;
+}
+/**
+ * Narrow targeting adapter for engagement verbs. `acquire` returns the id of a
+ * hostile within `radius` (nearest, or whatever policy the game injects), and
+ * `positionOf` locates a known target. Actual damage/effects stay game-side.
+ */
+export interface OrderTargeting {
+    /** Acquire a hostile within `radius`, or `null` if none. */
+    acquire(radius: number): string | null;
+    /** Current position of a target id, or `null` if it is gone. */
+    positionOf(targetId: string): OrderVec3 | null;
+}
+/** Payload for a move order: go to a point and complete on arrival. */
+export interface MoveOrderPayload {
+    point: OrderVec3;
+    /** Distance that counts as arrived; falls back to the factory default. */
+    arriveRadius?: number;
+    /** Per-order speed multiplier passed to the mover. */
+    speedScale?: number;
+}
+/** Payload for stop/hold orders — no data; the verb is the intent. */
+export type EmptyOrderPayload = Record<string, never>;
+/** Payload for an attack-move: advance toward `point`, engaging hostiles encountered en route. */
+export interface AttackMoveOrderPayload {
+    point: OrderVec3;
+    /** Radius scanned for hostiles each tick; falls back to the factory default. */
+    aggroRadius?: number;
+    /** Distance at which an acquired target is "in range" to attack; falls back to the factory default. */
+    attackRange?: number;
+    /** Arrive radius for the destination when no hostile is engaged. */
+    arriveRadius?: number;
+    speedScale?: number;
+}
+/** Live intent an attack-move/targeted order writes into `Order.state`; the game reads it to run the actual attack. Serializable. */
+export interface EngagementOrderState {
+    /** Target currently pursued/engaged, or `null` while travelling. */
+    engaging: string | null;
+    /** The engaged target is within attack range this tick — the swing/cast window. */
+    inRange: boolean;
+}
+/** Payload for a targeted action: pursue one target until in range, holding within a leash. */
+export interface TargetedOrderPayload {
+    targetId: string;
+    /** Distance at which the target is "in range"; falls back to the factory default. */
+    range?: number;
+    speedScale?: number;
+}
+/** Serializable patrol progress. */
+export interface PatrolOrderState {
+    /** Index of the waypoint currently being approached. */
+    index: number;
+}
+/** Payload for a patrol: walk a waypoint route, optionally looping forever. */
+export interface PatrolOrderPayload {
+    waypoints: OrderVec3[];
+    /** Loop back to the first waypoint after the last; otherwise complete at the end. Default `true`. */
+    loop?: boolean;
+    arriveRadius?: number;
+    speedScale?: number;
+}
+/** Shared factory config: override the verb key so a game can register the composition under its own name. */
+export interface OrderKindConfig {
+    /** Registry key / `Order.kind`; defaults to the natural verb name. */
+    kind?: string;
+}
+/** Move + engagement config carrying the default radii the payload may override. */
+export interface EngagementKindConfig extends OrderKindConfig {
+    arriveRadius?: number;
+    aggroRadius?: number;
+    attackRange?: number;
+    range?: number;
+}
+/**
+ * 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 declare function defineMoveOrder<TCtx extends OrderMover>(config?: OrderKindConfig & {
+    arriveRadius?: number;
+}): OrderKind<TCtx, MoveOrderPayload>;
+/**
+ * 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 declare function defineStopOrder<TCtx extends OrderMover>(config?: OrderKindConfig): OrderKind<TCtx, EmptyOrderPayload>;
+/**
+ * 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 declare function defineHoldOrder<TCtx extends OrderMover>(config?: OrderKindConfig): OrderKind<TCtx, EmptyOrderPayload>;
+/**
+ * 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 declare function defineAttackMoveOrder<TCtx extends OrderMover & OrderTargeting>(config?: EngagementKindConfig): OrderKind<TCtx, AttackMoveOrderPayload>;
+/**
+ * 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 declare function defineTargetedOrder<TCtx extends OrderMover & OrderTargeting>(config?: EngagementKindConfig): OrderKind<TCtx, TargetedOrderPayload>;
+/**
+ * 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 declare function definePatrolOrder<TCtx extends OrderMover>(config?: OrderKindConfig & {
+    arriveRadius?: number;
+}): OrderKind<TCtx, PatrolOrderPayload>;

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>;