@jgengine/core 0.10.0 → 0.12.0

package/dist/movement/steering.js

@@ -37,4 +37,22 @@ export function steerToward(yaw, desiredYaw) {
         delta += TWO_PI;
     return -delta;
 }
+/**
+ * @internal Rotate `yaw` toward `targetYaw` by at most `turnRatePerSecond * dt`
+ * radians, always along the shortest arc, snapping exactly onto the target once
+ * within a single step so it converges without overshoot or jitter — the
+ * smoothing behind a rendered body-turn (`PlayerMovementConfig.turnSpeed`). A
+ * large enough rate (or `dt`) reaches the target in one call, matching a snap.
+ */
+export function approachYaw(yaw, targetYaw, turnRatePerSecond, dt) {
+    let delta = (targetYaw - yaw) % TWO_PI;
+    if (delta > Math.PI)
+        delta -= TWO_PI;
+    if (delta <= -Math.PI)
+        delta += TWO_PI;
+    const maxStep = turnRatePerSecond * dt;
+    if (maxStep <= 0 || Math.abs(delta) <= maxStep)
+        return targetYaw;
+    return yaw + Math.sign(delta) * maxStep;
+}
 const TWO_PI = Math.PI * 2;

package/dist/multiplayer/combatSnapshot.d.ts

@@ -16,7 +16,9 @@ export interface SerializeBoardArgs {
     seed?: number;
     capturedAt?: number;
 }
+/** @internal */
 export declare function serializeBoard(args: SerializeBoardArgs): BoardSnapshot;
+/** @internal */
 export declare function cloneSnapshot(snapshot: BoardSnapshot): BoardSnapshot;
 export interface CombatRules {
     attackStat: string;
@@ -42,4 +44,5 @@ export interface ReplayResult {
     survivorsA: readonly string[];
     survivorsB: readonly string[];
 }
+/** @internal */
 export declare function replayCombat(a: BoardSnapshot, b: BoardSnapshot, rules: CombatRules): ReplayResult;

package/dist/multiplayer/combatSnapshot.js

@@ -1,6 +1,8 @@
+import { randomSeedFrom, stepRandomSeed } from "../random/rng.js";
 function cloneStats(stats) {
     return { ...stats };
 }
+/** @internal */
 export function serializeBoard(args) {
     return {
         ownerId: args.ownerId,
@@ -10,6 +12,7 @@ export function serializeBoard(args) {
         capturedAt: args.capturedAt ?? 0,
     };
 }
+/** @internal */
 export function cloneSnapshot(snapshot) {
     return serializeBoard({
         ownerId: snapshot.ownerId,
@@ -19,14 +22,18 @@ export function cloneSnapshot(snapshot) {
         capturedAt: snapshot.capturedAt,
     });
 }
-function mulberry32(seed) {
-    let a = seed >>> 0;
+/**
+ * Deterministic per-replay PRNG built from the shared {@link randomSeedFrom} /
+ * {@link stepRandomSeed} primitives. `randomSeedFrom` takes the raw integer seed
+ * without string hashing, so the emitted sequence is byte-identical to the former
+ * inline mulberry32 — replay determinism across peers is preserved.
+ */
+function seededPrng(seed) {
+    let cursor = randomSeedFrom(seed);
     return () => {
-        a |= 0;
-        a = (a + 0x6d2b79f5) | 0;
-        let t = Math.imul(a ^ (a >>> 15), 1 | a);
-        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        const [value, next] = stepRandomSeed(cursor);
+        cursor = next;
+        return value;
     };
 }
 function toLive(snapshot, rules) {
@@ -36,11 +43,12 @@ function toLive(snapshot, rules) {
         health: unit.stats[rules.healthStat] ?? 0,
     }));
 }
+/** @internal */
 export function replayCombat(a, b, rules) {
     const maxRounds = rules.maxRounds ?? 100;
     const critChance = rules.critChance ?? 0;
     const critMultiplier = rules.critMultiplier ?? 2;
-    const prng = mulberry32((a.seed ^ (b.seed * 0x9e3779b1)) >>> 0);
+    const prng = seededPrng((a.seed ^ (b.seed * 0x9e3779b1)) >>> 0);
     const liveA = toLive(a, rules);
     const liveB = toLive(b, rules);
     const blows = [];

package/dist/multiplayer/lagCompensation.d.ts

@@ -10,6 +10,7 @@ export interface PositionHistoryConfig {
     historyMs: number;
     maxSamples?: number;
 }
+/** @internal */
 export declare class PositionHistory {
     private readonly historyMs;
     private readonly maxSamples;
@@ -23,7 +24,9 @@ export declare class PositionHistory {
     prune(now: number): void;
     forget(entityId: string): void;
 }
+/** @internal */
 export declare function createPositionHistory(config: PositionHistoryConfig): PositionHistory;
+/** @internal */
 export declare function rewindTimestamp(nowMs: number, rttMs: number, interpDelayMs: number): number;
 export interface HitscanRay {
     origin: Vec3;
@@ -39,5 +42,7 @@ export interface HitscanHit {
     distance: number;
     point: Vec3;
 }
+/** @internal */
 export declare function raySphereDistance(ray: HitscanRay, center: Vec3, radius: number): number | null;
+/** @internal */
 export declare function resolveHitscan(history: PositionHistory, targets: readonly HitscanTarget[], ray: HitscanRay, atMs: number): HitscanHit | null;

package/dist/multiplayer/lagCompensation.js

@@ -1,4 +1,5 @@
 const DEFAULT_MAX_SAMPLES = 256;
+/** @internal */
 export class PositionHistory {
     historyMs;
     maxSamples;
@@ -90,9 +91,11 @@ export class PositionHistory {
         this.tracks.delete(entityId);
     }
 }
+/** @internal */
 export function createPositionHistory(config) {
     return new PositionHistory(config);
 }
+/** @internal */
 export function rewindTimestamp(nowMs, rttMs, interpDelayMs) {
     return nowMs - rttMs / 2 - interpDelayMs;
 }
@@ -102,6 +105,7 @@ function normalize(v) {
         return null;
     return { x: v.x / len, y: v.y / len, z: v.z / len };
 }
+/** @internal */
 export function raySphereDistance(ray, center, radius) {
     const dir = normalize(ray.direction);
     if (dir === null)
@@ -126,6 +130,7 @@ export function raySphereDistance(ray, center, radius) {
         return null;
     return t;
 }
+/** @internal */
 export function resolveHitscan(history, targets, ray, atMs) {
     const dir = normalize(ray.direction);
     if (dir === null)

package/dist/multiplayer/presenceModel.d.ts

@@ -32,6 +32,8 @@ export interface PoseSyncRules {
     /** Unchanged poses refresh the keep-alive stamp at most this often. */
     keepAliveRefreshMs: number;
 }
+/** Canonical client-authoritative pose-sync tuning shared by every host transport (WS, Convex). */
+export declare const DEFAULT_POSE_SYNC_RULES: PoseSyncRules;
 export interface PoseSyncDecision {
     position: {
         x: number;
@@ -51,25 +53,33 @@ export declare const DEFAULT_SPAWN_ORIGIN: {
     readonly y: 0;
     readonly z: 0;
 };
+/** @internal */
 export declare function spawnPresenceState(origin: {
     x: number;
     y: number;
     z: number;
 } | undefined, nowMs: number, rules: Pick<PoseSyncRules, "maxElapsedSec">): PresencePoseState;
+/** @internal */
 export declare function decidePoseSync(current: PresencePoseState, incoming: IncomingPose, rules: PoseSyncRules, nowMs: number, floorY?: number): PoseSyncDecision;
+/** @internal */
 export declare function shouldRefreshKeepAlive(lastSeenAtMs: number | undefined, nowMs: number, rules: Pick<PoseSyncRules, "keepAliveRefreshMs">): boolean;
+/** @internal */
 export declare function shouldPersistWorldSnapshot(lastSavedAtMs: number | undefined, nowMs: number, intervalMs: number): boolean;
 export interface ActivePresenceResolution<T> {
     active: T | null;
     /** Other unrevoked rows for the same actor — a session may only have one. */
     extras: T[];
 }
+/** @internal */
 export declare function resolveActivePresence<T extends {
     revokedAt?: number;
     lastSeenAt?: number;
 }>(rows: readonly T[]): ActivePresenceResolution<T>;
+/** @internal */
 export declare function isPresenceExpired(lastSeenAtMs: number, nowMs: number, idleCutoffMs: number): boolean;
-/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one. */
+/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one.
+ * @internal
+ */
 export declare function pickReusablePresence<T extends {
     lastSeenAt?: number;
 }>(rows: readonly T[]): T | undefined;

package/dist/multiplayer/presenceModel.js

@@ -1,3 +1,11 @@
+/** Canonical client-authoritative pose-sync tuning shared by every host transport (WS, Convex). */
+export const DEFAULT_POSE_SYNC_RULES = {
+    maxSpeed: 12,
+    maxVerticalOffset: 3,
+    minElapsedSec: 0.05,
+    maxElapsedSec: 0.5,
+    keepAliveRefreshMs: 10_000,
+};
 function appearanceEqual(a, b) {
     if (a === b)
         return true;
@@ -10,6 +18,7 @@ function appearanceEqual(a, b) {
     return aKeys.every((key) => a[key] === b[key]);
 }
 export const DEFAULT_SPAWN_ORIGIN = { x: 0, y: 0, z: 0 };
+/** @internal */
 export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules) {
     return {
         position: { x: origin.x, y: origin.y, z: origin.z },
@@ -18,6 +27,7 @@ export function spawnPresenceState(origin = DEFAULT_SPAWN_ORIGIN, nowMs, rules)
         lastSeenAtMs: nowMs - rules.maxElapsedSec * 1000,
     };
 }
+/** @internal */
 export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
     const rawElapsedSec = Math.max(0, (nowMs - (current.lastSeenAtMs ?? nowMs)) / 1000);
     const elapsedSec = Math.min(rules.maxElapsedSec, rawElapsedSec);
@@ -55,12 +65,15 @@ export function decidePoseSync(current, incoming, rules, nowMs, floorY) {
         refreshKeepAlive: !changed && shouldRefreshKeepAlive(current.lastSeenAtMs, nowMs, rules),
     };
 }
+/** @internal */
 export function shouldRefreshKeepAlive(lastSeenAtMs, nowMs, rules) {
     return nowMs - (lastSeenAtMs ?? 0) >= rules.keepAliveRefreshMs;
 }
+/** @internal */
 export function shouldPersistWorldSnapshot(lastSavedAtMs, nowMs, intervalMs) {
     return lastSavedAtMs === undefined || nowMs - lastSavedAtMs >= intervalMs;
 }
+/** @internal */
 export function resolveActivePresence(rows) {
     const actives = rows.filter((row) => row.revokedAt === undefined);
     if (actives.length === 0)
@@ -68,10 +81,13 @@ export function resolveActivePresence(rows) {
     const sorted = [...actives].sort((a, b) => (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0));
     return { active: sorted[0] ?? null, extras: sorted.slice(1) };
 }
+/** @internal */
 export function isPresenceExpired(lastSeenAtMs, nowMs, idleCutoffMs) {
     return nowMs - lastSeenAtMs >= idleCutoffMs;
 }
-/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one. */
+/** Most-recently-seen row across an actor's rows, to reuse instead of inserting a new one.
+ * @internal
+ */
 export function pickReusablePresence(rows) {
     return [...rows].sort((a, b) => (b.lastSeenAt ?? 0) - (a.lastSeenAt ?? 0))[0];
 }

package/dist/multiplayer/simultaneousCommit.d.ts

@@ -15,6 +15,7 @@ export type SealResult = {
     ok: false;
     reason: "unknown_participant" | "already_sealed" | "already_revealed";
 };
+/** @internal */
 export declare class CommitRound<TAction> {
     private readonly order;
     private readonly participants;
@@ -30,5 +31,7 @@ export declare class CommitRound<TAction> {
     get phase(): CommitPhase;
     reveal(): readonly SealedCommit<TAction>[] | null;
 }
+/** @internal */
 export declare function createCommitRound<TAction>(config: CommitRoundConfig): CommitRound<TAction>;
+/** @internal */
 export declare function resolveCommits<TAction, TResult>(reveals: readonly SealedCommit<TAction>[], resolver: (ordered: readonly SealedCommit<TAction>[]) => TResult): TResult;

package/dist/multiplayer/simultaneousCommit.js

@@ -1,3 +1,4 @@
+/** @internal */
 export class CommitRound {
     order;
     participants;
@@ -45,9 +46,11 @@ export class CommitRound {
         return this.order.map((id) => this.sealed.get(id));
     }
 }
+/** @internal */
 export function createCommitRound(config) {
     return new CommitRound(config);
 }
+/** @internal */
 export function resolveCommits(reveals, resolver) {
     return resolver(reveals);
 }

package/dist/multiplayer.d.ts

@@ -0,0 +1,11 @@
+export { type ChatActions, type ChatSendOutcome, type ChatSync, type ChatTransport, } from "./multiplayer/chatContract.js";
+export { type BoardSnapshot } from "./multiplayer/combatSnapshot.js";
+export { createFeedWriteGate, validateFeedWrite, type FeedWriteGate } from "./multiplayer/feedWriteGate.js";
+export { resolveGuestSession, sessionPlayer, type AuthSession, type PlayerIdentity } from "./multiplayer/identity.js";
+export { type Vec3 } from "./multiplayer/lagCompensation.js";
+export { browseSessions, findByJoinCode, normalizeJoinCode, quickMatch, type MatchFilter, type SessionListing, type SessionVisibility, } from "./multiplayer/matchmaking.js";
+export { createPoseSyncGate, type PlayerPose, type PoseSyncTuning } from "./multiplayer/poseSyncGate.js";
+export { type EnsurePresenceResult, type PresenceActions, type PresenceFeeds, type PresenceSession, type PresenceTransport, } from "./multiplayer/presenceContract.js";
+export { type PoseSyncRules, type PresencePoseState } from "./multiplayer/presenceModel.js";
+export { createLocalVoiceTransport, createPushToTalk, type PushToTalkMode, type PushToTalkStatus, type VoiceParticipant, type VoiceRoute, type VoiceTransport, } from "./multiplayer/voiceContract.js";
+export { type ReplicationPolicy } from "./runtime/worldProjection.js";

package/dist/multiplayer.js

@@ -0,0 +1,11 @@
+export {} from "./multiplayer/chatContract.js";
+export {} from "./multiplayer/combatSnapshot.js";
+export { createFeedWriteGate, validateFeedWrite } from "./multiplayer/feedWriteGate.js";
+export { resolveGuestSession, sessionPlayer } from "./multiplayer/identity.js";
+export {} from "./multiplayer/lagCompensation.js";
+export { browseSessions, findByJoinCode, normalizeJoinCode, quickMatch, } from "./multiplayer/matchmaking.js";
+export { createPoseSyncGate } from "./multiplayer/poseSyncGate.js";
+export {} from "./multiplayer/presenceContract.js";
+export {} from "./multiplayer/presenceModel.js";
+export { createLocalVoiceTransport, createPushToTalk, } from "./multiplayer/voiceContract.js";
+export {} from "./runtime/worldProjection.js";

package/dist/nav/pathFollow.d.ts

@@ -21,6 +21,63 @@ export interface HeightSampler {
     sampleHeight(x: number, z: number): number;
 }
 export declare function pathFromNav(points: readonly NavPoint[], elevation?: number | HeightSampler, offset?: number): Waypoint[];
+/**
+ * Semantic seek target for {@link pathFollowSeek} — the caller-facing progress vocabulary a
+ * stateful path behavior restores from, so a follower can start at a distributed phase or resume
+ * a serialized route without knowing waypoint internals. `direction` (forward heading) falls out of
+ * the resulting {@link PathFollowState.heading}, so it is an output rather than a seek input.
+ */
+export type PathProgress = 
+/** Fraction `0..1` of total path length (looping paths wrap; clamped otherwise). */
+{
+    readonly kind: "normalized";
+    readonly value: number;
+}
+/** World-distance travelled from the first waypoint (looping paths wrap; clamped otherwise). */
+ | {
+    readonly kind: "distance";
+    readonly value: number;
+}
+/** Segment `index` (0-based) plus `fraction` `0..1` along that segment. */
+ | {
+    readonly kind: "segment";
+    readonly index: number;
+    readonly fraction: number;
+};
+/** Read-only progress readout for inspection/debug tooling, produced by {@link pathFollowProgress}. */
+export interface PathFollowProgress {
+    /** Cumulative world-distance travelled (matches {@link PathFollowState.distanceTravelled}). */
+    distance: number;
+    /** Fraction `0..1` of total path length at the current position. */
+    normalized: number;
+    /** 0-based index of the segment the mover is currently on. */
+    segment: number;
+    /** Fraction `0..1` along the current segment. */
+    fraction: number;
+}
+/**
+ * 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 declare function pathLength(config: PathFollowConfig): number;
+/**
+ * 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 declare function pathFollowSeek(config: PathFollowConfig, target: PathProgress): PathFollowState;
+/**
+ * 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 declare function pathFollowProgress(config: PathFollowConfig, state: PathFollowState): PathFollowProgress;
 export declare function createPathFollow(config: PathFollowConfig): PathFollowState;
 /**
  * Advance a path-follower by `speed * dt` along its authored polyline. Pure — returns

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