@jgengine/core 0.18.1 → 0.21.0

package/dist/editor/movementCatalog.js

@@ -0,0 +1,144 @@
+const FIELDS = [
+    { key: "walkSpeed", label: "Walk speed", group: "movement", min: 0, step: 0.1 },
+    { key: "gravity", label: "Gravity", group: "jump", step: 0.5 },
+    { key: "jumpVelocity", label: "Jump velocity", group: "jump", min: 0, step: 0.1 },
+    { key: "stepHeight", label: "Step height", group: "movement", min: 0, step: 0.05 },
+    { key: "collisionHeight", label: "Collision height", group: "movement", min: Number.MIN_VALUE, step: 0.1 },
+    { key: "maxClimbGrade", label: "Max climb grade", group: "movement", min: 0, step: 0.05 },
+    { key: "groundAcceleration", label: "Ground acceleration", group: "response", min: 0, step: 1 },
+    { key: "airAcceleration", label: "Air control", group: "response", min: 0, step: 1 },
+    { key: "groundFriction", label: "Braking", group: "response", min: 0, step: 1 },
+    { key: "runMultiplier", label: "Sprint multiplier", group: "movement", min: 0, step: 0.1 },
+    { key: "crouchMultiplier", label: "Crouch multiplier", group: "movement", min: 0, step: 0.05 },
+    { key: "jumpBufferMs", label: "Jump buffer (ms)", group: "jump-response", min: 0, step: 10 },
+    { key: "coyoteMs", label: "Coyote time (ms)", group: "jump-response", min: 0, step: 10 },
+    { key: "jumpCutFactor", label: "Jump release factor", group: "jump-response", min: 0, max: 1, step: 0.05 },
+    { key: "apexGravityScale", label: "Apex gravity multiplier", group: "jump-response", min: 0, step: 0.05 },
+    { key: "apexSpeed", label: "Apex speed threshold (m/s)", group: "jump-response", min: 0, step: 0.1 },
+    { key: "fallGravityScale", label: "Fall gravity multiplier", group: "jump-response", min: 0, step: 0.05 },
+    { key: "landingRecoveryMs", label: "Landing recovery (ms)", group: "jump-response", min: 0, step: 10 },
+    { key: "landingSpeedScale", label: "Landing speed multiplier", group: "jump-response", min: 0, step: 0.05 },
+];
+function validValue(field, value) {
+    return typeof value === "number" && Number.isFinite(value) && (!("min" in field) || value >= field.min) && (!("max" in field) || value <= field.max);
+}
+function numberRequirement(field) {
+    if (field.key === "jumpCutFactor")
+        return "finite number between 0 and 1";
+    return `finite${field.key === "collisionHeight" ? " positive" : "min" in field ? " nonnegative" : ""} number`;
+}
+/**
+ * Creates editor/RPC controls only for the values a game supplies, with those game's defaults.
+ * Gravity retains the game's sign convention; collision height is positive, other controls nonnegative.
+ * Jump release is bounded to 0..1; supplied deeper jump controls share a collapsed response group.
+ * @capability editor-movement author game-chosen character movement controls through ordinary catalog rows
+ */
+export function createMovementSchema(defaults) {
+    const fields = [];
+    for (const field of FIELDS) {
+        const value = defaults[field.key];
+        if (value === undefined)
+            continue;
+        if (!validValue(field, value))
+            throw new Error(`Invalid movement default ${field.key}: use a ${numberRequirement(field)}`);
+        fields.push({ ...field, type: "number", default: value });
+    }
+    return {
+        fields,
+        groups: [
+            { id: "movement", label: "Movement" },
+            { id: "jump", label: "Jump" },
+            { id: "response", label: "Response", collapsed: true },
+            { id: "jump-response", label: "Jump response", collapsed: true },
+        ].filter((group) => fields.some((field) => field.group === group.id)),
+    };
+}
+/**
+ * Reads one game-named row as partial runtime tuning, retaining game defaults for omitted or invalid
+ * values. Rejected values include their document path and repair; no policy callbacks are replaced.
+ * @capability editor-movement resolve saved movement controls without replacing a game's character rules
+ */
+export function readAuthoredMovement(document, catalogId, entryId) {
+    const catalogIndex = document.catalogs.findIndex((catalog) => catalog.id === catalogId);
+    const catalog = document.catalogs[catalogIndex];
+    const entryIndex = catalog?.entries.findIndex((entry) => entry.id === entryId) ?? -1;
+    const meta = catalog?.entries[entryIndex]?.meta;
+    const config = {};
+    const diagnostics = [];
+    if (meta === undefined)
+        return { config, diagnostics };
+    for (const field of FIELDS) {
+        const value = meta[field.key];
+        if (value === undefined)
+            continue;
+        if (!validValue(field, value)) {
+            diagnostics.push({
+                path: `catalogs[${catalogIndex}].entries[${entryIndex}].meta.${field.key}`,
+                message: `${field.key} must be a ${numberRequirement(field)}`,
+                repair: `Set ${field.key} to a valid number or remove it to inherit the game setting.`,
+            });
+            continue;
+        }
+        if (field.key === "walkSpeed")
+            config.walkSpeed = value;
+        else if (field.key === "gravity" || field.key === "jumpVelocity")
+            (config.physics ??= {})[field.key] = value;
+        else if (field.key === "stepHeight" || field.key === "collisionHeight" || field.key === "maxClimbGrade")
+            (config.movement ??= {})[field.key] = value;
+        else
+            ((config.movement ??= {}).feel ??= {})[field.key] = value;
+    }
+    return { config, diagnostics };
+}
+/**
+ * Memoizes movement resolution by immutable document identity; reads the latest document on every
+ * call while catalog lookup and diagnostics run only after authoring changes.
+ * @capability editor-movement consume live saved movement tuning with bounded per-frame work
+ */
+export function createAuthoredMovementReader(getDocument, catalogId, entryId) {
+    let previous;
+    let result;
+    return () => {
+        const document = getDocument();
+        if (document !== previous) {
+            result = readAuthoredMovement(document, catalogId, entryId);
+            previous = document;
+        }
+        return result;
+    };
+}
+/**
+ * Binds live authored numeric controls onto stable runtime objects, preserving the game's callbacks,
+ * collision, backend and other policy. The movement controller reads these getters each step.
+ * @capability editor-movement bind live character tuning while preserving distinctive game policy
+ */
+export function bindAuthoredMovement(read, defaults) {
+    let previous;
+    let previousBase;
+    let feel;
+    return {
+        movement: {
+            ...defaults.movement,
+            get stepHeight() { return read().config.movement?.stepHeight ?? defaults.movement?.stepHeight; },
+            get collisionHeight() { return read().config.movement?.collisionHeight ?? defaults.movement?.collisionHeight; },
+            get maxClimbGrade() { return read().config.movement?.maxClimbGrade ?? defaults.movement?.maxClimbGrade; },
+            get feel() {
+                const current = read();
+                const base = defaults.movement?.feel;
+                if (current !== previous || base !== previousBase) {
+                    const authored = current.config.movement?.feel;
+                    feel = authored === undefined ? base : { ...base, ...authored };
+                    previous = current;
+                    previousBase = base;
+                }
+                return feel;
+            },
+        },
+        physics: {
+            ...defaults.physics,
+            get gravity() { return read().config.physics?.gravity ?? defaults.physics?.gravity; },
+            get jumpVelocity() { return read().config.physics?.jumpVelocity ?? defaults.physics?.jumpVelocity; },
+        },
+        get diagnostics() { return read().diagnostics; },
+    };
+}

package/dist/editor/simulation.d.ts

@@ -0,0 +1,60 @@
+import { type ForceFieldConfig } from "../physics/forceVolume.js";
+import type { AuthoredWeatherConfig } from "../world/authoredWeather.js";
+import { type EmitterConfig } from "../vfx/particles.js";
+import { type ParticleAttachOptions } from "../vfx/particleDirector.js";
+import type { FireGridConfig } from "../world/weather.js";
+import type { FlockConfig } from "../ai/flock.js";
+import type { EditorDocument, EditorVec3 } from "./types.js";
+/** A named emitter authored in metres, with game-owned appearance and attachment ids. */
+export interface AuthoredEmitter {
+    id: string;
+    /** Spawn only while this authored fire area burns; live particles finish their lifetime. */
+    fireAreaId?: string;
+    position: EditorVec3;
+    config: EmitterConfig;
+    options?: ParticleAttachOptions;
+}
+/** A bounded fire grid; fuel and damage policy remain game content. */
+export interface AuthoredFireArea {
+    id: string;
+    /** Rain cooling in heat units/second at full exposure; zero disables automatic extinguishing. */
+    extinguishRate?: number;
+    position: EditorVec3;
+    config: Omit<FireGridConfig, "fuelAt" | "origin" | "wind">;
+    fuel?: readonly number[];
+    ignitions?: readonly {
+        col: number;
+        row: number;
+    }[];
+}
+/** An authored habitat selects a game species and optionally follows a document path. */
+export interface AuthoredFlockHabitat {
+    id: string;
+    species: string;
+    position: EditorVec3;
+    radius: number;
+    count: number;
+    seed: string | number;
+    role: "cosmetic" | "gameplay";
+    routeId?: string;
+    steering: FlockConfig;
+    /** Opt into authored wind/force acceleration; maxAcceleration is the game policy cap. */
+    /** Coupling in 1/second, bounded to 0..1e12. */
+    windResponse?: number;
+    /** Maximum acceleration in metres/second², bounded to 0..1e12. */
+    maxAcceleration?: number;
+    forceMask?: number;
+}
+/** Authored simulation inputs. Runtime particles, heat, accumulation and actors save separately. */
+export interface EditorSimulation {
+    weather?: AuthoredWeatherConfig;
+    /** Authoritative acceleration volumes; games select target masks and caps. */
+    forces?: readonly ForceFieldConfig[];
+    emitters?: readonly AuthoredEmitter[];
+    fires?: readonly AuthoredFireArea[];
+    habitats?: readonly AuthoredFlockHabitat[];
+}
+/** Decode authoring inputs with located diagnostics and bounded work before any document mutation.
+ * @capability validate-simulation diagnose authored weather, effect, fire, force and habitat documents before publication
+ */
+export declare function decodeEditorSimulation(value: unknown, document?: Pick<EditorDocument, "paths">): EditorSimulation;

package/dist/editor/simulation.js

@@ -0,0 +1,202 @@
+import { validateForceField } from "../physics/forceVolume.js";
+import { validateAuthoredWeather } from "../world/authoredWeather.js";
+import { validateEmitterConfig } from "../vfx/particles.js";
+import { validateParticleAttachOptions } from "../vfx/particleDirector.js";
+function object(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${path}: expected an object`);
+    return value;
+}
+function known(value, allowed, path) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            throw new Error(`${path}.${key}: unknown field`);
+}
+function finite(value, path, min = -Infinity, max = Infinity) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max)
+        throw new Error(`${path}: expected a finite number in ${min}..${max}`);
+    return value;
+}
+function text(value, path) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > 128)
+        throw new Error(`${path}: expected a nonempty string of at most 128 characters`);
+}
+function vector(value, path) {
+    const point = object(value, path);
+    for (const axis of ["x", "y", "z"])
+        finite(point[axis], `${path}.${axis}`);
+}
+function tuple(value, path) {
+    if (!Array.isArray(value) || value.length !== 3)
+        throw new Error(`${path}: expected [x,y,z]`);
+    value.forEach((component, index) => finite(component, `${path}[${index}]`));
+}
+function serializable(value, path, depth = 0) {
+    if (depth > 24)
+        throw new Error(`${path}: nesting exceeds 24 levels`);
+    if (value === null || typeof value === "string" || typeof value === "boolean" || value === undefined)
+        return;
+    if (typeof value === "number") {
+        finite(value, path);
+        return;
+    }
+    if (typeof value !== "object")
+        throw new Error(`${path}: expected serializable data`);
+    for (const [key, item] of Object.entries(value))
+        serializable(item, `${path}.${key}`, depth + 1);
+}
+function rows(value, path, limit, check) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value) || value.length > limit)
+        throw new Error(`${path}: expected at most ${limit} entries`);
+    const ids = new Set();
+    value.forEach((entry, index) => {
+        const location = `${path}[${index}]`;
+        const row = object(entry, location);
+        text(row.id, `${location}.id`);
+        if (ids.has(row.id))
+            throw new Error(`${location}.id: duplicate id ${row.id}`);
+        ids.add(row.id);
+        vector(row.position, `${location}.position`);
+        check(row, location);
+    });
+}
+/** Decode authoring inputs with located diagnostics and bounded work before any document mutation.
+ * @capability validate-simulation diagnose authored weather, effect, fire, force and habitat documents before publication
+ */
+export function decodeEditorSimulation(value, document) {
+    const source = object(value, "$.simulation");
+    known(source, ["weather", "forces", "emitters", "fires", "habitats"], "$.simulation");
+    serializable(source, "$.simulation");
+    if (source.weather !== undefined) {
+        object(source.weather, "$.simulation.weather");
+        try {
+            validateAuthoredWeather(source.weather);
+        }
+        catch (error) {
+            throw new Error(`$.simulation.weather: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (source.forces !== undefined) {
+        if (!Array.isArray(source.forces) || source.forces.length > 128)
+            throw new Error("$.simulation.forces: expected at most 128 fields");
+        source.forces.forEach((value, index) => {
+            try {
+                validateForceField(value);
+            }
+            catch (error) {
+                throw new Error(`$.simulation.forces[${index}]: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    rows(source.emitters, "$.simulation.emitters", 128, (row, path) => {
+        known(row, ["id", "position", "config", "options", "fireAreaId"], path);
+        if (row.fireAreaId !== undefined) {
+            text(row.fireAreaId, `${path}.fireAreaId`);
+            if (!Array.isArray(source.fires) || !source.fires.some((area) => area !== null && typeof area === "object" && area.id === row.fireAreaId))
+                throw new Error(`${path}.fireAreaId: missing fire area ${row.fireAreaId}`);
+        }
+        const diagnostics = validateEmitterConfig(row.config);
+        if (diagnostics.length)
+            throw new Error(`${path}.config: ${diagnostics.join("; ")}`);
+        if (row.options !== undefined) {
+            const errors = validateParticleAttachOptions(row.options);
+            if (errors.length)
+                throw new Error(`${path}.options: ${errors.join("; ")}`);
+        }
+        const config = object(row.config, `${path}.config`);
+        for (const key of ["max", "rate", "spread", "drag"])
+            if (config[key] !== undefined)
+                finite(config[key], `${path}.config.${key}`, 0, key === "max" ? 100_000 : key === "drag" ? 1 : Infinity);
+        if (config.max !== undefined && !Number.isInteger(config.max))
+            throw new Error(`${path}.config.max: expected an integer`);
+        for (const key of ["position", "spawnJitter", "direction", "gravity"])
+            if (config[key] !== undefined)
+                tuple(config[key], `${path}.config.${key}`);
+        for (const key of ["lifetime", "speed"])
+            if (config[key] !== undefined) {
+                const range = object(config[key], `${path}.config.${key}`);
+                finite(range.min, `${path}.config.${key}.min`, 0);
+                finite(range.max, `${path}.config.${key}.max`, range.min);
+            }
+        if (row.options !== undefined) {
+            const options = object(row.options, `${path}.options`);
+            if (options.space !== undefined && options.space !== "local" && options.space !== "world")
+                throw new Error(`${path}.options.space: expected local or world`);
+            if (options.active !== undefined && typeof options.active !== "boolean")
+                throw new Error(`${path}.options.active: expected boolean`);
+        }
+    });
+    rows(source.fires, "$.simulation.fires", 32, (row, path) => {
+        known(row, ["id", "position", "config", "fuel", "ignitions", "extinguishRate"], path);
+        if (row.extinguishRate !== undefined)
+            finite(row.extinguishRate, `${path}.extinguishRate`, 0);
+        const config = object(row.config, `${path}.config`);
+        known(config, ["cols", "rows", "cellSize", "ignitionThreshold", "spreadRate", "burnRate", "windBias", "maxCells"], `${path}.config`);
+        const cols = finite(config.cols, `${path}.config.cols`, 1, 256);
+        const count = cols * finite(config.rows, `${path}.config.rows`, 1, 256);
+        if (!Number.isInteger(cols) || !Number.isInteger(config.rows) || count > 16_384)
+            throw new Error(`${path}.config: expected integral dimensions with at most 16384 cells`);
+        finite(config.cellSize, `${path}.config.cellSize`, Number.EPSILON);
+        if (config.maxCells !== undefined) {
+            const capacity = finite(config.maxCells, `${path}.config.maxCells`, count, 1_048_576);
+            if (!Number.isInteger(capacity))
+                throw new Error(`${path}.config.maxCells: expected an integer`);
+        }
+        for (const key of ["ignitionThreshold", "spreadRate", "burnRate", "windBias"])
+            if (config[key] !== undefined)
+                finite(config[key], `${path}.config.${key}`, 0, key === "windBias" ? 1 : Infinity);
+        if (row.fuel !== undefined) {
+            if (!Array.isArray(row.fuel) || row.fuel.length !== count)
+                throw new Error(`${path}.fuel: expected ${count} cell values`);
+            row.fuel.forEach((fuel, index) => finite(fuel, `${path}.fuel[${index}]`, 0, 1));
+        }
+        if (row.ignitions !== undefined) {
+            if (!Array.isArray(row.ignitions) || row.ignitions.length > count)
+                throw new Error(`${path}.ignitions: expected at most ${count} cells`);
+            for (const cell of row.ignitions) {
+                const point = object(cell, `${path}.ignitions`);
+                known(point, ["col", "row"], `${path}.ignitions`);
+                finite(point.col, `${path}.ignitions.col`, 0, cols - 1);
+                finite(point.row, `${path}.ignitions.row`, 0, config.rows - 1);
+                if (!Number.isInteger(point.col) || !Number.isInteger(point.row))
+                    throw new Error(`${path}.ignitions: expected integral cell coordinates`);
+            }
+        }
+    });
+    rows(source.habitats, "$.simulation.habitats", 32, (row, path) => {
+        known(row, ["id", "species", "position", "radius", "count", "seed", "role", "routeId", "steering", "windResponse", "maxAcceleration", "forceMask"], path);
+        text(row.species, `${path}.species`);
+        finite(row.radius, `${path}.radius`, Number.EPSILON);
+        const count = finite(row.count, `${path}.count`, 0, 256);
+        if (!Number.isInteger(count))
+            throw new Error(`${path}.count: expected an integer`);
+        if (row.role !== "cosmetic" && row.role !== "gameplay")
+            throw new Error(`${path}.role: expected cosmetic or gameplay`);
+        if (typeof row.seed !== "string" && typeof row.seed !== "number")
+            throw new Error(`${path}.seed: expected string or number`);
+        if (typeof row.seed === "number")
+            finite(row.seed, `${path}.seed`);
+        for (const key of ["windResponse", "maxAcceleration"])
+            if (row[key] !== undefined)
+                finite(row[key], `${path}.${key}`, 0, 1e12);
+        if (row.forceMask !== undefined) {
+            finite(row.forceMask, `${path}.forceMask`, 0, 0xffffffff);
+            if (!Number.isInteger(row.forceMask))
+                throw new Error(`${path}.forceMask: expected a uint32`);
+        }
+        const steering = object(row.steering, `${path}.steering`);
+        known(steering, ["maxSpeed", "accel", "separationRadius", "separationWeight", "neighborRadius", "cohesionWeight", "alignmentWeight", "seekWeight", "stragglerRadius", "stragglerBoost"], `${path}.steering`);
+        for (const key of ["maxSpeed", "separationRadius", "neighborRadius"])
+            finite(steering[key], `${path}.steering.${key}`, Number.EPSILON);
+        for (const [key, item] of Object.entries(steering))
+            finite(item, `${path}.steering.${key}`, 0);
+        if (row.routeId !== undefined) {
+            text(row.routeId, `${path}.routeId`);
+            if (document !== undefined && !document.paths.some((route) => route.id === row.routeId && route.points.length > 1))
+                throw new Error(`${path}.routeId: missing route ${row.routeId} with at least two points`);
+        }
+    });
+    return structuredClone(source);
+}

package/dist/editor/staticPrefab.d.ts

@@ -0,0 +1,17 @@
+/** A solid or clearance volume in the prefab's unnormalized local asset space. */
+export interface StaticPrefabBox {
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}
+/** Persisted static export settings; source parts remain editable in the prefab fragment. */
+export interface StaticPrefabBake {
+    assetId: string;
+    /** Omit for a conservative closed exterior. Explicit boxes preserve authored openings. */
+    collisionBoxes?: readonly StaticPrefabBox[];
+    /** Required empty spaces, checked against movement solids before export. */
+    clearances?: readonly (StaticPrefabBox & {
+        id: string;
+    })[];
+}
+/** Validate and copy static prefab export settings from document or RPC input. */
+export declare function parseStaticPrefabBake(value: unknown): StaticPrefabBake;

package/dist/editor/staticPrefab.js

@@ -0,0 +1,51 @@
+/** Validate and copy static prefab export settings from document or RPC input. */
+export function parseStaticPrefabBake(value) {
+    const record = (input) => {
+        if (input === null || typeof input !== "object" || Array.isArray(input))
+            throw new Error("expected an object");
+        return input;
+    };
+    const input = record(value);
+    for (const key of Object.keys(input)) {
+        if (!["assetId", "collisionBoxes", "clearances"].includes(key))
+            throw new Error(`unknown static bake field: ${key}`);
+    }
+    if (typeof input.assetId !== "string" || input.assetId.trim().length === 0)
+        throw new Error("assetId: expected a nonempty string");
+    const boxes = (items, clearance) => {
+        if (!Array.isArray(items) || items.length === 0 || items.length > 4096)
+            throw new Error("expected 1..4096 boxes");
+        const ids = new Set();
+        return items.map((item, index) => {
+            const box = record(item);
+            for (const key of Object.keys(box)) {
+                if (!["min", "max", ...(clearance ? ["id"] : [])].includes(key))
+                    throw new Error(`box ${index}: unknown field ${key}`);
+            }
+            for (const key of ["min", "max"]) {
+                const vector = box[key];
+                if (!Array.isArray(vector) || vector.length !== 3 || !vector.every((axis) => typeof axis === "number" && Number.isFinite(axis)))
+                    throw new Error(`box ${index}.${key}: expected three finite numbers`);
+            }
+            const min = box.min;
+            const max = box.max;
+            if (!min.every((axis, i) => axis < max[i]))
+                throw new Error(`box ${index}: min must be less than max on every axis`);
+            if (clearance) {
+                if (typeof box.id !== "string" || box.id.trim().length === 0 || ids.has(box.id))
+                    throw new Error(`clearance ${index}: expected a unique nonempty id`);
+                ids.add(box.id);
+            }
+            return { min: [...min], max: [...max], ...(clearance ? { id: box.id } : {}) };
+        });
+    };
+    const collisionBoxes = input.collisionBoxes === undefined ? undefined : boxes(input.collisionBoxes, false);
+    const clearances = input.clearances === undefined ? undefined : boxes(input.clearances, true);
+    if (clearances !== undefined && collisionBoxes === undefined)
+        throw new Error("clearances require explicit collisionBoxes");
+    for (const clearance of clearances ?? []) {
+        if (collisionBoxes.some((solid) => solid.min.every((axis, i) => axis < clearance.max[i] && solid.max[i] > clearance.min[i])))
+            throw new Error(`clearance ${clearance.id} intersects a collision box`);
+    }
+    return { assetId: input.assetId, ...(collisionBoxes === undefined ? {} : { collisionBoxes }), ...(clearances === undefined ? {} : { clearances }) };
+}

package/dist/editor/types.d.ts

@@ -1,3 +1,6 @@
+import type { EditorSimulation } from "./simulation.js";
+import type { MaterialAsset } from "../material/materialAsset.js";
+import type { StaticPrefabBake } from "./staticPrefab.js";
 import type { ParamSchema } from "../scene/sceneKinds.js";
 import type { EditorUiDocument } from "../ui/hudDocument.js";
 import type { MinimapBakeBounds } from "../world/minimapBake.js";
@@ -100,6 +103,8 @@ export interface EditorNote {
 export type EditorTerrain = TerraformSnapshot;
 /** The four placeable-object collections a prefab fragment or clipboard fragment carries. */
 export interface EditorFragmentContent {
+    /** Referenced reusable materials travel with prefab and clipboard content. */
+    materialAssets?: MaterialAsset[];
     markers: readonly EditorMarker[];
     volumes: readonly EditorVolume[];
     paths: readonly EditorPath[];
@@ -115,6 +120,8 @@ export interface EditorPrefab {
     id: string;
     name: string;
     fragment: EditorFragmentContent;
+    /** Offline export settings; world instances remain authored markers. */
+    staticBake?: StaticPrefabBake;
 }
 /**
  * A named, persisted list of object ids — a selection bookmark (restore, add-to) that can also
@@ -219,11 +226,19 @@ export interface EditorEnvironment {
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Sun compass bearing in degrees (0 = -Z, 90 = +X); runtime `SkySunConfig.azimuth`. */
+    sunAzimuth?: number;
+    /** Sun height above the horizon in degrees; runtime `SkySunConfig.elevation`. */
+    sunElevation?: number;
     fog?: EditorFogConfig;
 }
 /** The full authored scene: every marker, volume, path, note, and sculpted terrain for a game. */
 export interface EditorDocument {
+    /** Reusable material library; per-marker named assignments live in meta.materialAssignments. */
+    materialAssets?: MaterialAsset[];
     version: 1;
+    /** Authored weather, emitter, fire and habitat inputs; runtime state saves separately. */
+    simulation?: EditorSimulation;
     markers: EditorMarker[];
     volumes: EditorVolume[];
     paths: EditorPath[];

package/dist/faction/reputation.d.ts

@@ -17,6 +17,10 @@ export interface ReputationLedgerConfig {
     min?: number;
     max?: number;
 }
+/** Plain JSON standings of a {@link ReputationLedger}: stored values only, `initial` stays config. */
+export interface ReputationLedgerState {
+    records: Record<string, Record<string, number>>;
+}
 export interface ReputationLedger {
     standing(actorId: string, factionId: string): number;
     hasStanding(actorId: string, factionId: string): boolean;
@@ -26,6 +30,8 @@ export interface ReputationLedger {
     relation(actorId: string, factionId: string): FactionRelation;
     standings(actorId: string): Record<string, number>;
     reset(actorId: string, factionId?: string): void;
+    snapshot(): ReputationLedgerState;
+    restore(next: ReputationLedgerState): void;
 }
 export declare function createReputationLedger(config?: ReputationLedgerConfig): ReputationLedger;
 export interface EffectiveRelationInput {

package/dist/faction/reputation.js

@@ -77,6 +77,17 @@ export function createReputationLedger(config = {}) {
             else
                 records.get(actorId)?.delete(factionId);
         },
+        snapshot() {
+            const out = {};
+            for (const [actorId, row] of records)
+                out[actorId] = Object.fromEntries(row);
+            return { records: out };
+        },
+        restore(next) {
+            records.clear();
+            for (const [actorId, row] of Object.entries(next.records))
+                records.set(actorId, new Map(Object.entries(row)));
+        },
     };
 }
 export function effectiveRelation(input) {

package/dist/game/cameraConfig.d.ts

@@ -1,3 +1,5 @@
+import type { WeaponHandlingFrame } from "../combat/weaponHandling.js";
+import type { WeaponPresentationTuning } from "../combat/weaponPresentation.js";
 export interface CameraFollowState {
     entityId: string;
     target: {
@@ -12,6 +14,11 @@ export interface CameraFollowState {
     };
     distance: number;
 }
+/** What a camera rig reads about the held weapon each frame; see `GameCameraConfig.weapon`. */
+export interface CameraWeaponView {
+    handling: WeaponHandlingFrame;
+    presentation?: WeaponPresentationTuning;
+}
 export interface FirstPersonCameraConfig {
     /** Camera height above the followed entity's origin. Default 1.6. */
     eyeHeight?: number;
@@ -162,6 +169,8 @@ export interface LockOnCameraConfig {
 export type ChaseView = "chase" | "cockpit" | "hood" | "rear";
 /** Speed-reactive vehicle chase rig (#27) — speed→FOV, spring arm, procedural shake, interior views. */
 export interface ChaseCameraConfig {
+    /** Heading the chase boom follows: target body (default), or independent input/aim yaw for camera-relative walking. Seat views always follow the body. */
+    headingSource?: "body" | "input";
     /** Boom distance behind the vehicle. Default 6. */
     distance?: number;
     /** Camera height above the follow point. Default 2.6. */
@@ -170,11 +179,47 @@ export interface ChaseCameraConfig {
     lookHeight?: number;
     /** Spring-arm damping (higher = stiffer, less lag). Default 6. */
     springDamping?: number;
-    /** Speed→FOV curve: FOV lerps from `base` to `max` as speed climbs to `speedForMax`. */
+    /**
+     * Speed→FOV curve: FOV lerps from `base` to `max` as speed climbs to `speedForMax`. Speed is the
+     * followed entity's sim `velocity` when it publishes one. `response` (default 6) eases the FOV
+     * toward the curve with `1-exp(-response*dt)`; `Infinity` applies it unsmoothed.
+     */
     fov?: {
         base?: number;
         max?: number;
         speedForMax?: number;
+        response?: number;
+    };
+    /** Pull the boom back by up to `extra` world units as speed climbs to `speedForMax` (default the FOV curve's `speedForMax`). */
+    distanceBySpeed?: {
+        extra: number;
+        speedForMax?: number;
+    };
+    /**
+     * Tilt the boom with the target's body pitch (`rotationX`) so the camera stays behind it on
+     * slopes and ramps. `blend` (default 1) is the fraction of the pitch followed, clamped to `max`
+     * radians (default 0.6) and eased by `response` (default 5). Omit the block to keep a level boom.
+     */
+    pitchFollow?: {
+        blend?: number;
+        max?: number;
+        response?: number;
+    };
+    /** How `ctx.camera.kickFov(degrees)` impulses feel: the kick decays at `decay` per second (default 7) and the summed kick is clamped to `max` degrees (default 20). */
+    fovKick?: {
+        decay?: number;
+        max?: number;
+    };
+    /** Input action that, while held, swings the chase view to look back at what is behind the target. */
+    lookBackAction?: string;
+    /**
+     * Pull the boom in past scene colliders, objects, terrain and walls via `ctx.scene.raycast`
+     * (entities never block). `radius` (default 0.3) keeps the lens off the surface; `minDistance`
+     * (default 0.8) is the closest the camera gets to the look pivot. Default on; `false` disables.
+     */
+    collision?: boolean | {
+        radius?: number;
+        minDistance?: number;
     };
     /** Procedural shake amplitude per unit of speed (adds to the trauma channel). Default 0.0. */
     shakePerSpeed?: number;
@@ -434,7 +479,7 @@ export interface GameCameraConfig {
     };
     initialDistance?: number;
     initialHeight?: number;
-    /** Initial horizontal boom facing (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds the orbit rig; unset keeps the legacy -Z placement. */
+    /** Initial horizontal boom facing (radians): 0 = camera behind on -Z, PI = camera on +Z. Seeds orbit and input-owned chase once; unset keeps orbit's -Z placement or seeds chase from its first acquired target's heading. */
     initialYaw?: number;
     /** Initial boom elevation (radians): 0 = level, positive = camera above the target looking down. Seeds the orbit rig; unset derives elevation from `initialHeight`/`initialDistance`. */
     initialPitch?: number;
@@ -446,6 +491,13 @@ export interface GameCameraConfig {
     followEntityId?: string | null;
     /** Fired each frame after cameraFollow lock is applied. */
     onCameraFollow?: (state: CameraFollowState) => void;
+    /**
+     * The followed entity's held weapon, read every frame by the `first` and `shoulder` rigs. Return the
+     * weapon's `createWeaponHandling` frame and its presentation tuning, or `null` for none. First person
+     * poses the viewmodel from it (offset, ADS pose, viewmodel FOV, sway, bob, kick) and adds the recoil to
+     * the look; over-the-shoulder takes its ADS blend from `adsProgress` and adds the same recoil.
+     */
+    weapon?: (entityId: string) => CameraWeaponView | null;
     rotateSpeed?: number;
     zoomSpeed?: number;
     dampingFactor?: number;