@jgengine/core 0.18.1 → 0.19.0

package/dist/runtime/context/deathLoot.js

@@ -14,6 +14,7 @@ export function applyLethalLoot(input) {
         const resolved = resolveDeathDrops([...input.drops], {
             mode: "world",
             origin: input.position,
+            rng: input.rng,
             resolveRarity: (itemId) => input.content.itemById?.(itemId)?.rarity ?? DEFAULT_RARITY,
             resolveBaseType: (itemId) => input.content.itemById?.(itemId)?.baseType ?? itemId,
             scatter: normalizedOnDeath.scatter,

package/dist/runtime/gameContext.js

@@ -1,6 +1,7 @@
 import { createCommandRegistry } from "../commands/commandRegistry.js";
 import {} from "../game/cosmetics.js";
 import { groundFieldFor } from "../world/terrain.js";
+import { createWorldSolids, structureSolids } from "../world/worldSolids.js";
 import { createGameEvents } from "../game/events.js";
 import { createGameFeed } from "../game/feed.js";
 import { setGamePhase } from "../game/gamePhase.js";
@@ -43,6 +44,10 @@ export function createGameContext(options) {
     const activeUserId = () => actingUserId ?? player.userId;
     const time = createSimClock({ config: definition.time, onChange: signal.notify });
     const ground = groundFieldFor(definition.world);
+    const solids = createWorldSolids();
+    if (definition.world?.kind === "environment") {
+        solids.set("environment:structures", structureSolids(definition.world, ground.sampleHeight));
+    }
     const rawEvents = createGameEvents();
     const events = {
         on: rawEvents.on,
@@ -215,6 +220,7 @@ export function createGameContext(options) {
             commandRegistry.run(ctxRef, name, args);
         },
         localUserId: player.userId,
+        rng,
         ...(definition.physics !== undefined ? { physics: definition.physics } : {}),
     });
     scene.setOnAfterSpawn((instanceId) => combat.death.revive(instanceId));
@@ -406,6 +412,7 @@ export function createGameContext(options) {
         world: {
             ground,
             groundHeightAt: ground.sampleHeight,
+            solids,
         },
         game: {
             territory: options.territory,

package/dist/runtime/gameContextTypes.d.ts

@@ -11,6 +11,7 @@ import type { ChargeOptions as WalletChargeOptions } from "../economy/wallet.js"
 import type { Cosmetics } from "../game/cosmetics.js";
 import type { GameDefinition } from "../game/defineGame.js";
 import type { TerrainField } from "../world/terrain.js";
+import type { WorldSolids } from "../world/worldSolids.js";
 import type { GameEventMap, GameEvents, VfxKind } from "../game/events.js";
 import type { VfxInstanceStore } from "../game/vfxInstance.js";
 import type { GameFeed } from "../game/feed.js";
@@ -344,6 +345,11 @@ export type WorldItemPickupResult = {
     status: "rejected";
     reason: string;
 };
+/**
+ * `ctx.scene.worldItem`: items lying in the world — spawn, list, find the nearest, and pick up into a player's bag.
+ *
+ * @capability world-item-pickup pick up dropped items: ctx.scene.worldItem nearestInRadius → pickup into the player's inventory
+ */
 export interface SceneWorldItemContext {
     spawn(input: WorldItemSpawnInput): WorldItemRecord;
     get(instanceId: string): WorldItemRecord | null;
@@ -390,6 +396,11 @@ export interface GameContextItemUse {
 export interface GameContextWorld {
     ground: TerrainField;
     groundHeightAt(x: number, z: number): number;
+    /**
+     * Static collision for world geometry that is not a scene object. `environment({ structures })`
+     * fills the `environment:structures` layer; `syncAuthoredSolids` fills one layer per studio object.
+     */
+    solids: WorldSolids;
 }
 export interface GameContextCards {
     /** Lazily creates (on first call, `config` required) or returns the existing notify-wrapped pile for `id`. */
@@ -420,14 +431,19 @@ export interface GameAudio {
     }): void;
     /**
      * Live-update retained loop `id` via `audio.loopSet`: `rate` re-pitches it (1 = authored pitch, clamped
-     * 0.25–4 by the shell), `gain` rescales volume (0–1), `at` repositions its emitter. Cheap to call every
-     * tick (~60 Hz) — the shell ramps rate/gain over ~20 ms to avoid zipper noise. A no-op when `id` is not a
-     * live loop (an update may race a stop) (#1051).
+     * 0.25–4 by the shell), `gain` rescales volume (0–1), `at` repositions its emitter. `lowpass`/`highpass`
+     * set filter cutoffs in Hz (muffle an engine off-throttle or behind a wall); `velocity` is the emitter's
+     * world velocity, which pitches the loop by doppler when its sound declares `doppler`. Cheap to call every
+     * tick (~60 Hz) — the shell ramps rate/gain/cutoffs over ~20 ms to avoid zipper noise. A no-op when `id`
+     * is not a live loop (an update may race a stop) (#1051).
      */
     setLoop(id: string, params: {
         rate?: number;
         gain?: number;
         at?: readonly [number, number, number];
+        velocity?: readonly [number, number, number];
+        lowpass?: number;
+        highpass?: number;
     }): void;
     /** Stop and dispose retained loop `id` (emits `audio.loopStop`); an unknown `id` is ignored (#1051). */
     stopLoop(id: string): void;

package/dist/runtime/gameRuntime.d.ts

@@ -1,5 +1,5 @@
 import type { SaveConfig } from "./save.js";
-import type { CommandDef, CommandScope } from "./commandRunner.js";
+import type { CommandAccess, CommandDef, CommandScope } from "./commandRunner.js";
 import { runCommand } from "./commandRunner.js";
 import { type GameRuntimeSnapshot, type RuntimeChunkRow, type RuntimePlayerRow, type RuntimeProfileRow, type RuntimeServerRow } from "./snapshot.js";
 export type ServerLoopHooks = {
@@ -69,6 +69,8 @@ export type GameRuntime = {
      * and nothing else. Missing scopes load only the actor and no chunks; `{}` explicitly requests all state.
      */
     commandScope: (commandName: string, input: unknown, actorUserId: string) => CommandScope | undefined;
+    /** Who may send a command, or `undefined` when the runtime has no command by that name. */
+    commandAccess: (commandName: string) => CommandAccess | undefined;
     /** What a join has to hydrate. `undefined` means the whole world, as when `onNewPlayer` is unscoped. */
     joinScope: (userId: string, isNew: boolean) => CommandScope | undefined;
     /** `nowMs` is the host wall clock at the start of the tick, in ms; defaults to `Date.now()`. */

package/dist/runtime/gameRuntime.js

@@ -38,6 +38,10 @@ export function createGameRuntime(definition) {
         commandScope(commandName, input, actorUserId) {
             return resolveCommandScope(definition.commands, commandName, input, actorUserId);
         },
+        commandAccess(commandName) {
+            const command = definition.commands[commandName];
+            return command === undefined ? undefined : (command.access ?? "client");
+        },
         joinScope(userId, isNew) {
             if (!loop?.onNewPlayer)
                 return { players: [userId], chunkKeys: [] };

package/dist/runtime/inputSnapshot.d.ts

@@ -1,5 +1,6 @@
 import type { PointerAxisState } from "../input/pointerAxis.js";
 import { type AxisBinding, type AxisRange } from "../input/axisInput.js";
+import { type HapticChannels } from "../input/haptics.js";
 /** One client's input for a tick — the semantic held-action set plus pointer state, the serializable, over-the-wire counterpart of {@link InputSnapshot} the host stores per connected player. */
 export interface InputFrame {
     held: readonly string[];
@@ -16,6 +17,11 @@ export interface InputSnapshot {
         weak: number;
         ms: number;
     }): Promise<boolean>;
+    /**
+     * Continuous rumble channels for a local user (`engine`, `road`, `impact`, …): set levels each tick
+     * and the shell mixes them by priority onto that user's pad. Local only — never in a snapshot or on the wire.
+     */
+    haptics(userId: string): HapticChannels;
     /** Replaces the held-action set for this frame, rolling the previous held set forward for edge detection (#671). Called by the shell before `onTick` each frame; does not bump `ctx.version()` or notify `ctx.subscribe` listeners — per-frame publishes would storm subscribers. */
     publish(held: readonly string[]): void;
     /** Replaces the normalized pointer-position state for this frame (#293). Same no-notify contract as `publish`. */

package/dist/runtime/inputSnapshot.js

@@ -1,10 +1,12 @@
 import { sampleAxisBindings } from "../input/axisInput.js";
+import { createHapticChannels } from "../input/haptics.js";
 export function createInputSnapshot() {
     let heldSet = new Set();
     let previousHeldSet = new Set();
     let heldList = [];
     let pointerState = null;
     let analogValues = null;
+    const haptics = new Map();
     const value = (action) => {
         const analog = analogValues?.[action];
         if (analog !== undefined)
@@ -13,6 +15,14 @@ export function createInputSnapshot() {
     };
     return {
         rumble: async () => false,
+        haptics(userId) {
+            let channels = haptics.get(userId);
+            if (channels === undefined) {
+                channels = createHapticChannels();
+                haptics.set(userId, channels);
+            }
+            return channels;
+        },
         publish(held) {
             previousHeldSet = heldSet;
             heldList = Object.freeze([...held]);

package/dist/runtime/localPlayers.d.ts

@@ -0,0 +1,73 @@
+import type { GameContext } from "./gameContext.js";
+import { type InputSnapshot } from "./inputSnapshot.js";
+/** One local seat on a shared screen: a stable slot id, the user id the game spawns for it, and the device driving it. */
+export interface LocalPlayerSlot {
+    readonly slotId: string;
+    readonly index: number;
+    readonly userId: string;
+    /** Device that claimed the seat (`"gamepad:1"`), `null` for the primary seat before a device claims it. */
+    readonly deviceId: string | null;
+}
+/** Retunable seat policy. */
+export interface LocalPlayersConfig {
+    /** Seats on this screen, including the primary (default `1`: every device drives the primary player). */
+    maxSlots: number;
+    /**
+     * Whether the first device to press something claims the primary seat alongside keyboard and touch
+     * (`"first"`, default), or the primary stays keyboard/touch-only and every pad opens a new seat (`"none"`).
+     */
+    claimPrimary?: "first" | "none";
+}
+/** Options for {@link createLocalPlayers}. */
+export interface LocalPlayersOptions extends LocalPlayersConfig {
+    /** User id of seat 0 — `ctx.player.userId`. */
+    primaryUserId: string;
+    /** Input of seat 0 — `ctx.input`; other seats get their own snapshot. */
+    primaryInput?: InputSnapshot;
+    /** User id for seat `index >= 1` (default `` `${primaryUserId}:p${index + 1}` ``). */
+    userIdFor?: (index: number) => string;
+}
+/** Result of {@link LocalPlayers.assign}. */
+export interface LocalPlayerAssignment {
+    slot: LocalPlayerSlot;
+    /** True when this call opened the seat: spawn its entity through `onNewPlayer`. */
+    joined: boolean;
+}
+/** Serializable seat table. */
+export interface LocalPlayersSnapshot {
+    maxSlots: number;
+    claimPrimary: "first" | "none";
+    slots: LocalPlayerSlot[];
+}
+/** Seats for couch co-op: devices hot-join into slots, each slot has its own input. */
+export interface LocalPlayers {
+    /** Seat for a device that just produced input: its existing seat, the primary seat, a newly opened seat, or `null` when full. */
+    assign(deviceId: string): LocalPlayerAssignment | null;
+    /** Free a seat other than the primary; its device may hot-join again. */
+    release(slotId: string): boolean;
+    slots(): readonly LocalPlayerSlot[];
+    slot(slotId: string): LocalPlayerSlot | null;
+    slotForDevice(deviceId: string): LocalPlayerSlot | null;
+    /** The seat's user id and input, or `null` for an unknown seat. Seat 0 returns `ctx.player`'s id and `ctx.input`. */
+    local(slotId: string): {
+        userId: string;
+        input: InputSnapshot;
+    } | null;
+    /** Called after every assign that changes the table, release, restore and retune; returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    config(): Required<LocalPlayersConfig>;
+    /** Change seat count or claim policy mid-game; seats above a lowered `maxSlots` stay until released. */
+    retune(next: LocalPlayersConfig): void;
+    snapshot(): LocalPlayersSnapshot;
+    restore(snapshot: LocalPlayersSnapshot): void;
+}
+/**
+ * Seat table for local multiplayer on one screen.
+ * @capability local-players Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+ */
+export declare function createLocalPlayers(options: LocalPlayersOptions): LocalPlayers;
+/**
+ * The seat table of a game context, created on first use with one seat for `ctx.player` and `ctx.input`.
+ * The shell retunes it from `defineGame({ localPlayers })` and hot-joins pads into it.
+ */
+export declare function localPlayers(ctx: GameContext): LocalPlayers;

package/dist/runtime/localPlayers.js

@@ -0,0 +1,119 @@
+import { createInputSnapshot } from "./inputSnapshot.js";
+const PRIMARY_SLOT = "slot:0";
+/**
+ * Seat table for local multiplayer on one screen.
+ * @capability local-players Couch co-op seats: devices hot-join into slots, each with its own user id and input snapshot.
+ */
+export function createLocalPlayers(options) {
+    const userIdFor = options.userIdFor ?? ((index) => `${options.primaryUserId}:p${index + 1}`);
+    const primaryInput = options.primaryInput ?? createInputSnapshot();
+    let config = {
+        maxSlots: Math.max(1, Math.floor(options.maxSlots)),
+        claimPrimary: options.claimPrimary ?? "first",
+    };
+    let slots = [];
+    const inputs = new Map();
+    const listeners = new Set();
+    const changed = () => {
+        for (const listener of [...listeners])
+            listener();
+    };
+    const primarySlot = (deviceId) => Object.freeze({ slotId: PRIMARY_SLOT, index: 0, userId: options.primaryUserId, deviceId });
+    const reset = (next) => {
+        slots = next.map((slot) => Object.freeze({ ...slot }));
+        if (!slots.some((slot) => slot.index === 0))
+            slots.unshift(primarySlot(null));
+        slots.sort((a, b) => a.index - b.index);
+        for (const slotId of [...inputs.keys()]) {
+            if (!slots.some((slot) => slot.slotId === slotId))
+                inputs.delete(slotId);
+        }
+    };
+    reset([]);
+    const inputFor = (slot) => {
+        if (slot.index === 0)
+            return primaryInput;
+        let input = inputs.get(slot.slotId);
+        if (input === undefined) {
+            input = createInputSnapshot();
+            inputs.set(slot.slotId, input);
+        }
+        return input;
+    };
+    return {
+        assign(deviceId) {
+            const existing = slots.find((slot) => slot.deviceId === deviceId);
+            if (existing !== undefined)
+                return { slot: existing, joined: false };
+            if (config.claimPrimary === "first" || config.maxSlots === 1) {
+                const primary = slots[0];
+                if (primary.deviceId === null) {
+                    slots[0] = primarySlot(deviceId);
+                    changed();
+                    return { slot: slots[0], joined: false };
+                }
+                if (config.maxSlots === 1)
+                    return { slot: primary, joined: false };
+            }
+            if (slots.length >= config.maxSlots)
+                return null;
+            let index = 1;
+            while (slots.some((slot) => slot.index === index))
+                index += 1;
+            const slot = Object.freeze({ slotId: `slot:${index}`, index, userId: userIdFor(index), deviceId });
+            slots = [...slots, slot].sort((a, b) => a.index - b.index);
+            changed();
+            return { slot, joined: true };
+        },
+        release(slotId) {
+            if (slotId === PRIMARY_SLOT)
+                return false;
+            const next = slots.filter((slot) => slot.slotId !== slotId);
+            if (next.length === slots.length)
+                return false;
+            slots = next;
+            inputs.delete(slotId);
+            changed();
+            return true;
+        },
+        slots: () => slots,
+        slot: (slotId) => slots.find((slot) => slot.slotId === slotId) ?? null,
+        slotForDevice: (deviceId) => slots.find((slot) => slot.deviceId === deviceId) ?? null,
+        local(slotId) {
+            const slot = slots.find((candidate) => candidate.slotId === slotId);
+            return slot === undefined ? null : { userId: slot.userId, input: inputFor(slot) };
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        config: () => config,
+        retune(next) {
+            config = { maxSlots: Math.max(1, Math.floor(next.maxSlots)), claimPrimary: next.claimPrimary ?? config.claimPrimary };
+            changed();
+        },
+        snapshot() {
+            return { ...config, slots: slots.map((slot) => ({ ...slot })) };
+        },
+        restore(snapshot) {
+            config = { maxSlots: Math.max(1, Math.floor(snapshot.maxSlots)), claimPrimary: snapshot.claimPrimary };
+            reset(snapshot.slots);
+            changed();
+        },
+    };
+}
+const LOCAL_PLAYERS = new WeakMap();
+/**
+ * The seat table of a game context, created on first use with one seat for `ctx.player` and `ctx.input`.
+ * The shell retunes it from `defineGame({ localPlayers })` and hot-joins pads into it.
+ */
+export function localPlayers(ctx) {
+    let players = LOCAL_PLAYERS.get(ctx);
+    if (players === undefined) {
+        players = createLocalPlayers({ maxSlots: 1, primaryUserId: ctx.player.userId, primaryInput: ctx.input });
+        LOCAL_PLAYERS.set(ctx, players);
+    }
+    return players;
+}

package/dist/runtime/transport.d.ts

@@ -63,16 +63,25 @@ export type GameRuntimeFeedView = {
     entries: unknown[];
 };
 export type GameRuntimeTransport = {
+    /**
+     * Join a server. `sessionId` names this client session (one tab, one mounted view) so the host keeps
+     * the user a member while any of their sessions is still live.
+     */
     joinServer: (args: {
         gameId: string;
         serverId?: string;
         role?: MultiplayerRole;
+        sessionId?: string;
     }) => Promise<JoinServerOutcome>;
+    /** Leave a server. With `sessionId` only that session ends; the user leaves once no session remains. Without it the user leaves outright. */
     leaveServer: (args: {
         serverId: string;
+        sessionId?: string;
     }) => Promise<void>;
     runCommand: (args: RunCommandArgs) => Promise<TransportRunCommandResult>;
 };
+/** Fresh id for one client session's join/leave pair (see {@link GameRuntimeTransport.joinServer}). */
+export declare function createTransportSessionId(): string;
 export type FeedUnsubscribe = () => void;
 export type GameRuntimeFeeds = {
     subscribeServer: (serverId: string, onChange: (view: GameRuntimeServerView | null) => void) => FeedUnsubscribe;

package/dist/runtime/transport.js

@@ -1 +1,7 @@
-export {};
+/** Fresh id for one client session's join/leave pair (see {@link GameRuntimeTransport.joinServer}). */
+export function createTransportSessionId() {
+    const cryptoApi = globalThis.crypto;
+    if (cryptoApi?.randomUUID)
+        return cryptoApi.randomUUID();
+    return `s-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}

package/dist/scene/behaviorRuntime.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
+import type { Blackboard, DecisionAbort, DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
 import { type InterestGateState } from "../ai/interestScheduler.js";
 import { type PathFollowState, type PathProgress, type Waypoint } from "../nav/pathFollow.js";
 import type { GameContext } from "../runtime/gameContext.js";
@@ -13,10 +13,15 @@ export interface BehaviorActionContext {
 }
 /** Callback used by a registered decision graph behavior action. */
 export type BehaviorAction = DecisionAction<BehaviorActionContext>;
+/** Optional hooks for a registered behavior action set. */
+export interface BehaviorActionOptions {
+    /** Called when an action running last think is pre-empted by another branch, to stop movement or release claims. */
+    onAbort?: DecisionAbort<BehaviorActionContext>;
+}
 /** Register the named actions used by decision graph behavior descriptors.
  * @capability behavior-actions register named callbacks for decision graph behavior descriptors
  */
-export declare function registerBehaviorActions(id: string, actions: Record<string, BehaviorAction>): () => void;
+export declare function registerBehaviorActions(id: string, actions: Record<string, BehaviorAction>, options?: BehaviorActionOptions): () => void;
 /**
  * Catch-up policy applied when a paused instance resumes. `freeze` (default, deterministic) discards
  * the time spent paused; `advance` silently fast-forwards the instance by the paused duration without
@@ -36,6 +41,9 @@ export type BehaviorSnapshot = {
     readonly kind: "decisionGraph";
     readonly graph: ReturnType<DecisionGraphRuntime["snapshot"]>;
     readonly gate: InterestGateState;
+    readonly blackboard?: Blackboard;
+    /** Seconds accrued since the last think. */
+    readonly pending?: number;
 };
 /** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
 export interface BehaviorInspection {
@@ -72,6 +80,8 @@ export interface BehaviorControl {
     inspect(id: string): BehaviorInspection | null;
     /** Inspect every live instance (bounded by spawned behavior entities). */
     list(): BehaviorInspection[];
+    /** The live, persistent blackboard of a decision graph instance for perception and game systems to write facts into, or `null`. */
+    blackboard(id: string): Blackboard | null;
 }
 /**
  * Advance every spawned entity carrying a `patrol` or `wander` {@link BehaviorDescriptor} one tick — the

package/dist/scene/behaviorRuntime.js

@@ -11,14 +11,17 @@ const behaviorActions = new Map();
 /** Register the named actions used by decision graph behavior descriptors.
  * @capability behavior-actions register named callbacks for decision graph behavior descriptors
  */
-export function registerBehaviorActions(id, actions) {
-    behaviorActions.set(id, actions);
+export function registerBehaviorActions(id, actions, options = {}) {
+    const entry = { actions, options };
+    behaviorActions.set(id, entry);
     return () => {
-        if (behaviorActions.get(id) === actions)
+        if (behaviorActions.get(id) === entry)
             behaviorActions.delete(id);
     };
 }
-const DECISION_GRAPH_CADENCE = { wakeRadius: Number.POSITIVE_INFINITY, activeInterval: 0 };
+function thinkCadence(behavior) {
+    return { wakeRadius: Number.POSITIVE_INFINITY, activeInterval: Math.max(0, behavior.thinkInterval ?? 0) };
+}
 function patrolOf(entity) {
     return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
 }
@@ -66,14 +69,21 @@ const runtimeOf = perContext((ctx) => {
             }
             const decisionGraph = decisionGraphOf(entity);
             if (decisionGraph !== null) {
-                const actions = behaviorActions.get(decisionGraph.actions);
-                if (actions === undefined)
+                const registered = behaviorActions.get(decisionGraph.actions);
+                if (registered === undefined)
                     continue;
+                const cadence = thinkCadence(decisionGraph);
                 nav.set(entity.id, {
                     kind: "decisionGraph",
                     behavior: decisionGraph,
-                    runtime: createDecisionGraphRuntime(decisionGraph.graph, actions),
-                    gate: createInterestGateState(DECISION_GRAPH_CADENCE, ctx.rng()),
+                    runtime: createDecisionGraphRuntime(decisionGraph.graph, registered.actions, {
+                        rng: () => ctx.rng(),
+                        ...(registered.options.onAbort === undefined ? {} : { onAbort: registered.options.onAbort }),
+                    }),
+                    gate: createInterestGateState(cadence, ctx.rng()),
+                    cadence,
+                    blackboard: { ...(decisionGraph.blackboard ?? {}) },
+                    pending: 0,
                     status: "active",
                     reason: null,
                     pausedElapsed: 0,
@@ -174,13 +184,13 @@ export function advanceBehaviors(ctx, dt) {
             const entity = ctx.scene.entity.get(id);
             if (entity === null)
                 continue;
-            const step = advanceInterestGate(entry.gate, DECISION_GRAPH_CADENCE, dt, { proximity: 0 });
+            entry.pending += dt;
+            const step = advanceInterestGate(entry.gate, entry.cadence, dt, { proximity: 0 });
             if (!step.active)
                 continue;
-            const blackboard = {};
-            const status = entry.runtime.tick({ ctx, entityId: id, dt }, blackboard, dt);
-            if (status === "done" || status === "failed")
-                entry.runtime.restore({ runningPath: null });
+            const elapsed = entry.pending;
+            entry.pending = 0;
+            entry.runtime.tick({ ctx, entityId: id, dt: elapsed }, entry.blackboard, elapsed);
         }
     }
 }
@@ -252,7 +262,7 @@ export function behaviorControl(ctx) {
                 return { kind: "patrol", state: { ...entry.state } };
             if (entry.kind === "wander")
                 return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
-            return { kind: "decisionGraph", graph: entry.runtime.snapshot(), gate: { ...entry.gate } };
+            return { kind: "decisionGraph", graph: entry.runtime.snapshot(), gate: { ...entry.gate }, blackboard: { ...entry.blackboard }, pending: entry.pending };
         },
         restore: (id, snapshot) => {
             const entry = nav.get(id);
@@ -265,6 +275,8 @@ export function behaviorControl(ctx) {
             if (entry.kind === "decisionGraph" && snapshot.kind === "decisionGraph") {
                 entry.runtime.restore(snapshot.graph);
                 entry.gate = { ...snapshot.gate };
+                entry.blackboard = { ...(snapshot.blackboard ?? entry.behavior.blackboard ?? {}) };
+                entry.pending = snapshot.pending ?? 0;
                 return true;
             }
             if (entry.kind === "wander" && snapshot.kind === "wander") {
@@ -286,5 +298,9 @@ export function behaviorControl(ctx) {
                 out.push({ id, kind: entry.kind, status: entry.status, reason: entry.reason });
             return out;
         },
+        blackboard: (id) => {
+            const entry = nav.get(id);
+            return entry?.kind === "decisionGraph" ? entry.blackboard : null;
+        },
     };
 }

package/dist/scene/behaviors.d.ts

@@ -1,6 +1,6 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
 import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
-import type { DecisionGraph } from "../ai/decisionGraph.js";
+import type { Blackboard, DecisionGraph } from "../ai/decisionGraph.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -33,6 +33,10 @@ export interface DecisionGraphBehavior {
     kind: "decisionGraph";
     graph: DecisionGraph;
     actions: string;
+    /** Initial facts for this entity's persistent blackboard; systems write more through `behaviorControl(ctx).blackboard(id)`. */
+    blackboard?: Blackboard;
+    /** Seconds between graph ticks (`0` = every frame). Siblings are staggered; actions receive the elapsed time. */
+    thinkInterval?: number;
 }
 export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior | DecisionGraphBehavior;
 export declare function wander({ radius }: {

package/dist/scene/sceneKinds.d.ts

@@ -5,6 +5,7 @@
  * party ship a new authorable "studio" (pole line, water, bookcase) — schema + resolver here, a
  * matching renderer in `shell` — without editing editor or engine files. Scatter is the proof adopter.
  */
+import type { WorldSolid } from "../world/worldSolids.js";
 /** Which document collection a scene kind lives in. Drives placement + which `meta` bag holds params. */
 export type SceneKindTarget = "path" | "marker" | "volume";
 /** A closed-polygon area vs an open polyline, for path-target kinds. Ignored for marker/volume kinds. */
@@ -212,6 +213,12 @@ export interface SceneKindDefinition<TResolved = unknown> {
      * marker/volume/path; `params` is `parseParams(schema, object.meta)`.
      */
     resolve?: (object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => TResolved;
+    /**
+     * World-space collision for a resolved object. Omitted, the kind is render-only. `syncAuthoredSolids`
+     * (`world/authoredSolids`) writes these into `ctx.world.solids`, so movement, NPCs, physics
+     * backends and nav grids all collide with what the studio draws.
+     */
+    solids?: (resolved: TResolved, object: SceneKindObject, params: ParsedParams, context: SceneKindResolveContext) => readonly WorldSolid[];
     /** Optional one-line readout under the inspector fields (estimate, dimensions) — owned by the studio. */
     note?: (object: SceneKindObject, params: ParsedParams) => string;
     /**
@@ -258,6 +265,8 @@ export interface SceneKindObject {
 export interface SceneKindResolveContext {
     sampleHeight?: (x: number, z: number) => number;
     sampleNormal?: (x: number, z: number) => readonly [number, number, number];
+    /** Every studio object in the same document, for kinds that read siblings (a `city` reads its `cityzone` volumes). */
+    objects?: readonly SceneKindObject[];
 }
 /**
  * Register a scene kind — the plug-in point for a new parametric studio. Idempotent per `kind` (last

package/dist/scene/vehicleSeat.d.ts

@@ -64,5 +64,9 @@ export declare class VehicleSeats {
     driverOf(vehicleId: string): string | null;
     get mounts(): MountController;
 }
-/** Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy. */
+/**
+ * Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy.
+ *
+ * @capability vehicle-seats enter, exit and swap seats in a car or mount (GTA-style boarding) with driver and passenger slots
+ */
 export declare function createVehicleSeats(controller?: MountController): VehicleSeats;

package/dist/scene/vehicleSeat.js

@@ -53,7 +53,11 @@ export class VehicleSeats {
         return this.controller;
     }
 }
-/** Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy. */
+/**
+ * Builds a {@link VehicleSeats}, optionally over an existing `MountController` to share its occupancy.
+ *
+ * @capability vehicle-seats enter, exit and swap seats in a car or mount (GTA-style boarding) with driver and passenger slots
+ */
 export function createVehicleSeats(controller) {
     return new VehicleSeats(controller);
 }

package/dist/sensor/concealment.d.ts

@@ -14,9 +14,15 @@ export interface ConcealmentSample {
     concealed: boolean;
     dwellSeconds: number;
 }
+/** Plain JSON state of a {@link ConcealmentSensor}: seconds each target has stayed concealed. */
+export interface ConcealmentSensorState {
+    dwell: Record<string, number>;
+}
 export interface ConcealmentSensor {
     tick(targets: readonly ConcealmentTarget[], dt: number): ConcealmentSample[];
     reset(id?: string): void;
+    snapshot(): ConcealmentSensorState;
+    restore(next: ConcealmentSensorState): void;
 }
 /** @internal */
 export declare function createConcealmentSensor(config?: {

package/dist/sensor/concealment.js

@@ -62,5 +62,13 @@ export function createConcealmentSensor(config) {
             else
                 dwell.delete(id);
         },
+        snapshot() {
+            return { dwell: Object.fromEntries(dwell) };
+        },
+        restore(next) {
+            dwell.clear();
+            for (const [id, seconds] of Object.entries(next.dwell))
+                dwell.set(id, seconds);
+        },
     };
 }