@jgengine/core 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -11,6 +11,69 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## Unreleased
+
+## 0.9.0
+
+### Added
+
+- Mobile HUD fit — design-resolution UI scaling now applies to every game by default: `HudCanvas` measures the live viewport and scales the whole HUD from `PlayableGame.hudFit.designSize` (default 1600×900, clamps `minScale`/`maxScale` 0.4–1) so desktop-authored layouts shrink to fit a phone instead of overflowing it; `hudFit.mobile` overrides tune the phone fit separately. Pure math lives in `@jgengine/core/ui/hudScale` (`hudScaleForViewport`, `resolveHudFit`, `rectOverflow`, `overflowingPanels`); the shell mounts `@jgengine/react`'s `HudViewportProvider` around `GameUI` so games need no wiring.
+- Graphics → UI scale — a player-facing `graphics.uiScale` slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform; the same resolution system drives desktop preference and mobile shrink.
+- HUD overflow gate — `HudCanvas` measures every `HudPanel` against the viewport at runtime and reports offenders on a `data-hud-overflow` attribute (plus a console warning); `bun run shoot <game> --device mobile|both` now exits non-zero naming the panels that escape the viewport.
+- Automatic visibility & streaming defaults — an engine-level `VisibilitySystem` (exported from `@jgengine/core`) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness (including cameras excluded from streaming), and per-object overrides (always-visible, never-unload, disabled culling/streaming, custom render distance and preload margin).
+- Self-hosted asset mirror — `DEFAULT_RELEASE_BASE` now points at this repo's rolling `packs` release instead of the upstream host; a catalog-driven `mirror-assets` workflow (weekly cron + manual dispatch) keeps the mirror in sync with the asset catalog.
+
+### Changed
+
+- Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (previously opt-in via `platforms: ["web", "mobile"]`). A desktop-only game keeps the legacy fixed 0.85 compact zoom by declaring `platforms: ["web"]` (without `"mobile"`).
+
+## 0.8.0
+
+Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel
+and puzzle primitives, HUD-only presentation, cumulative leveling, and a round of
+controller/camera/sensor additions. **Breaking:** the `gameui` component kit moved out of
+`@jgengine/react` onto the shadcn registry.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.8.0` (the eight packages version in lockstep).
+- Additive only, except for `gameui` — every other 0.7.0 API is unchanged; opt into any of the below by importing it directly.
+- **Breaking:** replace any `@jgengine/react/gameui` import with the equivalent registry component (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), and swap `GameUiThemeProvider` for `--jg-*` CSS variables on a wrapper element. `GameIcon` and friends moved to `@jgengine/react/gameIcons`.
+- `leveling({ thresholdMode: 'cumulative' })` is opt-in; the default `perLevel` behavior is unchanged.
+- `defineGame.physics.gravity`/`jumpVelocity` are now read by the built-in kinematics controller every frame — if a game already set them expecting a no-op, jump/fall now actually reflects them; omit both to keep the previous defaults.
+
+### Added
+
+- Cumulative leveling — `leveling({ thresholdMode: 'cumulative' })` tracks xp as a lifetime total that resolves upward across levels and clamps at the max-level threshold once capped (#12).
+- Direction-aware pool depletion — `EffectSystem.canReceive(instanceId, effect, magnitude?)` takes an optional signed magnitude; negative checks the opposite direction and returns `pools-depleted` only when every stat in the receive order is already at max, so heals reach fully-depleted targets (#168).
+- Puzzle primitives — `puzzle/cellGrid` (uniform-cell boards: line-clear, match-3 cascade, run detection) and `puzzle/fallingPiece` (rotation-state shapes, ghost drop, lock delay, classic gravity/level/score curves) for Tetris/match-3 games (#166).
+- Voxel field — `world/voxelField` (`createVoxelField`, chunked block lattice, neighbors/exposedFaces, 3D DDA raycast, dirty-tracked `chunkVersion`) for voxel games and instanced renderers; assert on `field.summary()` the way environment worlds assert on `summarizeEnvironment` (#166).
+- `defineGame` games may omit `assets` (an empty catalog is injected); `PlayableGame.presentation: 'hud'` mounts no 3D canvas/camera/pointer for board/card/menu games; an `environment()` world auto-renders as the shell's backdrop when `PlayableGame.environment` is unset (#166).
+- Declared-action intent board — `turn/intent` `createIntentBoard` for one-turn-ahead intents (Slay-the-Spire style): declare/peek/all/consume/clear (#168).
+- `turnLoop` lifecycle hooks — `config.onTurnStart`/`onTurnEnd` fire on every `advanceTurn()`; `ctx.game.turn.loop(id, config)` lazily creates/returns a notify-wrapped `TurnLoop` so every mutation (`advanceTurn`/`advancePhase`/`advanceRound`/`spend`/`gain`/`refill`/`setOrder`/...) auto-bumps `ctx.version()` with no manual wiring (#163/#168).
+- `ctx.game.store` — a reactive per-game keyed store (`set`/`delete`/`get`/`has`/`subscribe`/`mapSnapshot`/`arraySnapshot`) plus `@jgengine/react`'s `useGameStore` selector hook, replacing hand-rolled module-level stores for ad-hoc reactive game state; `ctx.game.cards.pile(id, config?)` lazily creates/returns a notify-wrapped `CardPile` the same way; `createCardPile` gained an `onChange` hook for headless use; `CommandDefinition.apply` may return void for side-effect-only commands (#163).
+- Camera — `sideScroll` rig (fixed lateral follow for 2.5D platformers/beat-'em-ups), a `none` rig (no camera mounted; pairs with `PlayableGame.presentation: 'hud'`), `rts.pan: false` (static backdrop camera: no pan/edge-scroll/rotate/zoom, still re-centers on the follow target), and the `observer` rig now defaults to the local player when `bind` is unset (#167).
+- Sensors + session — `sensor/concealment` (`colorDistance`/`concealmentScore`/`createConcealmentSensor`), `sensor/freezeMonitor` (`createFreezeMonitor`), `session/roles` (`assignRoles`); `createRoundState`'s `RoundConfig.teams` accepts per-team roles and an optional `winCondition` that `evaluate()` checks each tick, and takes an optional `phaseOrder` for arbitrary named phase cycles (`concludeRound`/`evaluate` settle only while the current phase is neither the first nor the last entry) (#151).
+- Appearance replication — presence rows carry an optional per-slot appearance channel (cosmetic ids, hex tints, model keys) alongside pose, riding the existing pose message with no protocol bump; wire `ctx.player.cosmetics.get(userId)` into the outgoing pose (#151).
+- `ctx.input` — a per-frame held-action snapshot (`publish(held)`/`isDown(action)`/`held()`) without bumping `ctx.version()`; action bindings gained `repeatMs` (repeat-fire while held); every command resolved from a bound action now carries `aim`; `pointer.secondaryCommand` runs a command on right-click off the same raycast as move/ping (#164).
+- Object spatial queries + entity patching — `ctx.scene.object.at`/`inBox`/`raycast`/`raycastAll` over unit-box objects; `ctx.scene.entity.update(id, patch)` for name/position/rotation/role/movement/behaviors/meta; per-instance `renderObject`/`objectStyles` overrides; `pointerService.worldHitCenter()` + pointer-lock center-ray aiming (#165).
+- Controller movement config — `PlayerMovementConfig` (`mode`: free/axis/grid, `axis`, `cellSize`, `collideObjects`, `beforeCommit` pre-commit hook) for the shell-driven walk controller; `defineGame.physics.gravity`/`jumpVelocity` are honored by the built-in walk controller (distinct from the standalone `physics/physicsWorld` rigid-body sim); `ctx.player.motion.impulse`/`setVerticalVelocity`/`setY`/`takePending` (`MotionIntents`); `entity.spawnPoseOf`/`resetToSpawn`/`resetAllToSpawn` (#162).
+- Model material/animation + paint — `ModelConfig.tint`/`metalness`/`roughness`/`animation` (GLTF clip playback, paused pose holds); `PointerHit.uv` + `pointerService.sampleSurface()` for material-aware picking; `ctx.scene.entity.paint` runtime paint layer, auto-rendered via a per-instance canvas texture with no per-game wiring; remote-player appearance tint recolors the shell's default capsule (#151).
+- **Transport pipe seam** (`@jgengine/ws/pipe`) — `createWsBackend` runs over any bidirectional string channel, not just a raw `WebSocket`: `TransportPipe`/`TransportPipeHandlers`/`TransportPipeFactory`, with `webSocketPipe(url, webSocketFactory?)` as the default. `createWsBackend({ userId, url?, pipe? })` — `url` stays the common case, `pipe` opens the seam to socket.io, WebRTC, and in-process loopback below.
+- **Browser-safe authoritative host** — `createGameHost` and `memoryPersistence` moved from `@jgengine/node` to `@jgengine/ws/host` (zero Node dependencies; `@jgengine/node` re-exports both unchanged from `@jgengine/node/host` / `@jgengine/node/persistence`, so existing imports keep working). `@jgengine/ws/hostRouter`'s `createHostRouter({ host, authenticate?, poseRules?, positionHistoryMs?, chatRateLimit?, chatHistoryLimit?, chatMaxBodyLength?, now? })` extracts the ws wire-protocol session logic out of `createGameWsServer` into a transport-agnostic `HostRouter` (`connect(transport) → { handleRaw, close }`, `rewind`, `close`); `@jgengine/node`'s `createGameWsServer` is now a thin binding of this router onto the `ws` npm package, same public API. `loopbackPipe(router): TransportPipeFactory` connects a `createWsBackend` straight into an in-process router.
+- **Socket.IO transport** — `@jgengine/ws/socketIoPipe` (`SocketIoLikeSocket` structural type, `socketIoPipe(socket)`, `createSocketIoBackend({ socket, userId, … })`) and `@jgengine/node/socketIoServer` (`attachGameSocketIoServer({ io, host, …router options }): { rewind, close }`, structural `SocketIoLikeServer`/`SocketIoLikeServerSocket`) ride the existing ws JSON protocol over socket.io's `send`/`message` frames — no socket.io dependency in either package's types. New `socketIo({ topology?, url? })` adapter in `@jgengine/core/runtime/adapter`.
+- **WebRTC peer-to-peer** (`@jgengine/ws/peer`) — one browser tab hosts, authoritatively, with no server process. `createPeerHost({ userId, host?, runtimes?, persistence?, tickMs?, router?, rtc? })` runs a `GameHost` + `HostRouter` in the host tab (`backend` is the host player's own loopback connection, `accept(offerCode) → Promise<answerCode>` per guest); `createPeerGuest({ userId, token?, rtc? })` offers/connects from the joining side. `encodePeerSignal`/`decodePeerSignal` turn SDP into copy-pasteable base64url codes for manual cross-machine signaling; `broadcastChannelSignaling(room)` automates it for same-origin multi-tab play, with `announcePeerHost`/`joinPeerSession` wiring host/guest to a `PeerSignaling` in one call. New `p2p({ topology?, room? })` adapter (topology defaults `"private"`).
+- **LAN adapter + Fly sugar** — `lan({ topology?, port?, path? })` in `@jgengine/core/runtime/adapter` resolves through `@jgengine/shell/multiplayer`'s `resolveShellMultiplayer` to `ws(s)://<page hostname>:<port ?? 8080><path ?? /ws>` derived from `window.location`, so any browser on the LAN auto-connects to whichever machine served the page — no URL configuration. `fly({ app, topology?, path? })` is `ws` sugar for a Fly.io deploy: resolves to `wss://<app>.fly.dev<path ?? "/ws">`. `apps/dev`'s Vite server now listens on the network (`server: { host: true }`) and exposes `?p2p=host` / `?p2p=join` query params wired through the new `resolvePeerShellMultiplayer({ gameId, role, room?, userId?, feedActions? })`.
+- `ws()` (`@jgengine/core/runtime/adapter`) gained an optional `url` field, carried through by `resolveShellMultiplayer` (`args.url ?? adapter.url ?? default`).
+
+### Removed
+
+- **The `gameui` component kit** (`@jgengine/react/gameui`) — the themed HUD kit (bars, slots, feedback, meters, panels, screens, reticles, icons) and its `GameUiThemeProvider`/`useGameUiTheme` theming have been removed. **Breaking** for anyone importing `@jgengine/react/gameui` (or its subpaths/barrel). The components now ship as installable shadcn registry items at `https://jgengine.com/r/<name>.json` (`npx shadcn@latest add https://jgengine.com/r/<name>.json`), styled with Tailwind + `--jg-*` CSS variables instead of a theme object. The icon catalog (`GameIcon`, `iconForAction`, `iconForItemId`, `isGameIconName`, `GameIconName`) moved to `@jgengine/react/gameIcons`. To theme, set the `--jg-*` variables on a wrapper element (the registry's `jg-theme` presets mirror the old `ember`/`synthwave`/`fieldkit` palettes) instead of wrapping in `GameUiThemeProvider`.
+
+### Docs
+
+- Added [CREDITS.md](CREDITS.md) crediting [achrefelouafi](https://github.com/achrefelouafi) for the MIT Three.js reference projects behind the procedural building, water, rain, and snow renderers, with links from the root, `@jgengine/core`, and `@jgengine/shell` READMEs.
+
 ## 0.7.0
 
 The engine-gaps release — 22 system-level additions across turn/tactics, cards & boards,

package/README.md

@@ -8,4 +8,6 @@ Import modules by path:
 import { createGameRuntime } from "@jgengine/core/runtime/gameRuntime";
 ```
 
+The renderer-free world layer includes a Gerstner `waterSurface` (`world/water`) and a seeded `generateBuilding` kit (`world/buildings`), whose wave math and building component vocabulary were shaped from **[achrefelouafi](https://github.com/achrefelouafi)**'s MIT [OceanThreejs](https://github.com/achrefelouafi/OceanThreejs) and [BuildingGeneratorThreeJS](https://github.com/achrefelouafi/BuildingGeneratorThreeJS) — see [CREDITS.md](../../CREDITS.md).
+
 Part of [JGengine](https://github.com/Noisemaker111/jgengine). AGPL-3.0-only.

package/dist/ai/flock.d.ts

@@ -0,0 +1,36 @@
+export type FlockVec3 = readonly [number, number, number];
+export interface FlockAgent {
+    position: FlockVec3;
+    velocity: FlockVec3;
+}
+export interface FlockConfig {
+    maxSpeed: number;
+    /** How hard steering can change velocity (units/s²); default `maxSpeed * 2`. */
+    accel?: number;
+    separationRadius: number;
+    separationWeight?: number;
+    /** Neighbors inside this radius pull toward the local centroid and average heading. */
+    neighborRadius: number;
+    cohesionWeight?: number;
+    alignmentWeight?: number;
+    /** Pull toward the seek target; default `1`. */
+    seekWeight?: number;
+    /** Beyond this distance from the flock centroid an agent's cohesion is boosted so stragglers rejoin. */
+    stragglerRadius?: number;
+    /** Cohesion multiplier applied to stragglers; default `3`. */
+    stragglerBoost?: number;
+}
+/**
+ * Classic per-agent boid steering — seek + separation + cohesion + alignment with a straggler
+ * rescue radius — the many-agents-to-*each-other* primitive `ai/crowd`'s navmesh flow field
+ * (many-agents-to-POI) deliberately isn't. Pure: returns the desired acceleration for one agent;
+ * `stepFlock` is the convenience integrator. O(neighbors) per agent — pre-filter with a spatial
+ * grid past a few hundred agents.
+ */
+export declare function flockSteer(agent: FlockAgent, neighbors: readonly FlockAgent[], config: FlockConfig, target?: FlockVec3): FlockVec3;
+export interface FlockStepAgent {
+    position: FlockVec3;
+    velocity: FlockVec3;
+}
+/** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions. */
+export declare function stepFlock(agents: FlockStepAgent[], config: FlockConfig, dt: number, target?: FlockVec3): void;

package/dist/ai/flock.js

@@ -0,0 +1,182 @@
+/**
+ * Classic per-agent boid steering — seek + separation + cohesion + alignment with a straggler
+ * rescue radius — the many-agents-to-*each-other* primitive `ai/crowd`'s navmesh flow field
+ * (many-agents-to-POI) deliberately isn't. Pure: returns the desired acceleration for one agent;
+ * `stepFlock` is the convenience integrator. O(neighbors) per agent — pre-filter with a spatial
+ * grid past a few hundred agents.
+ */
+export function flockSteer(agent, neighbors, config, target) {
+    const separationWeight = config.separationWeight ?? 1.5;
+    const cohesionWeight = config.cohesionWeight ?? 1;
+    const alignmentWeight = config.alignmentWeight ?? 1;
+    const seekWeight = config.seekWeight ?? 1;
+    const accel = config.accel ?? config.maxSpeed * 2;
+    let sepX = 0;
+    let sepY = 0;
+    let sepZ = 0;
+    let cohX = 0;
+    let cohY = 0;
+    let cohZ = 0;
+    let alignX = 0;
+    let alignY = 0;
+    let alignZ = 0;
+    let flockmates = 0;
+    for (const other of neighbors) {
+        if (other === agent)
+            continue;
+        const dx = other.position[0] - agent.position[0];
+        const dy = other.position[1] - agent.position[1];
+        const dz = other.position[2] - agent.position[2];
+        const distance = Math.hypot(dx, dy, dz);
+        if (distance > config.neighborRadius)
+            continue;
+        flockmates += 1;
+        cohX += other.position[0];
+        cohY += other.position[1];
+        cohZ += other.position[2];
+        alignX += other.velocity[0];
+        alignY += other.velocity[1];
+        alignZ += other.velocity[2];
+        if (distance < config.separationRadius && distance > 1e-9) {
+            const push = (config.separationRadius - distance) / config.separationRadius / distance;
+            sepX -= dx * push;
+            sepY -= dy * push;
+            sepZ -= dz * push;
+        }
+    }
+    let steerX = sepX * separationWeight;
+    let steerY = sepY * separationWeight;
+    let steerZ = sepZ * separationWeight;
+    if (flockmates > 0) {
+        const centroidX = cohX / flockmates;
+        const centroidY = cohY / flockmates;
+        const centroidZ = cohZ / flockmates;
+        const toCentroidX = centroidX - agent.position[0];
+        const toCentroidY = centroidY - agent.position[1];
+        const toCentroidZ = centroidZ - agent.position[2];
+        const centroidDistance = Math.hypot(toCentroidX, toCentroidY, toCentroidZ);
+        const straggling = config.stragglerRadius !== undefined && centroidDistance > config.stragglerRadius;
+        const cohesion = cohesionWeight * (straggling ? config.stragglerBoost ?? 3 : 1);
+        if (centroidDistance > 1e-9) {
+            steerX += (toCentroidX / centroidDistance) * cohesion;
+            steerY += (toCentroidY / centroidDistance) * cohesion;
+            steerZ += (toCentroidZ / centroidDistance) * cohesion;
+        }
+        const alignMagnitude = Math.hypot(alignX, alignY, alignZ);
+        if (alignMagnitude > 1e-9) {
+            steerX += (alignX / alignMagnitude) * alignmentWeight;
+            steerY += (alignY / alignMagnitude) * alignmentWeight;
+            steerZ += (alignZ / alignMagnitude) * alignmentWeight;
+        }
+    }
+    if (target !== undefined) {
+        const toTargetX = target[0] - agent.position[0];
+        const toTargetY = target[1] - agent.position[1];
+        const toTargetZ = target[2] - agent.position[2];
+        const targetDistance = Math.hypot(toTargetX, toTargetY, toTargetZ);
+        if (targetDistance > 1e-9) {
+            steerX += (toTargetX / targetDistance) * seekWeight;
+            steerY += (toTargetY / targetDistance) * seekWeight;
+            steerZ += (toTargetZ / targetDistance) * seekWeight;
+        }
+    }
+    const magnitude = Math.hypot(steerX, steerY, steerZ);
+    if (magnitude <= 1e-9)
+        return [0, 0, 0];
+    const scale = accel / magnitude;
+    return [steerX * scale, steerY * scale, steerZ * scale];
+}
+const CELL_KEY_STRIDE = 1_048_576;
+const gridCells = new Map();
+const freeBuckets = [];
+const neighborScratch = [];
+let steerScratch = new Float64Array(0);
+function cellKey(cx, cz) {
+    return cx * CELL_KEY_STRIDE + cz;
+}
+function takeBucket() {
+    return freeBuckets.pop() ?? [];
+}
+function ensureSteerCapacity(agentCount) {
+    const needed = agentCount * 3;
+    if (steerScratch.length < needed) {
+        steerScratch = new Float64Array(needed);
+    }
+}
+function buildAgentGrid(agents, invCell) {
+    for (const bucket of gridCells.values()) {
+        bucket.length = 0;
+        freeBuckets.push(bucket);
+    }
+    gridCells.clear();
+    for (let i = 0; i < agents.length; i += 1) {
+        const position = agents[i].position;
+        const key = cellKey(Math.floor(position[0] * invCell), Math.floor(position[2] * invCell));
+        let bucket = gridCells.get(key);
+        if (bucket === undefined) {
+            bucket = takeBucket();
+            gridCells.set(key, bucket);
+        }
+        bucket.push(i);
+    }
+}
+function fillNeighbors(agents, agentIndex, invCell) {
+    const agent = agents[agentIndex];
+    const cx = Math.floor(agent.position[0] * invCell);
+    const cz = Math.floor(agent.position[2] * invCell);
+    let count = 0;
+    for (let dz = -1; dz <= 1; dz += 1) {
+        for (let dx = -1; dx <= 1; dx += 1) {
+            const bucket = gridCells.get(cellKey(cx + dx, cz + dz));
+            if (bucket === undefined)
+                continue;
+            for (let b = 0; b < bucket.length; b += 1) {
+                const otherIndex = bucket[b];
+                if (otherIndex === agentIndex)
+                    continue;
+                neighborScratch[count] = agents[otherIndex];
+                count += 1;
+            }
+        }
+    }
+    neighborScratch.length = count;
+    return count;
+}
+/** Integrate one tick in place: steer every agent, clamp to `maxSpeed`, advance positions. */
+export function stepFlock(agents, config, dt, target) {
+    const count = agents.length;
+    if (count === 0)
+        return;
+    const cellSize = config.neighborRadius > 1e-6 ? config.neighborRadius : 1;
+    const invCell = 1 / cellSize;
+    buildAgentGrid(agents, invCell);
+    ensureSteerCapacity(count);
+    for (let i = 0; i < count; i += 1) {
+        fillNeighbors(agents, i, invCell);
+        const steer = flockSteer(agents[i], neighborScratch, config, target);
+        const base = i * 3;
+        steerScratch[base] = steer[0];
+        steerScratch[base + 1] = steer[1];
+        steerScratch[base + 2] = steer[2];
+    }
+    for (let i = 0; i < count; i += 1) {
+        const agent = agents[i];
+        const base = i * 3;
+        let vx = agent.velocity[0] + steerScratch[base] * dt;
+        let vy = agent.velocity[1] + steerScratch[base + 1] * dt;
+        let vz = agent.velocity[2] + steerScratch[base + 2] * dt;
+        const speed = Math.hypot(vx, vy, vz);
+        if (speed > config.maxSpeed) {
+            const clamp = config.maxSpeed / speed;
+            vx *= clamp;
+            vy *= clamp;
+            vz *= clamp;
+        }
+        agent.velocity = [vx, vy, vz];
+        agent.position = [
+            agent.position[0] + vx * dt,
+            agent.position[1] + vy * dt,
+            agent.position[2] + vz * dt,
+        ];
+    }
+}

package/dist/ai/groupAssist.d.ts

@@ -0,0 +1,19 @@
+import type { ThreatTable } from "./threat.js";
+export interface AssistMember {
+    id: string;
+    groupId: string;
+    table: ThreatTable;
+}
+export interface AssistNetworkConfig {
+    radius?: number;
+    shareFraction?: number;
+    distanceBetween?: (a: string, b: string) => number;
+}
+export interface AssistNetwork {
+    register(member: AssistMember): void;
+    remove(memberId: string): void;
+    memberIds(groupId?: string): string[];
+    assistersOf(memberId: string): string[];
+    addThreat(memberId: string, sourceId: string, amount: number): string[];
+}
+export declare function createAssistNetwork(config?: AssistNetworkConfig): AssistNetwork;

package/dist/ai/groupAssist.js

@@ -0,0 +1,59 @@
+export function createAssistNetwork(config = {}) {
+    const radius = config.radius;
+    const shareFraction = Math.max(0, config.shareFraction ?? 1);
+    const distanceBetween = config.distanceBetween;
+    const members = new Map();
+    const order = [];
+    function inRange(memberId, otherId) {
+        if (radius === undefined || !distanceBetween)
+            return true;
+        return distanceBetween(memberId, otherId) <= radius;
+    }
+    return {
+        register(member) {
+            if (!members.has(member.id))
+                order.push(member.id);
+            members.set(member.id, member);
+        },
+        remove(memberId) {
+            if (!members.delete(memberId))
+                return;
+            const index = order.indexOf(memberId);
+            if (index !== -1)
+                order.splice(index, 1);
+        },
+        memberIds(groupId) {
+            if (groupId === undefined)
+                return [...order];
+            return order.filter((id) => members.get(id).groupId === groupId);
+        },
+        assistersOf(memberId) {
+            const member = members.get(memberId);
+            if (!member)
+                return [];
+            return order.filter((id) => {
+                if (id === memberId)
+                    return false;
+                const other = members.get(id);
+                return other.groupId === member.groupId && inRange(memberId, id);
+            });
+        },
+        addThreat(memberId, sourceId, amount) {
+            const member = members.get(memberId);
+            if (!member || amount <= 0)
+                return [];
+            member.table.add(sourceId, amount);
+            if (shareFraction <= 0)
+                return [];
+            const assisters = order.filter((id) => {
+                if (id === memberId)
+                    return false;
+                const other = members.get(id);
+                return other.groupId === member.groupId && inRange(memberId, id);
+            });
+            for (const id of assisters)
+                members.get(id).table.add(sourceId, amount * shareFraction);
+            return assisters;
+        },
+    };
+}

package/dist/ai/laneSelect.d.ts

@@ -0,0 +1,21 @@
+export interface LaneCandidate<TId extends string = string> {
+    id: TId;
+    cost: number;
+}
+export interface PickLaneOptions<TId extends string = string> {
+    /** The lane currently taken — kept unless a rival is decisively cheaper. */
+    current?: TId | null;
+    /** How much cheaper a rival must be to displace `current`: it wins only when `cost < currentCost / stickiness`. Default `1.2`. */
+    stickiness?: number;
+    /** Candidates within this cost of the best tie for the win; the tie is broken by `rng`. Default `0`. */
+    tieEpsilon?: number;
+    rng?: () => number;
+}
+/**
+ * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
+ * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
+ * and let stickiness hysteresis stop the agent flip-flopping between near-equal lanes.
+ */
+export declare function pickLane<TId extends string>(candidates: readonly LaneCandidate<TId>[], options?: PickLaneOptions<TId>): TId | null;
+/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`. */
+export declare function corridorCost(points: readonly (readonly [number, number])[], costAt: (x: number, z: number) => number): number;

package/dist/ai/laneSelect.js

@@ -0,0 +1,37 @@
+/**
+ * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
+ * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
+ * and let stickiness hysteresis stop the agent flip-flopping between near-equal lanes.
+ */
+export function pickLane(candidates, options = {}) {
+    if (candidates.length === 0)
+        return null;
+    const stickiness = options.stickiness ?? 1.2;
+    const tieEpsilon = options.tieEpsilon ?? 0;
+    const rng = options.rng ?? Math.random;
+    let best = candidates[0];
+    for (const candidate of candidates) {
+        if (candidate.cost < best.cost)
+            best = candidate;
+    }
+    if (tieEpsilon > 0) {
+        const tied = candidates.filter((candidate) => candidate.cost <= best.cost + tieEpsilon);
+        if (tied.length > 1)
+            best = tied[Math.min(tied.length - 1, Math.floor(rng() * tied.length))];
+    }
+    const current = options.current ?? null;
+    if (current !== null && current !== best.id) {
+        const currentCandidate = candidates.find((candidate) => candidate.id === current);
+        if (currentCandidate !== undefined && best.cost >= currentCandidate.cost / stickiness) {
+            return current;
+        }
+    }
+    return best.id;
+}
+/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`. */
+export function corridorCost(points, costAt) {
+    let total = 0;
+    for (const [x, z] of points)
+        total += costAt(x, z);
+    return total;
+}

package/dist/ai/mobBrain.d.ts

@@ -0,0 +1,68 @@
+import { type ThreatTable, type ThreatTableConfig } from "./threat.js";
+export type MobBrainMode = "idle" | "wander" | "chase" | "engage" | "evade";
+export type MobVec3 = readonly [number, number, number];
+export interface MobWanderConfig {
+    /** Radius around home the wander points are drawn from. */
+    radius: number;
+    /** Seconds between wander-point picks; default `4`. */
+    intervalSeconds?: number;
+    /** Movement speed multiplier while wandering; default `0.35`. */
+    speedScale?: number;
+    /** Distance at which a wander point counts as reached; default `0.6`. */
+    arriveRadius?: number;
+}
+export interface MobBrainConfig {
+    /** Distance at which an unaggroed candidate pulls threat and becomes the target. */
+    aggroRadius: number;
+    /** Distance inside which the step reports `inAttackRange` and stops chasing. */
+    attackRange: number;
+    /** Distance from home beyond which the mob drops all threat and evades back. */
+    leashDistance: number;
+    /** Idle wandering around home; omit or `false` to stand still. */
+    wander?: MobWanderConfig | false;
+    /** Movement speed multiplier while evading home; default `1.4`. */
+    evadeSpeedScale?: number;
+    /** Target-switch stickiness passed to the threat table's `highest`; default `1.15`. */
+    stickiness?: number;
+    /** Distance to home at which an evade completes; default `1.2`. */
+    homeArriveRadius?: number;
+    threat?: ThreatTableConfig;
+}
+export interface MobBrainDeps {
+    home: MobVec3;
+    /** The mob's current position; `null` pauses the brain (despawned). */
+    position(): MobVec3 | null;
+    /** A target's current position; `null` drops it from the threat table (despawned, dead). */
+    targetPosition(targetId: string): MobVec3 | null;
+    /** Potential aggro targets near the mob — the brain distance-filters against `aggroRadius`. */
+    candidates(): readonly string[];
+    rng?: () => number;
+}
+export interface MobBrainStep {
+    mode: MobBrainMode;
+    targetId: string | null;
+    /** Where to step this tick — feed to `moveToward`; `null` holds position. */
+    moveTo: MobVec3 | null;
+    /** Multiplier on the mob's base move speed for this step. */
+    speedScale: number;
+    /** The target is inside `attackRange` — the swing/cast window. */
+    inAttackRange: boolean;
+    /** Fires on the single step an evade run reaches home — the reset/full-heal hook. */
+    arrivedHome: boolean;
+}
+/**
+ * The wander → aggro → chase → engage → leash-evade loop every MMO-shaped game hand-rolls,
+ * composed over `ai/threat`. The brain decides intent; the game executes it (`moveToward`,
+ * ground-snap, facing, swings) and routes damage into `addThreat`. Pack aggro is game-side:
+ * call `addThreat` on nearby packmates' brains when one aggros.
+ */
+export interface MobBrain {
+    readonly threat: ThreatTable;
+    mode(): MobBrainMode;
+    /** Route damage/heal aggro here — sugar over `threat.add`; ignored while the mob is evading. */
+    addThreat(sourceId: string, amount: number): void;
+    tick(dt: number): MobBrainStep;
+    /** Back to idle at full rest (respawn) — clears threat, evade, and wander state. */
+    reset(): void;
+}
+export declare function createMobBrain(config: MobBrainConfig, deps: MobBrainDeps): MobBrain;

package/dist/ai/mobBrain.js

@@ -0,0 +1,115 @@
+import { createThreatTable } from "./threat.js";
+const HOLD = {
+    targetId: null,
+    moveTo: null,
+    speedScale: 1,
+    inAttackRange: false,
+    arrivedHome: false,
+};
+function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+export function createMobBrain(config, deps) {
+    const threat = createThreatTable(config.threat);
+    const stickiness = config.stickiness ?? 1.15;
+    const evadeSpeedScale = config.evadeSpeedScale ?? 1.4;
+    const homeArriveRadius = config.homeArriveRadius ?? 1.2;
+    const wander = config.wander === false || config.wander === undefined ? null : config.wander;
+    const wanderInterval = wander?.intervalSeconds ?? 4;
+    const wanderArrive = wander?.arriveRadius ?? 0.6;
+    const rng = deps.rng ?? Math.random;
+    let currentMode = "idle";
+    let currentTarget = null;
+    let evading = false;
+    let wanderClock = 0;
+    let wanderTo = null;
+    function step(mode, patch = {}) {
+        currentMode = mode;
+        return { mode, ...HOLD, ...patch };
+    }
+    function acquireByProximity(position) {
+        let nearest = null;
+        let nearestDistance = config.aggroRadius;
+        for (const candidateId of deps.candidates()) {
+            const candidatePosition = deps.targetPosition(candidateId);
+            if (candidatePosition === null)
+                continue;
+            const candidateDistance = distance(position, candidatePosition);
+            if (candidateDistance <= nearestDistance) {
+                nearest = candidateId;
+                nearestDistance = candidateDistance;
+            }
+        }
+        if (nearest !== null)
+            threat.add(nearest, 1);
+    }
+    return {
+        threat,
+        mode: () => currentMode,
+        addThreat(sourceId, amount) {
+            if (evading)
+                return;
+            threat.add(sourceId, amount);
+        },
+        tick(dt) {
+            const position = deps.position();
+            if (position === null)
+                return step(currentMode);
+            if (evading) {
+                if (distance(position, deps.home) <= homeArriveRadius) {
+                    evading = false;
+                    wanderClock = 0;
+                    wanderTo = null;
+                    return step("idle", { arrivedHome: true });
+                }
+                return step("evade", { moveTo: deps.home, speedScale: evadeSpeedScale });
+            }
+            threat.decay(dt);
+            if (threat.size() === 0)
+                acquireByProximity(position);
+            let targetId = threat.highest({ current: currentTarget, stickiness });
+            if (targetId !== null && deps.targetPosition(targetId) === null) {
+                threat.remove(targetId);
+                targetId = threat.highest({ stickiness });
+            }
+            currentTarget = targetId;
+            if (targetId !== null) {
+                if (distance(position, deps.home) > config.leashDistance) {
+                    threat.clear();
+                    currentTarget = null;
+                    evading = true;
+                    return step("evade", { moveTo: deps.home, speedScale: evadeSpeedScale });
+                }
+                const targetPosition = deps.targetPosition(targetId);
+                if (targetPosition === null)
+                    return step(currentMode);
+                if (distance(position, targetPosition) <= config.attackRange) {
+                    return step("engage", { targetId, inAttackRange: true });
+                }
+                return step("chase", { targetId, moveTo: targetPosition });
+            }
+            if (wander === null)
+                return step("idle");
+            wanderClock += dt;
+            if (wanderTo !== null && distance(position, wanderTo) <= wanderArrive)
+                wanderTo = null;
+            if (wanderTo === null && wanderClock >= wanderInterval) {
+                wanderClock = 0;
+                const angle = rng() * Math.PI * 2;
+                const radius = Math.sqrt(rng()) * wander.radius;
+                wanderTo = [deps.home[0] + Math.cos(angle) * radius, deps.home[1], deps.home[2] + Math.sin(angle) * radius];
+            }
+            if (wanderTo === null)
+                return step("idle");
+            return step("wander", { moveTo: wanderTo, speedScale: wander.speedScale ?? 0.35 });
+        },
+        reset() {
+            threat.clear();
+            currentMode = "idle";
+            currentTarget = null;
+            evading = false;
+            wanderClock = 0;
+            wanderTo = null;
+        },
+    };
+}

package/dist/ai/spawnDirector.d.ts

@@ -21,6 +21,8 @@ export interface SpawnDirectorConfig {
     maxSpawnsPerTick?: number;
     loop?: boolean;
     seed?: number;
+    spawnPoints?: readonly NavPoint[];
+    spawnPointBias?: number;
 }
 export interface SpawnDirectorState {
     wave: number;
@@ -36,11 +38,14 @@ export interface SpawnDirectorState {
 export interface DirectorContext {
     alive: number;
     players?: number;
+    playerPositions?: readonly NavPoint[];
 }
 export interface SpawnRequest {
     entryId: string;
     cost: number;
     wave: number;
+    point?: NavPoint;
+    laneId?: number;
 }
 export interface DirectorStep {
     state: SpawnDirectorState;