@jgengine/core 0.9.0 → 0.11.0

package/dist/math/scalar.js

@@ -0,0 +1,47 @@
+export { lerp, clamp01, smoothstep } from "../anim/easing.js";
+/** Constrain a value to the inclusive `[min, max]` range.
+ * @internal
+ */
+export function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}
+/** Fraction of the way `value` sits between `from` and `to`; inverse of `lerp`. Returns 0 when the span is empty.
+ * @internal
+ */
+export function inverseLerp(from, to, value) {
+    return from === to ? 0 : (value - from) / (to - from);
+}
+/** Map `value` from the `[inMin, inMax]` range onto `[outMin, outMax]`, optionally clamped to the output range.
+ * @internal
+ */
+export function remap(value, inMin, inMax, outMin, outMax, clamped = false) {
+    const t = inMin === inMax ? 0 : (value - inMin) / (inMax - inMin);
+    const mapped = outMin + (outMax - outMin) * t;
+    if (!clamped)
+        return mapped;
+    const lo = Math.min(outMin, outMax);
+    const hi = Math.max(outMin, outMax);
+    return mapped < lo ? lo : mapped > hi ? hi : mapped;
+}
+/** Euclidean modulo that always returns a non-negative result in `[0, modulus)`, unlike the `%` operator.
+ * @internal
+ */
+export function mod(value, modulus) {
+    return ((value % modulus) + modulus) % modulus;
+}
+/** Step `current` toward `target` by at most `maxDelta`, without overshooting.
+ * @internal
+ */
+export function moveTowards(current, target, maxDelta) {
+    const diff = target - current;
+    if (Math.abs(diff) <= maxDelta)
+        return target;
+    return current + Math.sign(diff) * maxDelta;
+}
+/** Wrap `value` into the half-open range `[min, max)`, cycling past either edge.
+ * @internal
+ */
+export function wrap(value, min, max) {
+    const span = max - min;
+    return span <= 0 ? min : min + mod(value - min, span);
+}

package/dist/meta/changelog.d.ts

@@ -1,8 +1,11 @@
-export declare const VERSION = "0.9.0";
+/** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
+export declare const VERSION = "0.11.0";
+/** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];
     added: readonly string[];
     changed: readonly string[];
     removed: readonly string[];
 }
+/** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export declare const CHANGELOG: Record<string, ChangelogEntry>;

package/dist/meta/changelog.js

@@ -1,5 +1,40 @@
-export const VERSION = "0.9.0";
+/** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
+export const VERSION = "0.11.0";
+/** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.11.0": {
+        migrate: [
+            "Bump lockstep SDK packages to ^0.11.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine and @jgengine/github may lag on their own version lines.",
+            "Nothing required — classic loop.onTick fan-out still runs after systems. Prefer moving per-frame work into defineGame({ systems: [...] }) with defineSystem (@jgengine/core/game/defineSystem); install a system with feature: \"quest\" (etc.) instead of a redundant features flag.",
+        ],
+        added: [
+            "Composable game systems (#842) — defineSystem / compileSystemSchedule / composeGameLoop / installSystems. defineGame({ systems }) is the single authoring path: fixed / frame / interval / event-only / manual ticks, multi-subscribe channels, deterministic stage order + optional before/after/dependsOn, system-owned save / replicate / reset / dispose. Installing a system activates its feature without a separate flag. GameLoop gains optional onReset / onDispose. ctx.game.registerSave / registerReplicate for system modules. Adopters: tower-guard, claudecraft (runtime without a giant tick fan-out).",
+        ],
+        changed: [],
+        removed: [],
+    },
+    "0.10.0": {
+        migrate: [
+            "Bump lockstep SDK packages to ^0.10.0: @jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}. CLI jgengine and @jgengine/github may lag on their own version lines.",
+            "Nothing to change for existing games — the shared mobile-composition system (viewport allocation, region collision, --jg-* viewport vars) is wired automatically by the shell; HudPanels inside a HudCanvas register themselves. Legacy orientation: \"landscape\" | \"portrait\" keeps its advisory dismissible-hint behavior.",
+            "Opt a driving/landscape game into the strict gate: replace advisory orientation with the contract form orientation: { mobile: \"landscape-required\" } (rules: any · portrait/landscape advisory · portrait-required/landscape-required · unsupported). In portrait the engine shows a polished RotateDeviceScreen, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.",
+            "Declare HUD intent where useful: HudPanel gains priority (critical/secondary/tertiary), mobileBehavior (hidden unmounts on phones, transient softens collision), allowOverlapWith, and collisionGroup — all optional; omitting them keeps prior behavior.",
+            "Mobile validation now also fails on overlap: bun run shoot <game> --device mobile|mobile-landscape|both exits non-zero on forbidden inter-element collisions, naming both regions.",
+        ],
+        added: [
+            "Authored behavior triggers — schema'd `on`/`action` meta vocabulary on editor volumes and markers (`registerTriggerAction`, `collectAuthoredTriggers`, `createAuthoredTriggerRuntime`, `pointInVolume` in `@jgengine/core/scene/authoredTriggers` / `@jgengine/core/world`). Games declare typed actions via ParamSchema; the editor inspector renders trigger fields; runtime watches enter/exit/interact and dispatches to handlers. studio-showcase adopts with an announce zone.",
+            "Shared mobile layout composition — @jgengine/core/ui/gameLayout (resolveLayoutMode, intersects, overlapArea, detectLayoutCollisions, computeGameplayRect, LayoutRegion, GameViewportLayout) and @jgengine/core/ui/orientation (resolveOrientationRequirement, orientationGateActive, MobileOrientationRule); @jgengine/react adds GameViewportProvider (mounted by the shell), hooks (useGameViewportLayout, useGameLayoutMode, useGameOrientation, useReservedControlZones, useLayoutCollisions, useRegisterLayoutRegion), and a headless RotateDeviceScreen. The provider tracks window.visualViewport, publishes --jg-viewport-*/--jg-visual-viewport-*/--jg-safe-* CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps.",
+            "Mandatory orientation contract — PlayableGame.orientation accepts { mobile: <rule> }; landscape-required/portrait-required render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; visualViewport-sized for mobile Safari/PWA.",
+            "Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as control regions, so HUD placement and collision validation know exactly where controls sit.",
+            "HUD placement metadata — HudPanel gains priority, mobileBehavior, allowOverlapWith, collisionGroup, and registers as a collision-tracked layout region.",
+            "Mobile-landscape shoot device — bun run shoot --device mobile-landscape (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.",
+            "Canyon Chase migrated as the reference landscape-required game — declares orientation: { mobile: \"landscape-required\" } and composes its HUD through coordinated HudPanel regions instead of independent fixed corners.",
+        ],
+        changed: [
+            "First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline; hit detection is unchanged (still crosshair-accurate), and non-viewmodel games and enemy tracers are unaffected.",
+        ],
+        removed: [],
+    },
     "0.9.0": {
         migrate: [
             "Bump every @jgengine/* dependency to ^0.9.0 (the eight packages version in lockstep).",

package/dist/movement/avoidance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local collision avoidance: nudge a set of circular agents apart so they stop
+ * overlapping, kept deliberately separate from route planning so a game can
+ * pair it with nav paths, flow fields, direct seek, or vehicle steering. It is a
+ * short symmetric relaxation (Jacobi position correction) over a bounded uniform
+ * hash grid — each agent only tests the 3×3 cells around it, so cost scales with
+ * local density, never O(n²) across the whole world. Corrections are summed per
+ * agent and applied after each pass, so the result is order-independent and
+ * deterministic for a given agent list. Different radii and per-agent weights
+ * (inverse mass; `0` = immovable anchor/obstacle) are honored.
+ */
+import type { Vec2 } from "./formation.js";
+/** A circular agent that avoidance may push on the XZ plane. */
+export interface AvoidanceAgent {
+    /** Current XZ position; reassigned in place by {@link resolveLocalAvoidance}. */
+    position: Vec2;
+    /** Collision radius (world units). */
+    radius: number;
+}
+/** Tuning for {@link resolveLocalAvoidance}. */
+export interface LocalAvoidanceOptions {
+    /** Relaxation passes; more converges denser packs. Default `2`. */
+    iterations?: number;
+    /** Fraction of each overlap resolved per pass, `0..1`. Lower is softer/less jittery. Default `1`. */
+    strength?: number;
+    /** Extra gap enforced beyond the two radii (world units). Default `0`. */
+    padding?: number;
+    /**
+     * Per-agent inverse mass, parallel to the agent list. `0` pins an agent
+     * (obstacle/leader); a heavier agent (smaller value) yields less. Omitted or
+     * negative entries default to `1`. Two pinned agents never push each other.
+     */
+    weights?: readonly number[];
+}
+/**
+ * Resolve overlaps in `agents` in place and return how many overlapping pairs
+ * remained on the final pass (`0` = fully separated). Uses a bounded uniform
+ * hash grid sized to the largest agent, so only nearby agents are ever compared.
+ * Deterministic: corrections are accumulated then applied per pass, independent
+ * of agent order. Pass `weights` to pin or differentially push agents.
+ *
+ * @capability local-avoidance bounded deterministic local collision avoidance for moving agents
+ * @consumer squad/crowd movement — keep grouped agents from overlapping without a whole-world scan
+ */
+export declare function resolveLocalAvoidance(agents: AvoidanceAgent[], options?: LocalAvoidanceOptions): number;

package/dist/movement/avoidance.js

@@ -0,0 +1,123 @@
+/**
+ * Local collision avoidance: nudge a set of circular agents apart so they stop
+ * overlapping, kept deliberately separate from route planning so a game can
+ * pair it with nav paths, flow fields, direct seek, or vehicle steering. It is a
+ * short symmetric relaxation (Jacobi position correction) over a bounded uniform
+ * hash grid — each agent only tests the 3×3 cells around it, so cost scales with
+ * local density, never O(n²) across the whole world. Corrections are summed per
+ * agent and applied after each pass, so the result is order-independent and
+ * deterministic for a given agent list. Different radii and per-agent weights
+ * (inverse mass; `0` = immovable anchor/obstacle) are honored.
+ */
+const CELL_KEY_STRIDE = 0x40000000;
+function cellKey(cx, cz) {
+    return cx * CELL_KEY_STRIDE + cz;
+}
+/**
+ * Resolve overlaps in `agents` in place and return how many overlapping pairs
+ * remained on the final pass (`0` = fully separated). Uses a bounded uniform
+ * hash grid sized to the largest agent, so only nearby agents are ever compared.
+ * Deterministic: corrections are accumulated then applied per pass, independent
+ * of agent order. Pass `weights` to pin or differentially push agents.
+ *
+ * @capability local-avoidance bounded deterministic local collision avoidance for moving agents
+ * @consumer squad/crowd movement — keep grouped agents from overlapping without a whole-world scan
+ */
+export function resolveLocalAvoidance(agents, options = {}) {
+    const count = agents.length;
+    if (count < 2)
+        return 0;
+    const iterations = Math.max(1, Math.floor(options.iterations ?? 2));
+    const strength = options.strength ?? 1;
+    const padding = options.padding ?? 0;
+    const weights = options.weights;
+    let maxRadius = 0;
+    for (let i = 0; i < count; i += 1) {
+        if (agents[i].radius > maxRadius)
+            maxRadius = agents[i].radius;
+    }
+    const cell = Math.max(2 * maxRadius + padding, 1e-6);
+    const invCell = 1 / cell;
+    const corrX = new Float64Array(count);
+    const corrZ = new Float64Array(count);
+    const grid = new Map();
+    let overlaps = 0;
+    for (let pass = 0; pass < iterations; pass += 1) {
+        grid.clear();
+        for (let i = 0; i < count; i += 1) {
+            const p = agents[i].position;
+            const key = cellKey(Math.floor(p[0] * invCell), Math.floor(p[1] * invCell));
+            let bucket = grid.get(key);
+            if (bucket === undefined) {
+                bucket = [];
+                grid.set(key, bucket);
+            }
+            bucket.push(i);
+        }
+        corrX.fill(0);
+        corrZ.fill(0);
+        overlaps = 0;
+        for (let i = 0; i < count; i += 1) {
+            const a = agents[i];
+            const cx = Math.floor(a.position[0] * invCell);
+            const cz = Math.floor(a.position[1] * invCell);
+            const wi = weightOf(weights, i);
+            for (let dz = -1; dz <= 1; dz += 1) {
+                for (let dx = -1; dx <= 1; dx += 1) {
+                    const bucket = grid.get(cellKey(cx + dx, cz + dz));
+                    if (bucket === undefined)
+                        continue;
+                    for (let b = 0; b < bucket.length; b += 1) {
+                        const j = bucket[b];
+                        if (j <= i)
+                            continue;
+                        const wj = weightOf(weights, j);
+                        const totalWeight = wi + wj;
+                        if (totalWeight <= 0)
+                            continue;
+                        const bAgent = agents[j];
+                        const minDist = a.radius + bAgent.radius + padding;
+                        let ndx = bAgent.position[0] - a.position[0];
+                        let ndz = bAgent.position[1] - a.position[1];
+                        let dist = Math.hypot(ndx, ndz);
+                        if (dist >= minDist)
+                            continue;
+                        overlaps += 1;
+                        if (dist < 1e-9) {
+                            // Coincident: separate along a deterministic axis by index order.
+                            ndx = 1;
+                            ndz = 0;
+                            dist = 0;
+                        }
+                        else {
+                            ndx /= dist;
+                            ndz /= dist;
+                        }
+                        const penetration = (minDist - dist) * strength;
+                        const shareA = (wi / totalWeight) * penetration;
+                        const shareB = (wj / totalWeight) * penetration;
+                        corrX[i] -= ndx * shareA;
+                        corrZ[i] -= ndz * shareA;
+                        corrX[j] += ndx * shareB;
+                        corrZ[j] += ndz * shareB;
+                    }
+                }
+            }
+        }
+        for (let i = 0; i < count; i += 1) {
+            const cxi = corrX[i];
+            const czi = corrZ[i];
+            if (cxi === 0 && czi === 0)
+                continue;
+            const p = agents[i].position;
+            agents[i].position = [p[0] + cxi, p[1] + czi];
+        }
+    }
+    return overlaps;
+}
+function weightOf(weights, index) {
+    if (weights === undefined)
+        return 1;
+    const w = weights[index];
+    return w === undefined || w < 0 ? 1 : w;
+}

package/dist/movement/cameraRig.d.ts

@@ -5,11 +5,19 @@
  * apply the results to its own three.js camera/vectors without owning the math.
  */
 export declare const CAMERA_PITCH_LIMIT = 1.45;
+/** @internal */
 export declare function clampCameraPitch(pitch: number): number;
+/** @internal */
 export declare function resolveTargetEyeHeight(crouching: boolean, grounded: boolean): number;
+/** @internal */
 export declare function advanceEyeHeight(currentEyeHeight: number, targetEyeHeight: number, deltaSeconds: number): number;
+/** @internal */
 export declare function resolveHeadBobRate(crouching: boolean, running: boolean): number;
+/** @internal */
 export declare function resolveHeadBobAmplitude(crouching: boolean, running: boolean, grounded: boolean): number;
+/** @internal */
 export declare function advanceHeadBobTime(currentHeadBobTime: number, moving: boolean, grounded: boolean, bobRate: number, deltaSeconds: number): number;
+/** @internal */
 export declare function resolveHeadBobOffset(headBobTime: number, bobAmplitude: number): number;
+/** @internal */
 export declare function resolveCameraTrackingBlend(deltaSeconds: number): number;

package/dist/movement/cameraRig.js

@@ -6,16 +6,20 @@
  */
 import { MOVEMENT_TUNING } from "./movementModel.js";
 export const CAMERA_PITCH_LIMIT = 1.45;
+/** @internal */
 export function clampCameraPitch(pitch) {
     return Math.max(-CAMERA_PITCH_LIMIT, Math.min(CAMERA_PITCH_LIMIT, pitch));
 }
+/** @internal */
 export function resolveTargetEyeHeight(crouching, grounded) {
     return crouching && grounded ? MOVEMENT_TUNING.crouchEyeHeight : MOVEMENT_TUNING.standEyeHeight;
 }
+/** @internal */
 export function advanceEyeHeight(currentEyeHeight, targetEyeHeight, deltaSeconds) {
     const blend = 1 - Math.exp(-MOVEMENT_TUNING.crouchTransitionSpeed * deltaSeconds);
     return currentEyeHeight + (targetEyeHeight - currentEyeHeight) * blend;
 }
+/** @internal */
 export function resolveHeadBobRate(crouching, running) {
     return crouching
         ? MOVEMENT_TUNING.crouchBobRate
@@ -23,6 +27,7 @@ export function resolveHeadBobRate(crouching, running) {
             ? MOVEMENT_TUNING.runBobRate
             : MOVEMENT_TUNING.walkBobRate;
 }
+/** @internal */
 export function resolveHeadBobAmplitude(crouching, running, grounded) {
     if (!grounded)
         return 0;
@@ -32,12 +37,15 @@ export function resolveHeadBobAmplitude(crouching, running, grounded) {
             ? MOVEMENT_TUNING.runBobAmplitude
             : MOVEMENT_TUNING.walkBobAmplitude;
 }
+/** @internal */
 export function advanceHeadBobTime(currentHeadBobTime, moving, grounded, bobRate, deltaSeconds) {
     return moving && grounded ? currentHeadBobTime + deltaSeconds * bobRate : 0;
 }
+/** @internal */
 export function resolveHeadBobOffset(headBobTime, bobAmplitude) {
     return Math.sin(headBobTime * Math.PI * 2) * bobAmplitude;
 }
+/** @internal */
 export function resolveCameraTrackingBlend(deltaSeconds) {
     return 1 - Math.exp(-MOVEMENT_TUNING.cameraTrackingSpeed * deltaSeconds);
 }

package/dist/movement/dash.d.ts

@@ -22,10 +22,20 @@ export interface DashBurst {
     durationMs: number;
     distance: number;
 }
+/** @internal */
 export declare function iframeActive(config: DashConfig, elapsedMs: number): boolean;
+/** @internal */
 export declare function dashEase(t: number): number;
+/**
+ * Compute a dash/dodge burst's displacement over its window, with i-frame timing for dodges.
+ *
+ * @capability dash-move a dash/dodge burst with i-frames and cooldown
+  * @internal
+  */
 export declare function dashDisplacement(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
+/** @internal */
 export declare function dashOffset(config: DashConfig, dir: DashDirection, elapsedMs: number): [number, number, number];
+/** @internal */
 export declare function dashFrameDelta(config: DashConfig, dir: DashDirection, previousElapsedMs: number, elapsedMs: number): [number, number, number];
 export interface DashState {
     tryDash(direction: DashDirection, nowMs: number): DashRejection | DashBurst;
@@ -37,4 +47,5 @@ export interface DashState {
     displacement(nowMs: number): [number, number, number];
     offset(nowMs: number): [number, number, number];
 }
+/** @internal */
 export declare function createDashState(config: DashConfig): DashState;

package/dist/movement/dash.js

@@ -1,10 +1,18 @@
+/** @internal */
 export function iframeActive(config, elapsedMs) {
     return elapsedMs >= config.iframes.fromMs && elapsedMs < config.iframes.toMs;
 }
+/** @internal */
 export function dashEase(t) {
     const clamped = Math.max(0, Math.min(1, t));
     return 1 - (1 - clamped) * (1 - clamped);
 }
+/**
+ * Compute a dash/dodge burst's displacement over its window, with i-frame timing for dodges.
+ *
+ * @capability dash-move a dash/dodge burst with i-frames and cooldown
+  * @internal
+  */
 export function dashDisplacement(config, dir, elapsedMs) {
     const traveled = dashEase(elapsedMs / config.durationMs) * config.distance;
     const len = Math.hypot(dir.x, dir.z);
@@ -12,14 +20,17 @@ export function dashDisplacement(config, dir, elapsedMs) {
         return [0, 0, 0];
     return [(dir.x / len) * traveled, 0, (dir.z / len) * traveled];
 }
+/** @internal */
 export function dashOffset(config, dir, elapsedMs) {
     return dashDisplacement(config, dir, elapsedMs);
 }
+/** @internal */
 export function dashFrameDelta(config, dir, previousElapsedMs, elapsedMs) {
     const previous = dashDisplacement(config, dir, previousElapsedMs);
     const current = dashDisplacement(config, dir, elapsedMs);
     return [current[0] - previous[0], current[1] - previous[1], current[2] - previous[2]];
 }
+/** @internal */
 export function createDashState(config) {
     let stamina = config.staminaMax;
     let dashStartMs = null;

package/dist/movement/formation.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Group destination assignment: slot a moving group into a formation around a
+ * target point, then match members to slots. Shape is caller data — a
+ * {@link FormationSlotGenerator} emits slot offsets in the group's local frame
+ * ("right" = +x, "forward" = +y) and the engine ships line/box/wedge/circle
+ * only as samples; a custom generator needs no engine change. Placement and
+ * matching are pure and deterministic so the same inputs always yield the same
+ * world slots and the same assignment, which keeps them replay- and
+ * network-safe. Route planning and local collision avoidance are deliberately
+ * separate seams (`movement/avoidance`, `nav/pathFollow`): this module answers
+ * only "where should each member stand", not "how does it get there".
+ */
+/** A point or offset on the XZ ground plane: `[x, z]`. */
+export type Vec2 = readonly [number, number];
+/**
+ * Produces `count` slot offsets in the group's local frame — `[right, forward]`
+ * where `+forward` points where the group faces. Index order is the slot order;
+ * a generator must be pure (same `count` → same offsets) so placement stays
+ * deterministic. Sample generators below cover common shapes; games pass their
+ * own for anything else (crowds, convoys, sports positions) with no engine edit.
+ */
+export type FormationSlotGenerator = (count: number) => Vec2[];
+/**
+ * Engine yaw (`rotationY`, radians) that faces from `from` toward `to` on the
+ * XZ plane, matching the `forward = (sin yaw, cos yaw)` convention. Feed the
+ * result as the `facing` of {@link placeFormation} to orient a formation along
+ * its travel direction. Returns `0` when the points coincide.
+ *
+ * @capability formation-facing group facing yaw from a travel direction on the XZ plane
+ * @consumer squad and crowd movement — orient a destination formation along its heading
+ */
+export declare function facingYaw(from: Vec2, to: Vec2): number;
+/**
+ * Transform a generator's local slot offsets into world XZ positions around a
+ * `destination`, rotated by `facing` (engine yaw). Slot `i` in the returned
+ * array is `generator(count)[i]` mapped through the group frame, so it stays
+ * aligned with {@link assignFormationSlots}' slot indices. Pure and allocation-
+ * light: one array of `count` points, no per-call closures retained.
+ *
+ * @capability formation-placement place a group formation's world slots around a destination
+ * @consumer squad/party/convoy movement — generate per-member destination slots around a target
+ */
+export declare function placeFormation(destination: Vec2, facing: number, count: number, generator: FormationSlotGenerator): Vec2[];
+/** Tuning for {@link assignFormationSlots}' stable, low-churn matching. */
+export interface SlotAssignmentOptions {
+    /**
+     * Last tick's result (`previous[member] = slot`). When supplied, a member is
+     * biased toward keeping its previous slot so the formation does not reshuffle
+     * every frame. Entries out of range for the current slot count are ignored.
+     */
+    previous?: readonly number[];
+    /**
+     * Squared-distance bonus (world units²) for keeping the previous slot; higher
+     * values reduce churn at the cost of tighter travel. Default `0` (pure
+     * nearest matching). Ignored without `previous`.
+     */
+    stickiness?: number;
+}
+/**
+ * Match `members` to `slots` by a deterministic greedy nearest assignment:
+ * every (member, slot) pair is ranked by squared travel distance (minus a
+ * stickiness bonus for a member's previous slot) and assigned in order while
+ * both ends are free. Returns `assignment[member] = slot`, or `-1` for members
+ * left unmatched when there are fewer slots than members. Ties break by member
+ * then slot index, so the result is stable across runs and independent of input
+ * ordering — the property replay and lockstep multiplayer rely on. Groups are
+ * bounded, so the `O(members·slots·log)` sort is fine; this is not a per-frame
+ * whole-world pass.
+ *
+ * @capability formation-assignment stable deterministic member-to-slot matching for a group formation
+ * @consumer squad/party movement — assign each member a destination slot with low reshuffle churn
+ */
+export declare function assignFormationSlots(members: readonly Vec2[], slots: readonly Vec2[], options?: SlotAssignmentOptions): number[];
+/** Options for {@link lineFormation}. */
+export interface LineFormationOptions {
+    /** Gap between adjacent members (world units). */
+    spacing: number;
+}
+/**
+ * A single rank abreast, centered on the destination and facing forward — a
+ * skirmish line or a chorus row. Slots run left→right along the group's right
+ * axis.
+ *
+ * @capability formation-line line (abreast) slot generator for group destinations
+ * @consumer squad movement — line formation sample policy for {@link placeFormation}
+ */
+export declare function lineFormation(options: LineFormationOptions): FormationSlotGenerator;
+/** Options for {@link boxFormation}. */
+export interface BoxFormationOptions {
+    /** Gap between adjacent members along both axes (world units). */
+    spacing: number;
+    /** Members per row; defaults to a near-square `ceil(sqrt(count))`. */
+    columns?: number;
+}
+/**
+ * A rectangular grid centered on the destination, front row toward `+forward` —
+ * a marching block or a phalanx. Rows fill front-to-back, left-to-right.
+ *
+ * @capability formation-box box/grid slot generator for group destinations
+ * @consumer squad movement — box formation sample policy for {@link placeFormation}
+ */
+export declare function boxFormation(options: BoxFormationOptions): FormationSlotGenerator;
+/** Options for {@link wedgeFormation}. */
+export interface WedgeFormationOptions {
+    /** Gap between successive ranks along each arm (world units). */
+    spacing: number;
+}
+/**
+ * A "V"/arrowhead with the apex at the destination and arms trailing back — a
+ * flying-wedge charge or a goose skein. Slot 0 is the tip; later slots alternate
+ * right then left, each rank stepping one `spacing` outward and backward.
+ *
+ * @capability formation-wedge wedge/arrowhead slot generator for group destinations
+ * @consumer squad movement — wedge formation sample policy for {@link placeFormation}
+ */
+export declare function wedgeFormation(options: WedgeFormationOptions): FormationSlotGenerator;
+/** Options for {@link circleFormation}. */
+export interface CircleFormationOptions {
+    /** Ring radius from the destination center (world units). */
+    radius: number;
+    /**
+     * Start angle offset (radians) around the ring; default `0` places slot 0
+     * directly forward. Angles advance counterclockwise.
+     */
+    startAngle?: number;
+}
+/**
+ * An evenly spaced ring around the destination — a guard cordon, a huddle, or a
+ * surround. Slot 0 sits `startAngle` from forward; slots advance evenly around
+ * the circle.
+ *
+ * @capability formation-circle ring/cordon slot generator for group destinations
+ * @consumer squad/crowd movement — circle formation sample policy for {@link placeFormation}
+ */
+export declare function circleFormation(options: CircleFormationOptions): FormationSlotGenerator;