@jgengine/core 0.18.1 → 0.19.0

package/dist/physics/worldColliders.d.ts

@@ -7,7 +7,7 @@ export interface WorldColliderSync {
     /** Remove all bodies owned by this synchronizer and stop reacting to scene changes. */
     dispose(): void;
 }
-/** Mirrors static scene-object physical colliders and the context's ground field into a physics backend.
+/** Mirrors static scene-object physical colliders, `ctx.world.solids` and the context's ground field into a physics backend.
  * @capability world-physics-colliders Synchronize terrain and authored static colliders with a physics backend.
  */
 export declare function syncWorldColliders(backend: PhysicsBackend, ctx: GameContext): WorldColliderSync;

package/dist/physics/worldColliders.js

@@ -10,11 +10,13 @@ function bodyShape(shape) {
 function bodyPosition(shape, position, rotationY) {
     return colliderWorldCenter({ name: "body", purpose: "physical", shape, damageEligible: false, blocks: true }, position, rotationY);
 }
-/** Mirrors static scene-object physical colliders and the context's ground field into a physics backend.
+/** Mirrors static scene-object physical colliders, `ctx.world.solids` and the context's ground field into a physics backend.
  * @capability world-physics-colliders Synchronize terrain and authored static colliders with a physics backend.
  */
 export function syncWorldColliders(backend, ctx) {
     const objectBodies = new Map();
+    const solidBodies = [];
+    let solidsVersion = -1;
     let terrainBody = null;
     let disposed = false;
     function rebuildTerrain() {
@@ -62,10 +64,32 @@ export function syncWorldColliders(backend, ctx) {
         });
         objectBodies.set(objectId, handle);
     }
+    function syncSolids() {
+        const solids = ctx.world.solids;
+        if (solids.version() === solidsVersion)
+            return;
+        solidsVersion = solids.version();
+        for (const handle of solidBodies)
+            backend.removeBody(handle);
+        solidBodies.length = 0;
+        for (const layer of solids.layers()) {
+            for (const solid of solids.layer(layer)) {
+                const yaw = solid.rotationY ?? 0;
+                solidBodies.push(backend.addBody({
+                    shape: { kind: "box", halfExtents: [solid.halfExtents[0], solid.halfExtents[1], solid.halfExtents[2]] },
+                    position: [solid.center[0], solid.center[1], solid.center[2]],
+                    rotation: [0, Math.sin(yaw / 2), 0, Math.cos(yaw / 2)],
+                    kind: "static",
+                    userData: { kind: "solid", layer },
+                }));
+            }
+        }
+    }
     function sync() {
         if (disposed)
             return;
         rebuildTerrain();
+        syncSolids();
         const ids = new Set(ctx.scene.object.ids());
         for (const [objectId, handle] of objectBodies) {
             if (!ids.has(objectId)) {
@@ -76,7 +100,11 @@ export function syncWorldColliders(backend, ctx) {
         for (const objectId of ids)
             syncObject(objectId);
     }
-    const unsubscribe = ctx.scene.object.subscribe(sync);
+    const unsubscribeObjects = ctx.scene.object.subscribe(sync);
+    const unsubscribeSolids = ctx.world.solids.subscribe(() => {
+        if (!disposed)
+            syncSolids();
+    });
     sync();
     return {
         sync,
@@ -84,7 +112,11 @@ export function syncWorldColliders(backend, ctx) {
             if (disposed)
                 return;
             disposed = true;
-            unsubscribe();
+            unsubscribeObjects();
+            unsubscribeSolids();
+            for (const handle of solidBodies)
+                backend.removeBody(handle);
+            solidBodies.length = 0;
             if (terrainBody !== null)
                 backend.removeBody(terrainBody);
             terrainBody = null;

package/dist/puzzle/cellGrid.d.ts

@@ -1,8 +1,10 @@
+/** A fixed-size 2D board of cells, row-major from the top-left; `null` is an empty cell. Plain data, so it serializes and restores as-is. */
 export interface CellGrid<T> {
     readonly width: number;
     readonly height: number;
     readonly cells: readonly (T | null)[];
 }
+/** A straight line of matching cells found by {@link findRuns}. */
 export interface CellRun<T> {
     readonly value: T;
     readonly cells: readonly {
@@ -11,25 +13,29 @@ export interface CellRun<T> {
     }[];
     readonly direction: "row" | "column";
 }
-/** @internal */
+/**
+ * An empty `width` × `height` board. Every helper here returns a new grid, so a store slot can hold it
+ * and undo, replay, and save/restore work without copying.
+ * @capability cell-grid immutable 2D board of cells with row clears, gravity collapse, and match runs
+ */
 export declare function createCellGrid<T>(width: number, height: number): CellGrid<T>;
-/** @internal */
+/** Whether `(x, y)` lies on the board. */
 export declare function inGridBounds<T>(grid: CellGrid<T>, x: number, y: number): boolean;
-/** @internal */
+/** The value at `(x, y)`, or `null` when empty or off the board. */
 export declare function cellAt<T>(grid: CellGrid<T>, x: number, y: number): T | null;
-/** @internal */
+/** A copy with `(x, y)` set to `value`; off-board writes return the grid unchanged. */
 export declare function withCell<T>(grid: CellGrid<T>, x: number, y: number, value: T | null): CellGrid<T>;
-/** @internal */
+/** A copy with every in-bounds entry written; one allocation for a whole piece or stamp. */
 export declare function withCells<T>(grid: CellGrid<T>, entries: readonly {
     readonly x: number;
     readonly y: number;
     readonly value: T | null;
 }[]): CellGrid<T>;
-/** @internal */
+/** Indices of rows with no empty cell, top to bottom. */
 export declare function fullRows<T>(grid: CellGrid<T>): number[];
-/** @internal */
+/** A copy with `rows` removed and the rows above shifted down, refilling empty rows at the top. */
 export declare function clearRows<T>(grid: CellGrid<T>, rows: readonly number[]): CellGrid<T>;
-/** @internal */
+/** A copy where every column's cells fall to the bottom, keeping their order. */
 export declare function collapseColumns<T>(grid: CellGrid<T>): CellGrid<T>;
-/** @internal */
+/** Horizontal and vertical runs of at least `minLength` cells whose values `matches` (default `===`). */
 export declare function findRuns<T>(grid: CellGrid<T>, minLength: number, matches?: (a: T, b: T) => boolean): CellRun<T>[];

package/dist/puzzle/cellGrid.js

@@ -1,18 +1,22 @@
-/** @internal */
+/**
+ * An empty `width` × `height` board. Every helper here returns a new grid, so a store slot can hold it
+ * and undo, replay, and save/restore work without copying.
+ * @capability cell-grid immutable 2D board of cells with row clears, gravity collapse, and match runs
+ */
 export function createCellGrid(width, height) {
     return { width, height, cells: new Array(width * height).fill(null) };
 }
-/** @internal */
+/** Whether `(x, y)` lies on the board. */
 export function inGridBounds(grid, x, y) {
     return x >= 0 && x < grid.width && y >= 0 && y < grid.height;
 }
-/** @internal */
+/** The value at `(x, y)`, or `null` when empty or off the board. */
 export function cellAt(grid, x, y) {
     if (!inGridBounds(grid, x, y))
         return null;
     return grid.cells[y * grid.width + x] ?? null;
 }
-/** @internal */
+/** A copy with `(x, y)` set to `value`; off-board writes return the grid unchanged. */
 export function withCell(grid, x, y, value) {
     if (!inGridBounds(grid, x, y))
         return grid;
@@ -20,7 +24,7 @@ export function withCell(grid, x, y, value) {
     cells[y * grid.width + x] = value;
     return { width: grid.width, height: grid.height, cells };
 }
-/** @internal */
+/** A copy with every in-bounds entry written; one allocation for a whole piece or stamp. */
 export function withCells(grid, entries) {
     const cells = grid.cells.slice();
     for (const entry of entries) {
@@ -29,7 +33,7 @@ export function withCells(grid, entries) {
     }
     return { width: grid.width, height: grid.height, cells };
 }
-/** @internal */
+/** Indices of rows with no empty cell, top to bottom. */
 export function fullRows(grid) {
     const rows = [];
     for (let y = 0; y < grid.height; y += 1) {
@@ -45,7 +49,7 @@ export function fullRows(grid) {
     }
     return rows;
 }
-/** @internal */
+/** A copy with `rows` removed and the rows above shifted down, refilling empty rows at the top. */
 export function clearRows(grid, rows) {
     const removed = new Set(rows);
     const kept = [];
@@ -62,7 +66,7 @@ export function clearRows(grid, rows) {
         cells.push(...row);
     return { width: grid.width, height: grid.height, cells };
 }
-/** @internal */
+/** A copy where every column's cells fall to the bottom, keeping their order. */
 export function collapseColumns(grid) {
     const cells = grid.cells.slice();
     for (let x = 0; x < grid.width; x += 1) {
@@ -96,7 +100,7 @@ function scanRuns(length, cellAtIndex, minLength, matches) {
     }
     return runs;
 }
-/** @internal */
+/** Horizontal and vertical runs of at least `minLength` cells whose values `matches` (default `===`). */
 export function findRuns(grid, minLength, matches = (a, b) => a === b) {
     const runs = [];
     for (let y = 0; y < grid.height; y += 1) {

package/dist/render/lookPreset.d.ts

@@ -6,12 +6,15 @@ import type { PostProcessingConfig } from "./postProcessing.js";
  * `"neutral"` (the default when unset) keeps presentation unstyled; `"cinematic"` draws a scene lit like a shipped game — a real day sky
  * with a view-following shadow-casting sun + hemisphere fill, a network-free image-based-lighting
  * environment so PBR surfaces catch soft reflections, and a tuned tone-map/bloom/AO/vignette post
- * stack. `"flat"` opts out of the sky/IBL/post rig to the bare ambient+directional default (pre-#773).
+ * stack. `"comic"` adds ink outlines and cel bands over a saturated grade (Borderlands-style);
+ * `"retro"` pixelates and posterizes the frame. `"flat"` opts out of the sky/IBL/post rig to the bare ambient+directional default (pre-#773).
  * The upgraded default primitive materials — tuned roughness/metalness plus subtle procedural surface
  * detail so un-modeled boxes/capsules stop reading as flat plastic — apply under both presets.
  * @capability default-look one field that lights a scene like a shipped game (opt out with "flat")
  */
-export type LookPreset = "neutral" | "photoreal" | "toon" | "cinematic" | "flat";
+export type LookPreset = "neutral" | "photoreal" | "toon" | "comic" | "retro" | "cinematic" | "flat";
+/** Every look preset name, for pickers and validating a preset read from a URL or file. */
+export declare const LOOK_PRESETS: readonly LookPreset[];
 /** Explicit graphics knobs a game may set; the preset only fills the ones left undefined. */
 export interface GameLookInput {
     look?: LookPreset;
@@ -37,6 +40,10 @@ export declare const NEUTRAL_POST_PROCESSING: PostProcessingConfig;
 export declare const PHOTOREAL_POST_PROCESSING: PostProcessingConfig;
 /** Clean graphic presentation; toon materials remain game-owned while this sets the grade. */
 export declare const TOON_POST_PROCESSING: PostProcessingConfig;
+/** Ink outlines, four cel bands and a punchy grade — a hand-inked comic look on any model. */
+export declare const COMIC_POST_PROCESSING: PostProcessingConfig;
+/** Chunky pixels and posterized colour with no smoothing — a low-resolution retro look. */
+export declare const RETRO_POST_PROCESSING: PostProcessingConfig;
 /**
  * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
  * `"flat"` passes the explicit knobs through untouched.

package/dist/render/lookPreset.js

@@ -1,3 +1,5 @@
+/** Every look preset name, for pickers and validating a preset read from a URL or file. */
+export const LOOK_PRESETS = ["neutral", "photoreal", "cinematic", "toon", "comic", "retro", "flat"];
 /** A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill. */
 export const CINEMATIC_SKY = { preset: "day" };
 /** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
@@ -28,6 +30,32 @@ export const TOON_POST_PROCESSING = {
     ao: { intensity: 0.8, radius: 1.2 },
     grade: { saturation: 1.18, gamma: 1, vignette: 0, grain: 0 },
 };
+/** Ink outlines, four cel bands and a punchy grade — a hand-inked comic look on any model. */
+export const COMIC_POST_PROCESSING = {
+    toneMapping: "aces",
+    exposure: 1.05,
+    aa: "msaa",
+    bloom: { strength: 0.12, radius: 0.4, threshold: 1 },
+    ao: { intensity: 1, radius: 1.2 },
+    stylize: { outline: { thickness: 1.5 }, bands: 4 },
+    grade: { saturation: 1.3, gamma: 0.94, vignette: 0.15, grain: 0 },
+};
+/** Chunky pixels and posterized colour with no smoothing — a low-resolution retro look. */
+export const RETRO_POST_PROCESSING = {
+    toneMapping: "aces",
+    aa: false,
+    bloom: false,
+    ao: false,
+    stylize: { pixelSize: 3, bands: 6 },
+    grade: { saturation: 1.15, gamma: 1, vignette: 0, grain: 0 },
+};
+const PRESET_POST = {
+    photoreal: PHOTOREAL_POST_PROCESSING,
+    toon: TOON_POST_PROCESSING,
+    comic: COMIC_POST_PROCESSING,
+    retro: RETRO_POST_PROCESSING,
+    cinematic: CINEMATIC_POST_PROCESSING,
+};
 /**
  * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"neutral"`;
  * `"flat"` passes the explicit knobs through untouched.
@@ -48,7 +76,6 @@ export function resolveGameLook(input) {
     return {
         lighting: input.lighting,
         backdrop,
-        postProcessing: input.postProcessing ??
-            (look === "toon" ? TOON_POST_PROCESSING : look === "photoreal" ? PHOTOREAL_POST_PROCESSING : CINEMATIC_POST_PROCESSING),
+        postProcessing: input.postProcessing ?? PRESET_POST[look],
     };
 }

package/dist/render/postProcessing.d.ts

@@ -55,6 +55,34 @@ export interface DofConfig {
     /** Maximum blur radius, 0..1. Default 0.01. */
     maxBlur?: number;
 }
+/** Ink outlines traced from depth and surface-normal edges — silhouettes plus interior creases. */
+export interface OutlineConfig {
+    /** Line colour (CSS). Default near-black "#101014". */
+    color?: string;
+    /** Line thickness in render pixels. Default 1. */
+    thickness?: number;
+    /** Line opacity, 0..1. Default 1. */
+    opacity?: number;
+    /** Relative depth jump that counts as a silhouette edge. Lower draws more lines. Default 0.08. */
+    depthThreshold?: number;
+    /** Normal difference (1 − cos angle) that counts as a crease. Lower draws more lines. Default 0.35. */
+    normalThreshold?: number;
+    /** Distance in world units at which lines have faded out, so far scenery stays clean. Default 160. */
+    fadeDistance?: number;
+}
+/**
+ * Art-style stage that turns the same models and lighting into a different look without
+ * touching materials: ink outlines (comic / Borderlands), cel bands (cartoon), pixelation (retro).
+ * Runs after tone mapping, before the grade.
+ */
+export interface StylizeConfig {
+    /** Ink outlines. Omitted or `false` draws none. */
+    outline?: OutlineConfig | false;
+    /** Quantize brightness into this many cel-shading bands, keeping hue. 0 or omitted is off; 3–6 reads as cartoon. */
+    bands?: number;
+    /** Snap the frame to blocks of this many render pixels for a retro look. 0, 1 or omitted is off. */
+    pixelSize?: number;
+}
 /**
  * Edge antialiasing for the post chain. SMAA runs in linear-sRGB before the output
  * tone-map and cleans alpha-tested foliage/particles that MSAA samples alone leave crawling.
@@ -86,6 +114,8 @@ export interface PostProcessingConfig {
     /** Depth-of-field / bokeh. Heavier stage — omit or `false` to skip. Default off (omitted). */
     dof?: DofConfig | false;
     grade?: GradeConfig | false;
+    /** Art-style stage: outlines, cel bands, pixelation. Default off (omitted). */
+    stylize?: StylizeConfig | false;
 }
 /**
  * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film

package/dist/render/postProcessing.js

@@ -8,7 +8,7 @@ export const STUDIO_STAGE_POST = {
     toneMapping: "aces",
     exposure: 1.05,
     bloom: { strength: 0.28, radius: 0.6, threshold: 0.8 },
-    ao: { radius: 1.4, intensity: 2.2, distanceFalloff: 3, blend: 1 },
+    ao: { radius: 1.1, intensity: 1.5, distanceFalloff: 3, blend: 1 },
     grade: {
         lift: [0.008, 0.008, 0.014],
         gain: [1.05, 1.02, 0.98],

package/dist/runtime/cameraDirector.d.ts

@@ -1,6 +1,16 @@
-import type { ChaseCameraConfig, CinematicCameraConfig } from "../game/playableGame.js";
-/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), or a whole driving-feel overlay (speed→FOV, lead, bank, speed shake, drift-lag) applied only while a vehicle is piloted (#1299). */
-export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse">>;
+import type { ChaseCameraConfig, ChaseView, CinematicCameraConfig } from "../game/playableGame.js";
+/** Runtime patch over the static `camera.chase` config — distance/height/fov retuning from gameplay events (#286.11), a whole driving-feel overlay applied only while a vehicle is piloted (#1299), or a `view` switch between chase and seat cameras. */
+export type ChaseCameraTuning = Partial<Pick<ChaseCameraConfig, "distance" | "height" | "lookHeight" | "springDamping" | "fov" | "lead" | "bank" | "shakePerSpeed" | "velocityYaw" | "yawResponse" | "distanceBySpeed" | "pitchFollow" | "fovKick" | "lookBackAction" | "collision" | "view">>;
+/** Default order {@link nextChaseView} cycles through. */
+export declare const CHASE_VIEWS: readonly ChaseView[];
+/**
+ * The view after `current` in `views`, wrapping at the end; a view missing from the list starts the cycle over.
+ * Pair with `setChaseTuning` to bind a "change camera" key:
+ * `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })`.
+ *
+ * @capability chase-view-cycle cycle a vehicle camera between chase, hood and cockpit views at runtime
+ */
+export declare function nextChaseView(current: ChaseView, views?: readonly ChaseView[]): ChaseView;
 export interface CameraDirector {
     follow(entityId: string | null): void;
     /** `undefined` means no runtime override — the shell falls back to the static `playable.camera.followEntityId`. `null` means explicitly follow nothing. */
@@ -10,6 +20,10 @@ export interface CameraDirector {
     /** Overlay a runtime patch on the chase rig's config — a boss-intro pull-back, drift zoom-out; `null` restores the static config. */
     setChaseTuning(tuning: ChaseCameraTuning | null): void;
     chaseTuning(): ChaseCameraTuning | null;
+    /** Add a transient FOV impulse in degrees (a landing, a hit, a boost) that the chase rig layers on and decays per `camera.chase.fovKick`. Kicks from one frame sum. */
+    kickFov(degrees: number): void;
+    /** Drain the FOV impulses queued since the last call; the shell's chase rig calls this once per frame. */
+    takeFovKick(): number;
     subscribe(listener: () => void): () => void;
 }
 /** @internal */

package/dist/runtime/cameraDirector.js

@@ -1,9 +1,25 @@
+/** Default order {@link nextChaseView} cycles through. */
+export const CHASE_VIEWS = ["chase", "hood", "cockpit"];
+/**
+ * The view after `current` in `views`, wrapping at the end; a view missing from the list starts the cycle over.
+ * Pair with `setChaseTuning` to bind a "change camera" key:
+ * `ctx.camera.setChaseTuning({ ...ctx.camera.chaseTuning(), view: nextChaseView(view) })`.
+ *
+ * @capability chase-view-cycle cycle a vehicle camera between chase, hood and cockpit views at runtime
+ */
+export function nextChaseView(current, views = CHASE_VIEWS) {
+    if (views.length === 0)
+        return current;
+    const index = views.indexOf(current);
+    return views[(index + 1) % views.length];
+}
 /** @internal */
 export function createCameraDirector() {
     const listeners = new Set();
     let followEntity = undefined;
     let cinematicConfig = null;
     let chaseTuningPatch = null;
+    let pendingFovKick = 0;
     function notify() {
         for (const listener of listeners)
             listener();
@@ -24,6 +40,15 @@ export function createCameraDirector() {
             notify();
         },
         chaseTuning: () => chaseTuningPatch,
+        kickFov(degrees) {
+            if (Number.isFinite(degrees))
+                pendingFovKick += degrees;
+        },
+        takeFovKick() {
+            const kick = pendingFovKick;
+            pendingFovKick = 0;
+            return kick;
+        },
         subscribe(listener) {
             listeners.add(listener);
             return () => listeners.delete(listener);

package/dist/runtime/commandInput.d.ts

@@ -13,3 +13,40 @@ export declare function readQuantity(value: unknown, options?: {
     min?: number;
     max?: number;
 }): QuantityResult;
+/** Narrow an untrusted value to a plain object, rejecting arrays and null. */
+export declare function isInputRecord(value: unknown): value is Record<string, unknown>;
+/** Read a non-empty string of at most `maxLength` characters, or `null`. */
+export declare function readInputString(value: unknown, options?: {
+    maxLength?: number;
+}): string | null;
+/**
+ * Read a finite number inside `[min, max]`, or `null`. `NaN` and `±Infinity` are always rejected, so a
+ * coordinate can never drive an unbounded loop; `integer` also rejects fractions instead of flooring them.
+ * @capability command-number validate finite, bounded numbers and integers at command boundaries
+ */
+export declare function readInputNumber(value: unknown, options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}): number | null;
+/** Read one of a fixed set of values, or `null`. */
+export declare function readInputOneOf<const T extends string | number>(value: unknown, allowed: readonly T[]): T | null;
+/** Read an `{ x, y, z }` point whose axes are finite and within `maxAbs`, or `null`. */
+export declare function readInputPoint3(value: unknown, options?: {
+    maxAbs?: number;
+}): {
+    x: number;
+    y: number;
+    z: number;
+} | null;
+/** Read an `{ x, z }` ground point whose axes are finite and within `maxAbs`, or `null`. */
+export declare function readInputPoint2(value: unknown, options?: {
+    maxAbs?: number;
+}): {
+    x: number;
+    z: number;
+} | null;
+/** Read an array of at most `maxItems` entries, each accepted by `readItem`; any rejected entry rejects the whole array. */
+export declare function readInputArray<T>(value: unknown, readItem: (item: unknown) => T | null, options?: {
+    maxItems?: number;
+}): T[] | null;

package/dist/runtime/commandInput.js

@@ -11,3 +11,61 @@ export function readQuantity(value, options = {}) {
         ? { ok: true, quantity: value }
         : { ok: false, reason: "invalid-quantity" };
 }
+/** Narrow an untrusted value to a plain object, rejecting arrays and null. */
+export function isInputRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Read a non-empty string of at most `maxLength` characters, or `null`. */
+export function readInputString(value, options = {}) {
+    return typeof value === "string" && value.length > 0 && value.length <= (options.maxLength ?? 256) ? value : null;
+}
+/**
+ * Read a finite number inside `[min, max]`, or `null`. `NaN` and `±Infinity` are always rejected, so a
+ * coordinate can never drive an unbounded loop; `integer` also rejects fractions instead of flooring them.
+ * @capability command-number validate finite, bounded numbers and integers at command boundaries
+ */
+export function readInputNumber(value, options = {}) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    if (options.integer === true && !Number.isSafeInteger(value))
+        return null;
+    if (value < (options.min ?? -Number.MAX_VALUE) || value > (options.max ?? Number.MAX_VALUE))
+        return null;
+    return value;
+}
+/** Read one of a fixed set of values, or `null`. */
+export function readInputOneOf(value, allowed) {
+    return allowed.includes(value) ? value : null;
+}
+/** Read an `{ x, y, z }` point whose axes are finite and within `maxAbs`, or `null`. */
+export function readInputPoint3(value, options = {}) {
+    if (!isInputRecord(value))
+        return null;
+    const bound = { min: -(options.maxAbs ?? Number.MAX_VALUE), max: options.maxAbs ?? Number.MAX_VALUE };
+    const x = readInputNumber(value.x, bound);
+    const y = readInputNumber(value.y, bound);
+    const z = readInputNumber(value.z, bound);
+    return x === null || y === null || z === null ? null : { x, y, z };
+}
+/** Read an `{ x, z }` ground point whose axes are finite and within `maxAbs`, or `null`. */
+export function readInputPoint2(value, options = {}) {
+    if (!isInputRecord(value))
+        return null;
+    const bound = { min: -(options.maxAbs ?? Number.MAX_VALUE), max: options.maxAbs ?? Number.MAX_VALUE };
+    const x = readInputNumber(value.x, bound);
+    const z = readInputNumber(value.z, bound);
+    return x === null || z === null ? null : { x, z };
+}
+/** Read an array of at most `maxItems` entries, each accepted by `readItem`; any rejected entry rejects the whole array. */
+export function readInputArray(value, readItem, options = {}) {
+    if (!Array.isArray(value) || value.length > (options.maxItems ?? 256))
+        return null;
+    const items = [];
+    for (const entry of value) {
+        const item = readItem(entry);
+        if (item === null)
+            return null;
+        items.push(item);
+    }
+    return items;
+}

package/dist/runtime/commandRunner.d.ts

@@ -16,7 +16,26 @@ export type CommandScope = {
 export type CommandScopeDefinition = Omit<CommandScope, "players"> & {
     players?: readonly string[] | "actor";
 };
+/** Who may send a command: any client through the public transport, or only trusted host code. */
+export type CommandAccess = "client" | "server";
+/** Reason every host returns when a command's `parse` rejects its input. */
+export declare const MALFORMED_COMMAND_INPUT_REASON = "Malformed command input";
+/** Reason a public transport returns for a {@link CommandDef} marked `access: "server"`. */
+export declare const SERVER_ONLY_COMMAND_REASON = "Command is server-only";
 export type CommandDef<TInput = unknown> = {
+    /**
+     * `"server"` when `input` carries facts only the host may decide (unlock state, prices, multipliers):
+     * public transports then refuse it and only trusted host calls such as `helpers.runCommand` run it.
+     * Defaults to `"client"`, so every field of `input` must be validated as untrusted.
+     */
+    access?: CommandAccess;
+    /**
+     * Turns the untrusted wire value into the command's input, or `null` to refuse it with
+     * {@link MALFORMED_COMMAND_INPUT_REASON} before `scope`, `validate` or `apply` run. Those then only ever see
+     * parsed input, so a field checked here can't be skipped in one of them. Build it from the readers in
+     * `runtime/commandInput`; declare typed commands with {@link defineCommand}.
+     */
+    parse?: (input: unknown) => TInput | null;
     /**
      * What this command reads and writes, derived from its own input. A host that hydrates through a
      * scope loads only this slice instead of the whole world, and refuses the command if `apply` then
@@ -55,3 +74,11 @@ export type RunCommandResult = {
 };
 /** @internal */
 export declare function runCommand<TInput>(snapshot: import("./snapshot.js").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string, nowMs?: number): RunCommandResult;
+/**
+ * Declare a command with a typed input: `parse` narrows the wire value once, and `scope`, `validate` and
+ * `apply` receive the parsed type. Returns the untyped {@link CommandDef} a runtime's command table holds.
+ * @capability command-parse parse untrusted command input once so every command stage sees typed, bounded values
+ */
+export declare function defineCommand<TInput>(definition: CommandDef<TInput> & {
+    parse: (input: unknown) => TInput | null;
+}): CommandDef;

package/dist/runtime/commandRunner.js

@@ -1,10 +1,23 @@
+/** Reason every host returns when a command's `parse` rejects its input. */
+export const MALFORMED_COMMAND_INPUT_REASON = "Malformed command input";
+/** Reason a public transport returns for a {@link CommandDef} marked `access: "server"`. */
+export const SERVER_ONLY_COMMAND_REASON = "Command is server-only";
 /**
  * The resolved scope, defaulting to the actor and no chunks.
  * Evaluate it before hydration: the actor and the command's own input are both known by then.
  * @internal
  */
 export function resolveCommandScope(commands, commandName, input, actorUserId) {
-    const scope = commands[commandName]?.scope?.(input, actorUserId) ?? { players: "actor", chunkKeys: [] };
+    const command = commands[commandName];
+    let declared;
+    if (command?.parse === undefined) {
+        declared = command?.scope?.(input, actorUserId);
+    }
+    else {
+        const parsed = command.parse(input);
+        declared = parsed === null ? undefined : command.scope?.(parsed, actorUserId);
+    }
+    const scope = declared ?? { players: "actor", chunkKeys: [] };
     const { players, ...rest } = scope;
     return players === undefined ? rest : { ...rest, players: players === "actor" ? [actorUserId] : players };
 }
@@ -42,11 +55,18 @@ export function runCommand(snapshot, commands, commandName, input, actorUserId,
     if (!command) {
         return { ok: false, reason: `Unknown command: ${commandName}` };
     }
-    const validationError = command.validate(snapshot, input, actorUserId, nowMs);
+    let parsed = input;
+    if (command.parse !== undefined) {
+        const result = command.parse(input);
+        if (result === null)
+            return { ok: false, reason: MALFORMED_COMMAND_INPUT_REASON };
+        parsed = result;
+    }
+    const validationError = command.validate(snapshot, parsed, actorUserId, nowMs);
     if (validationError) {
         return { ok: false, reason: validationError.reason };
     }
-    const next = command.apply(snapshot, input, actorUserId, nowMs);
+    const next = command.apply(snapshot, parsed, actorUserId, nowMs);
     return {
         ok: true,
         snapshot: {
@@ -62,3 +82,11 @@ export function runCommand(snapshot, commands, commandName, input, actorUserId,
         },
     };
 }
+/**
+ * Declare a command with a typed input: `parse` narrows the wire value once, and `scope`, `validate` and
+ * `apply` receive the parsed type. Returns the untyped {@link CommandDef} a runtime's command table holds.
+ * @capability command-parse parse untrusted command input once so every command stage sees typed, bounded values
+ */
+export function defineCommand(definition) {
+    return definition;
+}

package/dist/runtime/context/combat.d.ts

@@ -36,6 +36,7 @@ export interface CombatSubsystemDeps {
     despawnEntity: (instanceId: string) => boolean;
     runCommand: (name: string, args: unknown) => void;
     localUserId: string;
+    rng: () => number;
     physics?: PhysicsConfig;
 }
 /** @internal Effects, projectiles, death, and combat presentation surface. */

package/dist/runtime/context/combat.js

@@ -8,7 +8,7 @@ import { createCombatFx } from "./combatFx.js";
 import { applyLethalLoot, isLocalPlayerKill } from "./deathLoot.js";
 /** @internal */
 export function createCombatSubsystem(d) {
-    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, localUserId, } = d;
+    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, localUserId, rng, } = d;
     const death = createDeathSystem({
         resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
         resolveIdentity(instanceId) {
@@ -64,6 +64,7 @@ export function createCombatSubsystem(d) {
                 spawnWorldItem,
                 grantToPlayer: loot.grantToPlayer,
                 localUserId,
+                rng,
             });
         },
     }), ["applyEffect"], signalNotify);

package/dist/runtime/context/deathLoot.d.ts

@@ -18,6 +18,8 @@ export interface LethalLootInput {
     spawnWorldItem: (input: WorldItemSpawnInput) => void;
     grantToPlayer: (userId: string, drops: Drop[], source?: string) => void;
     localUserId: string;
+    /** The world's seeded stream — scatter positions must replay with the rest of the simulation. */
+    rng: () => number;
 }
 /**
  * Pure death→loot policy: when a kill yields drops for the local player, either scatter them as