@jgengine/core 0.19.0 → 0.22.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/terrainMaterials.d.ts

@@ -0,0 +1,10 @@
+/** A paintable terrain material layer — a surface id plus the color it renders as. */
+export interface TerrainMaterial {
+    id: string;
+    label: string;
+    color: string;
+}
+/** The default terrain paint palette (surface id → color) shared by the panel and the mesh. */
+export declare const TERRAIN_MATERIALS: readonly TerrainMaterial[];
+/** Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint. */
+export declare const TERRAIN_MATERIAL_COLORS: Record<string, string>;

package/dist/editor/terrainMaterials.js

@@ -0,0 +1,13 @@
+/** The default terrain paint palette (surface id → color) shared by the panel and the mesh. */
+export const TERRAIN_MATERIALS = [
+    { id: "grass", label: "Grass", color: "#4b7f3f" },
+    { id: "dirt", label: "Dirt", color: "#6b4f34" },
+    { id: "rock", label: "Rock", color: "#7c7f86" },
+    { id: "sand", label: "Sand", color: "#c2b283" },
+    { id: "mud", label: "Mud", color: "#574433" },
+    { id: "snow", label: "Snow", color: "#eef3f7" },
+    { id: "road", label: "Road", color: "#3a3a3d" },
+    { id: "gravel", label: "Gravel", color: "#8d8d84" },
+];
+/** Maps every default material id to its render color, for the sculpt mesh's per-cell surface tint. */
+export const TERRAIN_MATERIAL_COLORS = Object.fromEntries(TERRAIN_MATERIALS.map((material) => [material.id, material.color]));

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
@@ -227,7 +234,11 @@ export interface EditorEnvironment {
 }
 /** 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/game/cameraConfig.d.ts

@@ -169,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. */
@@ -477,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;

package/dist/game/clipRoles.d.ts

@@ -46,6 +46,7 @@ export declare function defaultAnimationForClips(clips: readonly string[], table
  * configs pass through, `"none"`/absent render the bind pose, and `"auto"` derives states and
  * one-shots from the model's clip names via {@link defaultAnimationForClips}. The shell calls
  * this with the loaded GLB's actual clip names, so `"auto"` works on any rigged model —
- * catalog-resolved ids are stamped `"auto"` automatically.
+ * catalog-resolved ids are stamped `"auto"` automatically. An object with `auto: true` derives
+ * the same defaults, then replaces each explicitly supplied field whole, including empty maps.
  */
 export declare function resolveAnimationConfig(animation: ModelAnimationConfig | "auto" | "none" | undefined, clips: readonly string[] | undefined, table?: ClipRoleTable): ModelAnimationConfig | undefined;

package/dist/game/clipRoles.js

@@ -129,14 +129,18 @@ export function defaultAnimationForClips(clips, table = DEFAULT_CLIP_ROLE_TABLE)
  * configs pass through, `"none"`/absent render the bind pose, and `"auto"` derives states and
  * one-shots from the model's clip names via {@link defaultAnimationForClips}. The shell calls
  * this with the loaded GLB's actual clip names, so `"auto"` works on any rigged model —
- * catalog-resolved ids are stamped `"auto"` automatically.
+ * catalog-resolved ids are stamped `"auto"` automatically. An object with `auto: true` derives
+ * the same defaults, then replaces each explicitly supplied field whole, including empty maps.
  */
 export function resolveAnimationConfig(animation, clips, table = DEFAULT_CLIP_ROLE_TABLE) {
     if (animation === undefined || animation === "none")
         return undefined;
-    if (animation !== "auto")
+    if (animation !== "auto" && animation.auto !== true)
         return animation;
     if (clips === undefined || clips.length === 0)
         return undefined;
-    return defaultAnimationForClips(clips, table);
+    const defaults = defaultAnimationForClips(clips, table);
+    if (defaults === undefined || animation === "auto")
+        return defaults;
+    return { ...defaults, ...animation };
 }