@jgengine/core 0.26.0 → 0.28.0

package/dist/vfx/particleBudget.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The graphics-tier particle budget. A tier caps the live particle count across every effect on
+ * screen; when the requested effects do not fit, whole effects are dropped in a defined order
+ * (lowest {@link ParticleBudgetEntry.priority} first) rather than every effect thinning out.
+ */
+/** One effect asking for particle capacity this frame. */
+export interface ParticleBudgetEntry {
+    /** Emitter or burst id; unique within the request. */
+    id: string;
+    /** Drop order: higher survives, lower is dropped first. */
+    priority: number;
+    /** Particles this effect wants (its pool maximum, or a burst's count). */
+    requested: number;
+}
+/** An admitted effect and the particles it may hold. */
+export interface ParticleBudgetGrant {
+    id: string;
+    particles: number;
+}
+/** What the tier cap admits, and what it drops. */
+export interface ParticleBudgetPlan {
+    /** Admitted effects in priority order, each with its granted particle count. */
+    grants: ParticleBudgetGrant[];
+    /** Dropped effect ids, lowest priority first — the defined drop order. */
+    dropped: string[];
+    /** Sum of the granted particle counts, never above the cap. */
+    particles: number;
+}
+/**
+ * Allocate a tier's particle cap across the effects that want it.
+ *
+ * Effects are visited highest priority first (ties keep authoring order) and each takes
+ * `min(requested, remaining)`. An effect that receives nothing is dropped, so the drop list comes
+ * out lowest priority first: ambient dressing (dust, weather) yields before gameplay-loud effects
+ * (explosions, muzzle flashes). The granted total never exceeds the cap, so the live particle
+ * count cannot either.
+ *
+ * @capability plan-particle-budget cap live particles to a graphics tier and drop whole effects lowest-priority-first when over budget
+ */
+export declare function planParticleBudget(entries: readonly ParticleBudgetEntry[], cap: number): ParticleBudgetPlan;

package/dist/vfx/particleBudget.js

@@ -0,0 +1,39 @@
+/**
+ * The graphics-tier particle budget. A tier caps the live particle count across every effect on
+ * screen; when the requested effects do not fit, whole effects are dropped in a defined order
+ * (lowest {@link ParticleBudgetEntry.priority} first) rather than every effect thinning out.
+ */
+function count(value, fallback = 0) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : fallback;
+}
+/**
+ * Allocate a tier's particle cap across the effects that want it.
+ *
+ * Effects are visited highest priority first (ties keep authoring order) and each takes
+ * `min(requested, remaining)`. An effect that receives nothing is dropped, so the drop list comes
+ * out lowest priority first: ambient dressing (dust, weather) yields before gameplay-loud effects
+ * (explosions, muzzle flashes). The granted total never exceeds the cap, so the live particle
+ * count cannot either.
+ *
+ * @capability plan-particle-budget cap live particles to a graphics tier and drop whole effects lowest-priority-first when over budget
+ */
+export function planParticleBudget(entries, cap) {
+    const limit = count(cap);
+    const ordered = entries
+        .map((entry, index) => ({ entry, index, priority: Number.isFinite(entry.priority) ? entry.priority : 0, wanted: count(entry.requested) }))
+        .sort((a, b) => (b.priority - a.priority) || (a.index - b.index));
+    const grants = [];
+    const dropped = [];
+    let remaining = limit;
+    for (const { entry, wanted } of ordered) {
+        const particles = Math.min(wanted, remaining);
+        if (particles <= 0) {
+            dropped.push(entry.id);
+            continue;
+        }
+        grants.push({ id: entry.id, particles });
+        remaining -= particles;
+    }
+    dropped.reverse();
+    return { grants, dropped, particles: limit - remaining };
+}

package/dist/vfx/particleDirector.d.ts

@@ -1,3 +1,4 @@
+import { type EffectOverride } from "./effectLibrary.js";
 import { type EmitterConfig, type ParticleEvent, type Vec3 } from "./particles.js";
 /** How a particle effect composites on screen: `additive` for sparks/fire/glow, `normal` for smoke/dust. */
 export type ParticleBlendHint = "additive" | "normal";
@@ -17,6 +18,8 @@ export interface ParticleBurst {
     blending?: ParticleBlendHint;
     emitterId?: string;
     options?: ParticleAttachOptions;
+    /** Graphics-tier drop order; higher survives. Default 0. */
+    priority?: number;
 }
 /** A bounded collision child effect; children cannot spawn further collision children. */
 export interface ParticleCollisionEffect {
@@ -43,6 +46,8 @@ export interface ParticleAttachOptions {
         maxAcceleration?: number;
         mask?: number;
     };
+    /** Graphics-tier drop order: higher survives, lower is dropped first. Default 0. */
+    priority?: number;
 }
 /** A keyed continuous emitter owned by the director until detached. */
 export interface ParticleEmitterSpec extends ParticleAttachOptions {
@@ -52,6 +57,11 @@ export interface ParticleEmitterSpec extends ParticleAttachOptions {
     offset?: Vec3;
     blending?: ParticleBlendHint;
 }
+/** A library effect played by name: where it plays, plus per-call overrides. */
+export interface EffectRequest extends EffectOverride {
+    /** Entity id a standing emitter tracks each frame (plus `offset`). */
+    follow?: string;
+}
 /** A cosmetic simulation event, labelled with its emitting effect. */
 export interface ParticleDirectorEvent extends ParticleEvent {
     emitterId: string;
@@ -87,6 +97,12 @@ export interface ParticleDirector {
     stop(id: string): void;
     /** Emit once through a named emitter's existing pool, including when stopped. */
     burstNamed(id: string, count: number): void;
+    /** Play a library effect by name once, as a one-shot burst at the request's position. */
+    play(name: string, request?: EffectRequest): void;
+    /** Create or replace a standing emitter from a library effect name under `id`. */
+    attachEffect(id: string, name: string, request?: EffectRequest): void;
+    /** The named effects a caller can play, from the shared library. */
+    effectNames(): readonly string[];
     /** Renderer-to-game cosmetic event exchange, bounded by the director's event limit. */
     reportEvents(id: string, events: readonly ParticleEvent[]): void;
     drainEvents(): ParticleDirectorEvent[];

package/dist/vfx/particleDirector.js

@@ -1,3 +1,4 @@
+import { effectNames, resolveEffect } from "./effectLibrary.js";
 import { validateEmitterConfig } from "./particles.js";
 /**
  * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
@@ -24,6 +25,7 @@ export function createParticleDirector(options = {}) {
         bursts.push({ seq: nextSeq++, config: structuredClone(config), count: wanted,
             ...(blending === undefined ? {} : { blending }),
             ...(emitterId === undefined ? {} : { emitterId }),
+            priority: Number.isFinite(attachOptions?.priority) ? attachOptions.priority : 0,
             ...(attachOptions === undefined ? {} : { options: structuredClone(attachOptions) }) });
         notify();
     }
@@ -64,6 +66,20 @@ export function createParticleDirector(options = {}) {
             const { id: _, config, ...options } = spec;
             queue(config, count, spec.blending, id, options);
         },
+        play(name, request) {
+            const effect = resolveEffect(name, request);
+            const follow = request?.follow ?? effect.options.follow;
+            queue(effect.config, effect.burst, effect.blending, undefined, { ...effect.options, ...(follow === undefined ? {} : { follow }) });
+        },
+        attachEffect(id, name, request) {
+            const effect = resolveEffect(name, request);
+            if (!emitters.has(id) && emitters.size >= maxEmitters)
+                throw new RangeError(`Particle emitter capacity ${maxEmitters} exceeded by ${id}`);
+            const follow = request?.follow ?? effect.options.follow;
+            emitters.set(id, { id, config: effect.config, ...effect.options, ...(follow === undefined ? {} : { follow }) });
+            notify();
+        },
+        effectNames,
         reportEvents(id, next) {
             for (let i = 0, n = Math.min(next.length, maxEvents - events.length); i < n; i++) {
                 events.push({ ...structuredClone(next[i]), emitterId: id });
@@ -129,6 +145,8 @@ export function validateParticleAttachOptions(value) {
         errors.push("space must be world or local");
     if (options.active !== undefined && typeof options.active !== "boolean")
         errors.push("active must be boolean");
+    if (options.priority !== undefined && (typeof options.priority !== "number" || !Number.isFinite(options.priority)))
+        errors.push("priority must be a finite number");
     const output = (render, blending, prefix) => {
         if (blending !== undefined && blending !== "normal" && blending !== "additive")
             errors.push(`${prefix}blending must be normal or additive`);

package/dist/world/authoredSimulation.js

@@ -89,7 +89,13 @@ export function createAuthoredSimulation(options) {
             const previous = config.emitters?.find((entry) => entry.id === emitter.id);
             if (emitterIds.includes(id) && JSON.stringify(previous) === JSON.stringify(emitter))
                 continue;
-            options.particles?.attach(id, { ...emitter.config, position: [emitter.position.x, emitter.position.y, emitter.position.z] }, { ...emitter.options, ...(emitter.fireAreaId === undefined ? {} : { active: emitter.options?.active !== false && nextFires.get(emitter.fireAreaId).burning > 0 }) });
+            const position = [emitter.position.x, emitter.position.y, emitter.position.z];
+            const fire = emitter.fireAreaId === undefined ? undefined : { active: emitter.options?.active !== false && nextFires.get(emitter.fireAreaId).burning > 0 };
+            const request = { position, options: { ...emitter.options, ...(fire ?? {}) } };
+            if (emitter.effect !== undefined)
+                options.particles?.attachEffect(id, emitter.effect, request);
+            else
+                options.particles?.attach(id, { ...emitter.config, position }, request.options);
         }
         emitterIds = nextEmitterIds;
         document = nextDocument;

package/dist/world/captureCamera.d.ts

@@ -0,0 +1,30 @@
+import type { CameraRigKind } from "../game/playableGame.js";
+import type { CameraRigConfig } from "../runtime/cameraDirector.js";
+/**
+ * Per-session capture-camera override — the harness counterpart of `?cam=`/`?look=`, and the same
+ * install-style seam as `world/spawnOverride`: the runner installs one, the shell reads it, nothing
+ * changes until one is installed.
+ *
+ * It exists because a game that owns its camera wins by other routes: a static `camera` config
+ * swapped by the harness only reaches the rig until the game selects its own rig at runtime
+ * (`ctx.camera.setRig`, a persisted settings camera, a director cinematic), and the capture then
+ * silently photographs the game's camera. This override is read above every one of those, so a
+ * framed capture stays framed; a game's own camera is untouched the moment the page loads without
+ * the param.
+ */
+export interface CaptureCameraOverride {
+    kind: CameraRigKind;
+    config: CameraRigConfig;
+}
+/**
+ * Install (or, with `null`, clear) the capture camera. Idempotent; last write wins. It outranks the
+ * game's static camera config and any runtime `ctx.camera` rig selection, and it is never saved —
+ * it is a property of this capture session, not of the game.
+ *
+ * @capability capture force a framed capture camera over a game that owns its camera
+ */
+export declare function installCaptureCamera(override: CaptureCameraOverride | null): void;
+/** Clear any installed capture camera. */
+export declare function clearCaptureCamera(): void;
+/** The installed capture camera, or `null` when the game's own camera should render. */
+export declare function readCaptureCamera(): CaptureCameraOverride | null;

package/dist/world/captureCamera.js

@@ -0,0 +1,19 @@
+let installed = null;
+/**
+ * Install (or, with `null`, clear) the capture camera. Idempotent; last write wins. It outranks the
+ * game's static camera config and any runtime `ctx.camera` rig selection, and it is never saved —
+ * it is a property of this capture session, not of the game.
+ *
+ * @capability capture force a framed capture camera over a game that owns its camera
+ */
+export function installCaptureCamera(override) {
+    installed = override;
+}
+/** Clear any installed capture camera. */
+export function clearCaptureCamera() {
+    installed = null;
+}
+/** The installed capture camera, or `null` when the game's own camera should render. */
+export function readCaptureCamera() {
+    return installed;
+}

package/dist/world/decalKind.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `decal` marker: a surface-grime decal authored as a placed marker (dirt, cracks, paint, blood).
+ * Its position, facing (`rotationY`), tilt (0 lies on the ground, 90 stands on a wall), size, opacity
+ * and seed live in the scene document, so decals are placed in the editor like any other authored
+ * content and a game never hardcodes a stain. Pure config here; the procedural texture and the
+ * draped/standing quad live in the `shell` renderer.
+ *
+ * @capability decal editor-authored surface decal
+ */
+import { type ParamSchema, type SceneKindObject } from "../scene/sceneKinds.js";
+/** The editor marker kind marking a surface decal. */
+export declare const DECAL_KIND = "decal";
+/** The four authored decal looks; each has its own deterministic procedural texture. */
+export declare const DECAL_STYLES: readonly ["dirt", "cracks", "paint", "blood"];
+/** One of the four authored decal looks. */
+export type DecalStyle = (typeof DECAL_STYLES)[number];
+/** Fully-defaulted decal params parsed from a marker's `meta`. */
+export interface DecalRules {
+    style: DecalStyle;
+    /** Decal width/height in metres. */
+    size: number;
+    /** 0 lies flat on the ground, 90 stands on a wall; 45 leans. */
+    tilt: number;
+    /** Vertical offset of the decal centre above the placed point, in metres. */
+    lift: number;
+    /** Push along the decal's own normal, so a wall decal clears the wall it sits on. */
+    offset: number;
+    /** 0..1 overall alpha. */
+    opacity: number;
+    /** Deterministic shape seed. */
+    seed: string;
+}
+/** Default decal rules: a small dirt smudge lying on the ground. */
+export declare const DECAL_DEFAULTS: DecalRules;
+/** The decal parameter schema — drives the inspector and the `meta` parse. */
+export declare const DECAL_SCHEMA: ParamSchema;
+/** Parse a marker's `meta` into fully-defaulted decal rules. @internal */
+export declare function readDecalRules(meta: Record<string, unknown> | undefined): DecalRules;
+/** A resolved decal: its placed point/facing plus fully-defaulted rules. */
+export interface ResolvedDecal {
+    position: readonly [number, number, number];
+    rotationY: number;
+    rules: DecalRules;
+}
+/** Resolve a decal marker into a placed, fully-defaulted decal; null without a position. @internal */
+export declare function resolveDecalObject(object: SceneKindObject): ResolvedDecal | null;
+/** Registers the `decal` scene kind. Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerDecalKind(): void;

package/dist/world/decalKind.js

@@ -0,0 +1,86 @@
+/**
+ * `decal` marker: a surface-grime decal authored as a placed marker (dirt, cracks, paint, blood).
+ * Its position, facing (`rotationY`), tilt (0 lies on the ground, 90 stands on a wall), size, opacity
+ * and seed live in the scene document, so decals are placed in the editor like any other authored
+ * content and a game never hardcodes a stain. Pure config here; the procedural texture and the
+ * draped/standing quad live in the `shell` renderer.
+ *
+ * @capability decal editor-authored surface decal
+ */
+import { registerSceneKind } from "../scene/sceneKinds.js";
+/** The editor marker kind marking a surface decal. */
+export const DECAL_KIND = "decal";
+/** The four authored decal looks; each has its own deterministic procedural texture. */
+export const DECAL_STYLES = ["dirt", "cracks", "paint", "blood"];
+/** Default decal rules: a small dirt smudge lying on the ground. */
+export const DECAL_DEFAULTS = {
+    style: "dirt",
+    size: 2.4,
+    tilt: 0,
+    lift: 0.02,
+    offset: 0.04,
+    opacity: 0.9,
+    seed: "",
+};
+/** The decal parameter schema — drives the inspector and the `meta` parse. */
+export const DECAL_SCHEMA = {
+    fields: [
+        { type: "select", key: "style", label: "style", options: DECAL_STYLES.map((value) => ({ value })), default: DECAL_DEFAULTS.style },
+        { type: "range", key: "size", label: "size", min: 0.3, max: 24, step: 0.1, default: DECAL_DEFAULTS.size, unit: "m" },
+        { type: "range", key: "tilt", label: "tilt", min: 0, max: 90, step: 1, default: DECAL_DEFAULTS.tilt, unit: "°" },
+        { type: "range", key: "lift", label: "height", min: 0, max: 30, step: 0.05, default: DECAL_DEFAULTS.lift, unit: "m" },
+        { type: "range", key: "offset", label: "surface offset", min: 0, max: 2, step: 0.01, default: DECAL_DEFAULTS.offset, unit: "m" },
+        { type: "range", key: "opacity", label: "opacity", min: 0.05, max: 1, step: 0.01, default: DECAL_DEFAULTS.opacity },
+        { type: "seed", key: "seed", label: "seed", default: DECAL_DEFAULTS.seed },
+    ],
+};
+function number(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function text(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "string" ? value : fallback;
+}
+/** Parse a marker's `meta` into fully-defaulted decal rules. @internal */
+export function readDecalRules(meta) {
+    const style = text(meta, "style", DECAL_DEFAULTS.style);
+    return {
+        style: DECAL_STYLES.includes(style) ? style : DECAL_DEFAULTS.style,
+        size: Math.min(24, Math.max(0.3, number(meta, "size", DECAL_DEFAULTS.size))),
+        tilt: Math.min(90, Math.max(0, number(meta, "tilt", DECAL_DEFAULTS.tilt))),
+        lift: Math.max(0, number(meta, "lift", DECAL_DEFAULTS.lift)),
+        offset: Math.max(0, number(meta, "offset", DECAL_DEFAULTS.offset)),
+        opacity: Math.min(1, Math.max(0.05, number(meta, "opacity", DECAL_DEFAULTS.opacity))),
+        seed: text(meta, "seed", DECAL_DEFAULTS.seed),
+    };
+}
+/** Resolve a decal marker into a placed, fully-defaulted decal; null without a position. @internal */
+export function resolveDecalObject(object) {
+    const position = object.position ?? object.center;
+    if (position === undefined)
+        return null;
+    return {
+        position: [position.x, position.y, position.z],
+        rotationY: object.rotationY ?? 0,
+        rules: readDecalRules(object.meta),
+    };
+}
+/** Registers the `decal` scene kind. Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerDecalKind() {
+    registerSceneKind({
+        kind: DECAL_KIND,
+        target: "marker",
+        label: "Decal",
+        addCategory: "Studios",
+        accent: "#b5793c",
+        schema: DECAL_SCHEMA,
+        resolve: (object) => resolveDecalObject(object),
+        note: (object) => {
+            const resolved = resolveDecalObject(object);
+            if (resolved === null)
+                return "Place the marker on a surface.";
+            return `${resolved.rules.style} · ${resolved.rules.size.toFixed(1)} m ${resolved.rules.tilt >= 45 ? "wall" : "ground"} decal`;
+        },
+    });
+}

package/dist/world/features.d.ts

@@ -70,16 +70,20 @@ export interface TerrainDetailConfig {
 }
 /**
  * PBR map URLs for a real ground texture — the same shape
- * `buildMaterialCatalog({ basePath }).resolve(id)!.maps` from `@jgengine/assets` returns. Kept
- * dependency-free here so `core` never imports the assets package; any URLs (pulled maps, a CDN, a
- * data URI) satisfy it. Omitted roughness keeps the terrain scalar; omitted AO skips occlusion sampling.
+ * `libraryTerrainMaterial(name).maps` from `@jgengine/assets` returns. Kept dependency-free here so
+ * `core` never imports the assets package; any URLs (pulled maps, a CDN, a data URI) satisfy it.
+ * Omitted roughness keeps the terrain scalar; omitted AO skips occlusion sampling.
  */
 export interface TerrainMaterialMaps {
     color: string;
     normal: string;
     roughness?: string;
     ao?: string;
-    displacement: string;
+    /**
+     * Height map for callers that displace geometry themselves. The terrain detail shader never
+     * samples it, so pass the URL only when the pulled set actually ships one — never invent it.
+     */
+    displacement?: string;
 }
 /**
  * Real PBR texture applied over the ground surface — the seam that lets a game put a
@@ -102,6 +106,13 @@ export interface TerrainDetailMaterialConfig {
      * hand-tinted world wants from a stock PBR set.
      */
     tint?: number;
+    /**
+     * What a failed map load does. Scanned maps are pulled by a game's asset step, not committed, so a
+     * checkout without them looks exactly like a broken one. `"procedural"` (default) keeps the
+     * authored procedural ground and logs one warning naming the map; `"fail"` hands the error to the
+     * presentation retry screen, which is what a view that cannot render without the scan asks for.
+     */
+    missing?: "procedural" | "fail";
 }
 export interface TerrainFlattenMask {
     center: EnvironmentVec2;
@@ -288,6 +299,8 @@ export interface GrassEnvironmentConfig {
     colorVariation?: number;
     /** 0..1 blend of blade normals toward straight-up (shell default 0.6). Low values light each blade plane individually and go dark when side-lit; high values light the field like a soft carpet. */
     normalLift?: number;
+    /** 0..1 strength of the turf ground-cover mat painted under the blades (shell default 0.9); 0 leaves the ground bare. */
+    groundCover?: number;
 }
 export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
@@ -459,7 +472,7 @@ export type SnowEnvironmentDescriptor = {
 } & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity">>;
 export type GrassEnvironmentDescriptor = {
     kind: "grass";
-} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed" | "bladeBend" | "tuftRadius" | "colorVariation" | "normalLift">;
+} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed" | "bladeBend" | "tuftRadius" | "colorVariation" | "normalLift" | "groundCover">;
 export type OceanEnvironmentDescriptor = {
     kind: "ocean";
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;

package/dist/world/features.js

@@ -201,6 +201,7 @@ export function grass(config = {}) {
         ...(config.tuftRadius === undefined ? {} : { tuftRadius: config.tuftRadius }),
         ...(config.colorVariation === undefined ? {} : { colorVariation: config.colorVariation }),
         ...(config.normalLift === undefined ? {} : { normalLift: config.normalLift }),
+        ...(config.groundCover === undefined ? {} : { groundCover: config.groundCover }),
     };
 }
 /** Declares an ocean water body for `environment()` — bounds, level, and wave tuning. */

package/dist/world/grassKind.d.ts

@@ -40,6 +40,11 @@ export interface GrassRules {
     windGust: number;
     /** Blade material roughness, 0..1. */
     roughness: number;
+    /**
+     * Ground-cover mat strength, 0..1: the patch paints a turf surface over its footprint instead of
+     * leaving the ground beneath the blades bare. 0 keeps blades only.
+     */
+    groundCover: number;
     /** Seed string; same seed reproduces the same blade layout. */
     seed: string;
 }

package/dist/world/grassKind.js

@@ -28,6 +28,7 @@ export const GRASS_DEFAULTS = {
     windSpeed: 1.6,
     windGust: 0.16,
     roughness: 0.85,
+    groundCover: 0.9,
     seed: "",
 };
 /** The grass parameter schema — drives the inspector and `meta` parse via the studio seam. */
@@ -48,6 +49,7 @@ export const GRASS_SCHEMA = {
         { type: "range", key: "windSpeed", label: "wind speed", min: 0, max: 4, step: 0.05, default: GRASS_DEFAULTS.windSpeed },
         { type: "range", key: "windGust", label: "gust scale", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.windGust },
         { type: "range", key: "roughness", label: "roughness", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.roughness },
+        { type: "range", key: "groundCover", label: "ground cover", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.groundCover },
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
@@ -81,6 +83,7 @@ export function readGrassRules(meta) {
         windSpeed: metaNumber(meta, "windSpeed", GRASS_DEFAULTS.windSpeed),
         windGust: metaNumber(meta, "windGust", GRASS_DEFAULTS.windGust),
         roughness: metaNumber(meta, "roughness", GRASS_DEFAULTS.roughness),
+        groundCover: Math.max(0, Math.min(1, metaNumber(meta, "groundCover", GRASS_DEFAULTS.groundCover))),
         seed: metaString(meta, "seed", GRASS_DEFAULTS.seed),
     };
 }

package/dist/world/terraform.d.ts

@@ -57,6 +57,14 @@ export interface TerrainMaterialLayer {
     tint?: string;
     /** Layer master opacity 0..1 — scales this layer's blend weight everywhere. */
     opacity?: number;
+    /**
+     * Material library name (e.g. `"foliage/grass"`) whose scanned PBR color map paints this layer,
+     * as authored. The editor resolves it into {@link TerrainMaterialLayer.materialUrl} so the runtime
+     * needs no asset-library lookup.
+     */
+    material?: string;
+    /** Resolved URL of the layer's scanned color map, written by the editor from {@link TerrainMaterialLayer.material}. */
+    materialUrl?: string;
 }
 export interface TerraformSnapshot {
     bounds: Aabb;

package/dist/world/terrain.d.ts

@@ -201,6 +201,7 @@ export interface ResolvedTerrainDetailMaterial {
     repeat: number;
     strength: number;
     tint: number;
+    missing: "procedural" | "fail";
 }
 /** A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes. */
 export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material" | "sweeps">> & {

package/dist/world/terrain.js

@@ -487,6 +487,7 @@ const IMPLICIT_TERRAIN_DETAIL = {
 const DEFAULT_TERRAIN_MATERIAL_REPEAT = 4;
 const DEFAULT_TERRAIN_MATERIAL_STRENGTH = 1;
 const DEFAULT_TERRAIN_MATERIAL_TINT = 1;
+const DEFAULT_TERRAIN_MATERIAL_MISSING = "procedural";
 /** Sand-band level for a terrain with no water: far below any ground, so no beach is painted. */
 const NO_WATER_SAND_LEVEL = -1e6;
 /** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level,
@@ -520,6 +521,7 @@ export function resolveTerrainDetail(config, terrainWaterLevel) {
                     repeat: config.material.repeat ?? DEFAULT_TERRAIN_MATERIAL_REPEAT,
                     tint: clamp01(config.material.tint ?? DEFAULT_TERRAIN_MATERIAL_TINT),
                     strength: clamp01(config.material.strength ?? DEFAULT_TERRAIN_MATERIAL_STRENGTH),
+                    missing: config.material.missing ?? DEFAULT_TERRAIN_MATERIAL_MISSING,
                 },
             }),
     };

package/dist/world.d.ts

@@ -1,6 +1,7 @@
-export { type HeatConfig, type HeatGain, type HeatLevelDef, type HeatState } from "./ai/heatSystem.js";
+export { type HeatConfig, type HeatGain, type HeatLevelDef, type HeatPoint, type HeatState } from "./ai/heatSystem.js";
 export { advanceInterestGate, createInterestCensus, createInterestGateState, interestPhase, type InterestCensus, type InterestCensusAccumulator, type InterestGateInput, type InterestGateState, type InterestGateStep, type InterestSchedulerConfig, type InterestState, type InterestTier, } from "./ai/interestScheduler.js";
 export { type Job, type JobDef, type JobReport } from "./ai/jobBoard.js";
+export { DEFAULT_POLICE_TIERS, DEFAULT_POLICE_TUNING, createPoliceResponse, policeRoadsFromLaneGraph, type PoliceLaneHit, type PoliceResponse, type PoliceResponseConfig, type PoliceResponseKind, type PoliceResponseState, type PoliceRoadblockSite, type PoliceRoads, type PoliceRoadsOptions, type PoliceSearchArea, type PoliceSighting, type PoliceStats, type PoliceStep, type PoliceTickContext, type PoliceTier, type PoliceTuning, type PoliceWitness, } from "./ai/policeResponse.js";
 export { createRvoCrowd, type RvoAgentSpec, type RvoAgentView, type RvoCrowd, type RvoCrowdOptions, type RvoSnapshot, type RvoTunables, } from "./ai/rvo.js";
 export { advanceSpawnDirector, advanceWave, createSpawnDirectorState, pickSpawnPoint, raiseAlert, type SpawnDirectorConfig, type SpawnDirectorState, type SpawnEntry, type SpawnRequest, type WaveManifest, } from "./ai/spawnDirector.js";
 export { acquireTarget, createTargetAcquirer, type AcquisitionEnvelope, type AcquisitionPolicy, type AcquisitionResult, type AcquisitionRetention, type TargetAcquirer, } from "./ai/targetAcquisition.js";
@@ -31,6 +32,7 @@ export { MOVEMENT_TUNING, type CollisionObstacle } from "./movement/movementMode
 export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/playerMovement.js";
 export { POSE_HITBOX, createPoseState, type MovementPose } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
+export { createLaneGraph, laneGraphFromDocument, type LaneEdgeConfig, type LaneGraph, type LaneGraphConfig, type LaneGraphDocumentOptions, type LaneIntersection, type LaneIntersectionConfig, type LaneNode, type LanePose, type LaneRightOfWay, type LaneSignalProgram, type LaneSpan, type LaneSpot, } from "./nav/laneGraph.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
 export { createNavCrowd, type NavCrowd, type NavCrowdAgentSpec, type NavCrowdAgentView, type NavCrowdOptions, type NavCrowdRevalidate, type NavCrowdSnapshot, type NavCrowdStats, } from "./nav/navCrowd.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
@@ -38,6 +40,7 @@ export { createNavGrid, findPath, slopeStepCost, type NavGrid, type NavPoint } f
 export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, type NavMeshAdjacency, type NavMeshData, type NavMeshLink, type NavMeshPath, type NavMeshQuery, type NavMeshQueryOptions, type NavMeshQuerySnapshot, } from "./nav/navMesh.js";
 export { createNavRuntime, navMeshFromBake, type AuthoredNavLink, type NavLinkKind, type NavRebuildStats, type NavRegion, type NavRuntime, type NavRuntimeOptions, type NavRuntimeSnapshot, type SceneBake, } from "./nav/navRuntime.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, type PathFollowConfig, type PathFollowProgress, type PathFollowState, type PathProgress, type Waypoint, } from "./nav/pathFollow.js";
+export { createTraffic, type Traffic, type TrafficCarView, type TrafficOptions, type TrafficRoutePolicy, type TrafficSignalState, type TrafficSnapshot, type TrafficStats, type TrafficTuning, } from "./nav/traffic.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, type AttackMoveOrderPayload, type EmptyOrderPayload, type EngagementKindConfig, type EngagementOrderState, type MoveOrderPayload, type OrderKindConfig, type OrderMoveResult, type OrderMover, type OrderTargeting, type PatrolOrderPayload, type PatrolOrderState, type TargetedOrderPayload, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, type Order, type OrderCancelReason, type OrderEvent, type OrderIssueResult, type OrderKind, type OrderOutcome, type OrderPhase, type OrderProgress, type OrderQueue, type OrderQueueOptions, type OrderQueuePolicy, type OrderQueueState, type OrderRegistry, type OrderRejection, type OrderRequest, type OrderStartResult, type OrderTickReport, type OrderVec3, } from "./orders/orderQueue.js";
 export { createBallisticSweep, type BallisticSweep, type BallisticSweepHit } from "./physics/ballisticSweep.js";
@@ -48,14 +51,16 @@ export { tickDrivableVehicle } from "./physics/drivableVehicle.js";
 export { createAircraftDynamics, type AircraftAxis, type AircraftDynamics, type AircraftKind, type AircraftOptions, type AircraftStep, type AircraftTuning, type FlightControlInput, type FlightControlRates, type FlightVector, } from "./physics/flightDynamics.js";
 export { ForceVolume, PlatformCarry } from "./physics/forceVolume.js";
 export { combineGravity, pointGravity, uniformGravity, type GravityField, type GravityVector, type PointGravityOptions, } from "./physics/gravityField.js";
-export { createKinematicVehicle, type KinematicChassisTuning, type KinematicDynamicsTuning, type KinematicPowertrainTuning, type KinematicSteeringTuning, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, } from "./physics/kinematicVehicle.js";
+export { createKinematicVehicle, type KinematicChassisTuning, type KinematicDynamicsTuning, type KinematicPowertrainTuning, type KinematicSteeringTuning, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, type KinematicWeightTransferTuning, } from "./physics/kinematicVehicle.js";
 export { PhysicsWorld, SHAPE_BOX, SHAPE_SPHERE, type AddBodyOptions, type CollisionEvent, type PhysicsStats, } from "./physics/physicsWorld.js";
 export { createRagdoll } from "./physics/ragdoll.js";
 export { SpatialGrid } from "./physics/spatialGrid.js";
 export { StructureGraph, type CollapseEvent, type StructureMaterial } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve, type GripCurve } from "./physics/vehicleBody.js";
+export { createVehicleDamage, damagedAxis, damagedTuning, type VehicleDamage, type VehicleDamageConfig, type VehicleDamageEffect, type VehicleDamageEffectResolved, type VehicleDamageState, type VehicleDamageTransition, type VehicleDamageZone, type VehicleDamageZoneState, type VehicleDeformation, } from "./physics/vehicleDamage.js";
 export { createVehicleObstacleClamp, type VehicleImpact, type VehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
+export { applyVehicleParts, feelOf, withPart, type VehicleFeel, type VehiclePart, type VehiclePartEffect, type VehicleSetup, type VehicleStat, } from "./physics/vehicleParts.js";
 export { type ObjectSlotRejection, type ObjectSlotResult, type ObjectSlotTransfer, type SceneObjectSlots, } from "./runtime/context/objectSlots.js";
 export { createAssetCatalog, type AssetCatalog, type ModelAssetRef, type ModelDims } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator, type GeneratedAsset, type GeneratedPart } from "./scene/assetGenerator.js";

package/dist/world.js

@@ -1,6 +1,7 @@
 export {} from "./ai/heatSystem.js";
 export { advanceInterestGate, createInterestCensus, createInterestGateState, interestPhase, } from "./ai/interestScheduler.js";
 export {} from "./ai/jobBoard.js";
+export { DEFAULT_POLICE_TIERS, DEFAULT_POLICE_TUNING, createPoliceResponse, policeRoadsFromLaneGraph, } from "./ai/policeResponse.js";
 export { createRvoCrowd, } from "./ai/rvo.js";
 export { advanceSpawnDirector, advanceWave, createSpawnDirectorState, pickSpawnPoint, raiseAlert, } from "./ai/spawnDirector.js";
 export { acquireTarget, createTargetAcquirer, } from "./ai/targetAcquisition.js";
@@ -31,6 +32,7 @@ export { MOVEMENT_TUNING } from "./movement/movementModel.js";
 export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/playerMovement.js";
 export { POSE_HITBOX, createPoseState } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
+export { createLaneGraph, laneGraphFromDocument, } from "./nav/laneGraph.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
 export { createNavCrowd, } from "./nav/navCrowd.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
@@ -38,6 +40,7 @@ export { createNavGrid, findPath, slopeStepCost } from "./nav/navGrid.js";
 export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, } from "./nav/navMesh.js";
 export { createNavRuntime, navMeshFromBake, } from "./nav/navRuntime.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, } from "./nav/pathFollow.js";
+export { createTraffic, } from "./nav/traffic.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, } from "./orders/orderQueue.js";
 export { createBallisticSweep } from "./physics/ballisticSweep.js";
@@ -55,7 +58,9 @@ export { SpatialGrid } from "./physics/spatialGrid.js";
 export { StructureGraph } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve } from "./physics/vehicleBody.js";
+export { createVehicleDamage, damagedAxis, damagedTuning, } from "./physics/vehicleDamage.js";
 export { createVehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
+export { applyVehicleParts, feelOf, withPart, } from "./physics/vehicleParts.js";
 export {} from "./runtime/context/objectSlots.js";
 export { createAssetCatalog } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator } from "./scene/assetGenerator.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter