@jgengine/core 0.10.0 → 0.12.0

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;

package/dist/movement/formation.js

@@ -0,0 +1,194 @@
+/**
+ * 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".
+ */
+import { yawForward, yawRight } from "./steering.js";
+/**
+ * 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 function facingYaw(from, to) {
+    const dx = to[0] - from[0];
+    const dz = to[1] - from[1];
+    if (dx * dx + dz * dz <= 1e-18)
+        return 0;
+    return Math.atan2(dx, dz);
+}
+/**
+ * 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 function placeFormation(destination, facing, count, generator) {
+    if (count <= 0)
+        return [];
+    const forward = yawForward(facing);
+    const right = yawRight(facing);
+    const local = generator(count);
+    const slots = [];
+    for (let i = 0; i < count; i += 1) {
+        const offset = local[i] ?? ZERO;
+        const r = offset[0];
+        const f = offset[1];
+        slots.push([
+            destination[0] + right[0] * r + forward[0] * f,
+            destination[1] + right[1] * r + forward[1] * f,
+        ]);
+    }
+    return slots;
+}
+/**
+ * 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 function assignFormationSlots(members, slots, options = {}) {
+    const memberCount = members.length;
+    const slotCount = slots.length;
+    const assignment = new Array(memberCount).fill(-1);
+    if (memberCount === 0 || slotCount === 0)
+        return assignment;
+    const previous = options.previous;
+    const stickiness = options.stickiness ?? 0;
+    const pairs = [];
+    for (let m = 0; m < memberCount; m += 1) {
+        const member = members[m];
+        const keepSlot = previous?.[m];
+        for (let s = 0; s < slotCount; s += 1) {
+            const slot = slots[s];
+            const dx = slot[0] - member[0];
+            const dz = slot[1] - member[1];
+            let cost = dx * dx + dz * dz;
+            if (stickiness > 0 && keepSlot === s)
+                cost -= stickiness;
+            pairs.push({ member: m, slot: s, cost });
+        }
+    }
+    pairs.sort((a, b) => a.cost !== b.cost ? a.cost - b.cost : a.member !== b.member ? a.member - b.member : a.slot - b.slot);
+    const slotTaken = new Array(slotCount).fill(false);
+    let filled = 0;
+    const need = Math.min(memberCount, slotCount);
+    for (let p = 0; p < pairs.length && filled < need; p += 1) {
+        const pair = pairs[p];
+        if (assignment[pair.member] !== -1 || slotTaken[pair.slot])
+            continue;
+        assignment[pair.member] = pair.slot;
+        slotTaken[pair.slot] = true;
+        filled += 1;
+    }
+    return assignment;
+}
+const ZERO = [0, 0];
+/**
+ * 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 function lineFormation(options) {
+    const spacing = options.spacing;
+    return (count) => {
+        const slots = [];
+        const mid = (count - 1) / 2;
+        for (let i = 0; i < count; i += 1)
+            slots.push([(i - mid) * spacing, 0]);
+        return slots;
+    };
+}
+/**
+ * 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 function boxFormation(options) {
+    const spacing = options.spacing;
+    const fixedColumns = options.columns;
+    return (count) => {
+        const columns = Math.max(1, fixedColumns ?? Math.ceil(Math.sqrt(count)));
+        const rows = Math.ceil(count / columns);
+        const midCol = (columns - 1) / 2;
+        const midRow = (rows - 1) / 2;
+        const slots = [];
+        for (let i = 0; i < count; i += 1) {
+            const row = Math.floor(i / columns);
+            const col = i % columns;
+            slots.push([(col - midCol) * spacing, (midRow - row) * spacing]);
+        }
+        return slots;
+    };
+}
+/**
+ * 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 function wedgeFormation(options) {
+    const spacing = options.spacing;
+    return (count) => {
+        const slots = [];
+        for (let i = 0; i < count; i += 1) {
+            if (i === 0) {
+                slots.push([0, 0]);
+                continue;
+            }
+            const rank = Math.ceil(i / 2);
+            const side = i % 2 === 1 ? 1 : -1;
+            slots.push([side * rank * spacing, -rank * spacing]);
+        }
+        return slots;
+    };
+}
+/**
+ * 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 function circleFormation(options) {
+    const radius = options.radius;
+    const startAngle = options.startAngle ?? 0;
+    return (count) => {
+        const slots = [];
+        for (let i = 0; i < count; i += 1) {
+            const angle = startAngle + (2 * Math.PI * i) / count;
+            slots.push([radius * Math.sin(angle), radius * Math.cos(angle)]);
+        }
+        return slots;
+    };
+}

package/dist/movement/glideModel.d.ts

@@ -41,4 +41,9 @@ export interface GlideModel {
     pose(): GlideStep;
     launch(position: GlideVec3, heading: number, initialSpeed?: number): void;
 }
+/**
+ * Gliding/wingsuit descent control — lift, drag, and steering from a launch.
+ *
+ * @capability glide gliding/wingsuit descent control from a launch
+ */
 export declare function createGlideModel(config?: GlideModelConfig): GlideModel;

package/dist/movement/glideModel.js

@@ -1,3 +1,8 @@
+/**
+ * Gliding/wingsuit descent control — lift, drag, and steering from a launch.
+ *
+ * @capability glide gliding/wingsuit descent control from a launch
+ */
 export function createGlideModel(config = {}) {
     const gravity = (config.gravity ?? 20) * (config.gravityScale ?? 0.25);
     const thrustAccel = config.thrustAccel ?? 10;

package/dist/movement/grappleSwing.d.ts

@@ -31,4 +31,9 @@ export interface GrappleSwing {
     /** Constrain one frame. `reeling` shortens the rope; returns the corrected position/velocity. */
     step(position: SwingVec3, velocity: SwingVec3, dt: number, reeling?: boolean): GrappleSwingStep;
 }
+/**
+ * Grappling-hook rope swing physics with anchor, pendulum motion, and reel-in.
+ *
+ * @capability grapple-swing grappling-hook rope swing physics with reel-in
+ */
 export declare function createGrappleSwing(config?: GrappleSwingConfig): GrappleSwing;

package/dist/movement/grappleSwing.js

@@ -1,3 +1,8 @@
+/**
+ * Grappling-hook rope swing physics with anchor, pendulum motion, and reel-in.
+ *
+ * @capability grapple-swing grappling-hook rope swing physics with reel-in
+ */
 export function createGrappleSwing(config = {}) {
     const reelSpeed = config.reelSpeed ?? 0;
     const minLength = config.minLength ?? 1;

package/dist/movement/leaderTrail.d.ts

@@ -26,4 +26,9 @@ export interface LeaderTrail {
     /** Drop all history (teleport, respawn) and optionally restart from a position. */
     reset(position?: TrailPoint): void;
 }
+/**
+ * A trailing follower formation that chases a leader along its past path — snake/convoy trails.
+ *
+ * @capability follow-trail trailing follower/snake formation that chases a leader
+ */
 export declare function createLeaderTrail(config: LeaderTrailConfig): LeaderTrail;

package/dist/movement/leaderTrail.js

@@ -1,3 +1,8 @@
+/**
+ * A trailing follower formation that chases a leader along its past path — snake/convoy trails.
+ *
+ * @capability follow-trail trailing follower/snake formation that chases a leader
+ */
 export function createLeaderTrail(config) {
     if (!(config.spacing > 0))
         throw new Error(`leader trail spacing must be positive, got ${config.spacing}`);