@jgengine/shell 0.26.0 → 0.28.0

package/dist/render/useModelAnimation.js

@@ -3,10 +3,20 @@ import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
 import { ANIM_PARAMS_KEY, createAnimGraphRuntime, } from "@jgengine/core/anim/animGraph";
-import { animGraphFromConfig, LOCOMOTION_CROUCHED_PARAM, LOCOMOTION_GROUNDED_PARAM, LOCOMOTION_SPEED_PARAM, LOCOMOTION_VERTICAL_SPEED_PARAM } from "@jgengine/core/anim/locomotionGraph";
+import { animGraphFromConfig, LOCOMOTION_CROUCHED_PARAM, LOCOMOTION_DIRECTION_PARAM, LOCOMOTION_FACING_PARAM, LOCOMOTION_GROUNDED_PARAM, LOCOMOTION_SPEED_PARAM, LOCOMOTION_TURN_RATE_PARAM, LOCOMOTION_VERTICAL_SPEED_PARAM, } from "@jgengine/core/anim/locomotionGraph";
 import { playerMovementTelemetry } from "@jgengine/core/movement/playerMovement";
 import { seededRng } from "@jgengine/core/random/rng";
 import { useOptionalGameContext } from "@jgengine/react/provider";
+import { characterLodInterval, characterLodTierOf, noteAnimationPhase, noteCharacterPose } from "./characterLod.js";
+/** Wraps a yaw change into `(-pi, pi]`, so a turn across the wrap boundary is not a full spin. */
+function shortestAngle(radians) {
+    const turn = radians % (Math.PI * 2);
+    if (turn > Math.PI)
+        return turn - Math.PI * 2;
+    if (turn < -Math.PI)
+        return turn + Math.PI * 2;
+    return turn;
+}
 function graphClipNames(graph) {
     const names = new Set();
     for (const layer of graph.layers) {
@@ -102,11 +112,14 @@ function warnAnimationDiagnostics(scene, animation, clips) {
 /**
  * Refreshes a caller-owned graph parameter dictionary from authored extras and known physical movement.
  * Grounded, verticalSpeed and crouched use the shared motor's resolved state when available; custom movers
- * retain their authored values. Speed always uses the supplied measured ground speed. Does not write game state.
+ * retain their authored values. Speed always uses the supplied measured ground speed. Passing `step`
+ * derives the directional parameters from the character's own motion: `direction` is the motion's share
+ * along the character's right axis, `facing` its share along the facing axis, and `turnRate` its yaw
+ * change per second. Derived values override conflicting authored extras. Does not write game state.
  *
  * @capability animation-motion-params read resolved player movement into reusable animation graph parameters
  */
-export function readModelAnimationParams(ctx, instanceId, speed, out) {
+export function readModelAnimationParams(ctx, instanceId, speed, out, step) {
     const extra = ctx.scene.entity.blackboard.get(instanceId, ANIM_PARAMS_KEY);
     const motion = playerMovementTelemetry(ctx, instanceId);
     if (out === extra || out === motion)
@@ -122,6 +135,22 @@ export function readModelAnimationParams(ctx, instanceId, speed, out) {
         out[LOCOMOTION_CROUCHED_PARAM] = motion.crouching;
     }
     out[LOCOMOTION_SPEED_PARAM] = speed;
+    if (step !== undefined) {
+        const yaw = ctx.scene.entity.get(instanceId)?.rotationY ?? 0;
+        const planar = Math.hypot(step.dx, step.dz);
+        if (planar > 1e-4) {
+            const mx = step.dx / planar;
+            const mz = step.dz / planar;
+            // The rig faces its own +Z turned by `rotationY`, so its right axis is +X turned the same way.
+            out[LOCOMOTION_FACING_PARAM] = mx * Math.sin(yaw) + mz * Math.cos(yaw);
+            out[LOCOMOTION_DIRECTION_PARAM] = mx * Math.cos(yaw) - mz * Math.sin(yaw);
+        }
+        else {
+            out[LOCOMOTION_FACING_PARAM] = 0;
+            out[LOCOMOTION_DIRECTION_PARAM] = 0;
+        }
+        out[LOCOMOTION_TURN_RATE_PARAM] = step.seconds > 0 ? step.dyaw / step.seconds : 0;
+    }
     return out;
 }
 /** Per-layer action key: a masked or additive layer needs its own clip variant even for a clip another layer plays. */
@@ -157,6 +186,15 @@ function applyGraphClips(actions, clips) {
         action.time = entry.time;
     }
 }
+/** The clip with the largest weight in one graph output: the pose the rig is mostly showing. */
+function dominantPhase(clips) {
+    let best;
+    for (const entry of clips) {
+        if (entry.weight > 0 && (best === undefined || entry.weight > best.weight))
+            best = entry;
+    }
+    return best === undefined ? undefined : { clip: best.clip, time: best.time };
+}
 /**
  * Binds a graph's clips to a rig exactly as `useModelAnimation` does (masked layers get filtered
  * clips, additive layers additive ones) so a host that runs its own `createAnimGraphRuntime`, such as
@@ -241,6 +279,7 @@ function buildGraphPlayback(scene, mixer, graph, clips, rng) {
         rootBone,
         rootBindPosition: rootBone?.position.clone() ?? null,
         lastPos: null,
+        lastYaw: null,
         smoothedSpeed: 0,
         params: {},
     };
@@ -274,6 +313,8 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
     const animationPausedRef = useRef(false);
     const graphRef = useRef(null);
     const advancedSecondsRef = useRef(undefined);
+    const pendingRef = useRef(0);
+    const frameRef = useRef(0);
     const states = animation?.states;
     const oneShots = animation?.oneShots;
     const authoredGraph = animation?.graph;
@@ -393,6 +434,17 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
                 return;
             playbackDelta = advancedSeconds - previousSeconds;
         }
+        // Distance tiers pose a far rig on fewer frames; the accumulated time keeps the clip at real
+        // speed, so a half-rate character walks the same distance, it just reaches its poses less often.
+        const interval = characterLodInterval(characterLodTierOf(instanceId));
+        if (interval === 0)
+            return;
+        pendingRef.current += playbackDelta;
+        frameRef.current += 1;
+        if (interval > 1 && frameRef.current % interval !== 0)
+            return;
+        playbackDelta = pendingRef.current;
+        pendingRef.current = 0;
         const playback = graphRef.current;
         if (playback !== null && mixerRef.current !== null) {
             const params = playback.params;
@@ -400,6 +452,8 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
                 const entity = ctx.scene.entity.get(instanceId);
                 if (entity !== null && playbackDelta > 0) {
                     const [x, , z] = entity.position;
+                    const yaw = entity.rotationY ?? 0;
+                    let step;
                     if (playback.lastPos !== null) {
                         const dx = x - playback.lastPos[0];
                         const dy = entity.position[1] - playback.lastPos[1];
@@ -411,11 +465,16 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
                         else {
                             const instantSpeed = Math.hypot(dx, dz) / playbackDelta;
                             playback.smoothedSpeed += (instantSpeed - playback.smoothedSpeed) * Math.min(1, playbackDelta * 12);
+                            step = { dx, dz, dyaw: playback.lastYaw === null ? 0 : shortestAngle(yaw - playback.lastYaw), seconds: playbackDelta };
                         }
                     }
                     playback.lastPos = [x, entity.position[1], z];
+                    playback.lastYaw = yaw;
+                    readModelAnimationParams(ctx, instanceId, playback.smoothedSpeed, params, step);
+                }
+                else {
+                    readModelAnimationParams(ctx, instanceId, playback.smoothedSpeed, params);
                 }
-                readModelAnimationParams(ctx, instanceId, playback.smoothedSpeed, params);
             }
             else {
                 for (const key in params)
@@ -426,6 +485,12 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             const out = playback.runtime.advance(playbackDelta * (animation?.timeScale ?? 1), params, playback.durations);
             applyGraphClips(playback.actions, out.clips);
             mixerRef.current.update(0);
+            if (instanceId !== undefined) {
+                noteCharacterPose(instanceId);
+                const phase = dominantPhase(out.clips);
+                if (phase !== undefined)
+                    noteAnimationPhase(instanceId, phase.clip, phase.time);
+            }
             if (out.rootMotion === true && playback.rootBone !== null && playback.rootBindPosition !== null) {
                 playback.rootBone.position.x = playback.rootBindPosition.x;
                 playback.rootBone.position.z = playback.rootBindPosition.z;
@@ -438,6 +503,10 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
         }
         if (mixerRef.current !== null && actionRef.current?.isRunning()) {
             mixerRef.current.update(playbackDelta);
+            if (instanceId !== undefined) {
+                noteCharacterPose(instanceId);
+                noteAnimationPhase(instanceId, actionRef.current.getClip().name, actionRef.current.time);
+            }
         }
     });
 }

package/dist/render/useModelInstance.d.ts

@@ -1,7 +1,7 @@
 import { Group, type Object3D } from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 /** Model loading, placement, shadows and animation for a custom renderer. */
-export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes" | "surfaceDetail">;
+export type ModelInstanceConfig = Pick<ModelConfig, "url" | "scale" | "targetHeight" | "y" | "anchor" | "dims" | "shadows" | "animation" | "hiddenNodes" | "surfaceDetail" | "wind" | "lod">;
 /** Caller-owned styling runs on the isolated clone, never the loader cache. */
 export interface ModelInstanceOptions {
     instanceId?: string;

package/dist/render/useModelInstance.js

@@ -2,9 +2,11 @@ import { useLoader, useThree } from "@react-three/fiber";
 import { useEffect, useMemo } from "react";
 import { Group } from "three";
 import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility";
+import { registerCharacterRig, unregisterCharacterRig } from "./characterLod.js";
 import { measureLocalBounds } from "./measureBounds.js";
 import { detectKtx2Support, sharedGltfLoader } from "./modelLoad.js";
 import { cloneModelScene, disposeModelScene, modelPlacementTransform } from "./modelRender.js";
+import { applyModelWindToScene } from "./modelWind.js";
 import { useModelAnimation } from "./useModelAnimation.js";
 import { applyModelNodeVisibility, modelHiddenNodesKey } from "./modelNodeVisibility.js";
 /**
@@ -26,6 +28,7 @@ export function useModelInstance(model, options = {}) {
         const content = cloneModelScene(gltf.scene, { shadows: model.shadows, surfaceDetail: model.surfaceDetail });
         try {
             configure?.(content);
+            applyModelWindToScene(content, model.wind, model.wind === false || model.wind === undefined ? 4 : model.wind.height ?? 4);
             for (const diagnostic of applyModelNodeVisibility(content, hiddenNodes))
                 console.warn(`Model ${model.url} hiddenNodes: ${diagnostic.message}`);
             const scene = new Group().add(content);
@@ -35,9 +38,31 @@ export function useModelInstance(model, options = {}) {
             disposeModelScene(content);
             throw error;
         }
-    }, [gltf.scene, model.shadows, model.surfaceDetail, configure, hiddenNodesKey]);
+    }, [gltf.scene, model.shadows, model.surfaceDetail, model.wind, configure, hiddenNodesKey]);
     const placement = useMemo(() => modelPlacementTransform(scene, model, bindBounds), [scene, bindBounds, model.scale, model.targetHeight, model.y, model.anchor, model.dims]);
     useEffect(() => () => disposeModelScene(content), [content]);
+    const lodKey = JSON.stringify(model.lod);
+    useEffect(() => {
+        if (instanceId === undefined)
+            return;
+        const [parts, bones] = countRig(content);
+        if (parts === 0)
+            return;
+        registerCharacterRig(instanceId, parts, bones);
+        return () => unregisterCharacterRig(instanceId);
+    }, [content, instanceId, lodKey]);
     useModelAnimation(content, gltf.animations, model.animation, instanceId);
     return { content, scene, ...placement };
 }
+/** Skinned parts and bones a mounted character renders, for the character-LOD probe. */
+function countRig(root) {
+    let parts = 0;
+    let bones = 0;
+    root.traverse((node) => {
+        if (node.isSkinnedMesh === true) {
+            parts += 1;
+            bones = Math.max(bones, node.skeleton.bones.length);
+        }
+    });
+    return [parts, bones];
+}

package/dist/render/useRagdoll.d.ts

@@ -0,0 +1,32 @@
+import * as THREE from "three";
+import type { SkeletonMap } from "@jgengine/core/anim/skeletonStandard";
+import type { PhysicsWorld } from "@jgengine/core/physics/physicsWorld";
+/** What {@link useRagdoll} needs: the rig's bone names, the physics world and what arms it. */
+export interface RagdollOptions {
+    /** The rig's bone names by standard slot, from `mapRigToStandard` on the loaded scene's bones. */
+    map: SkeletonMap;
+    /**
+     * The physics world the bodies live in. It is stepped by this hook, so give the ragdoll its own
+     * world (a private one per dead character) rather than a world shared with live physics. Its
+     * bounds' lower Y is the floor the body lands on.
+     */
+    world: PhysicsWorld;
+    /** Arm the ragdoll. On the false → true edge the rig's current world poses become the bodies. */
+    active: boolean;
+    /** Character height in metres, so body shapes scale. Default 1.8. */
+    height?: number;
+}
+/**
+ * Turns a rigged character into a physics ragdoll when `active` goes true: the bones' world poses at
+ * that moment become box bodies joined by distance links in `world`, and every frame after, each
+ * bone's world position and aim come from its body. The physics bodies carry translation only, so
+ * each bone is oriented by rotating its death-pose direction-to-child onto the current one, which is
+ * what gives the body a skeleton instead of a pile of boxes.
+ *
+ * While the ragdoll is active it owns the mapped bones, so stop the model's IK for the same
+ * character (`ModelConfig.ik` unset) or the two write the same joints. Deactivating removes the
+ * bodies and leaves the rig where the ragdoll put it.
+ *
+ * @capability animation turn a killed rigged character into a physics ragdoll on death
+ */
+export declare function useRagdoll(scene: THREE.Object3D, options: RagdollOptions): void;

package/dist/render/useRagdoll.js

@@ -0,0 +1,105 @@
+import { useFrame } from "@react-three/fiber";
+import { useEffect, useRef } from "react";
+import * as THREE from "three";
+import { ragdollBoneOrientations, ragdollConfigFromPoses } from "@jgengine/core/anim/ragdollRig";
+import { createRagdoll } from "@jgengine/core/physics/ragdoll";
+import { resolveRigNode } from "./rigNode.js";
+const REFERENCE_HEIGHT = 1.8;
+/**
+ * Turns a rigged character into a physics ragdoll when `active` goes true: the bones' world poses at
+ * that moment become box bodies joined by distance links in `world`, and every frame after, each
+ * bone's world position and aim come from its body. The physics bodies carry translation only, so
+ * each bone is oriented by rotating its death-pose direction-to-child onto the current one, which is
+ * what gives the body a skeleton instead of a pile of boxes.
+ *
+ * While the ragdoll is active it owns the mapped bones, so stop the model's IK for the same
+ * character (`ModelConfig.ik` unset) or the two write the same joints. Deactivating removes the
+ * bodies and leaves the rig where the ragdoll put it.
+ *
+ * @capability animation turn a killed rigged character into a physics ragdoll on death
+ */
+export function useRagdoll(scene, options) {
+    const { map, world, active, height = REFERENCE_HEIGHT } = options;
+    const ragdollRef = useRef(null);
+    const posesRef = useRef([]);
+    const bonesRef = useRef({});
+    useEffect(() => {
+        const bones = {};
+        for (const slot of Object.keys(map.slots)) {
+            const name = map.slots[slot];
+            if (name === undefined)
+                continue;
+            const node = resolveRigNode(scene, name).node;
+            if (node !== undefined)
+                bones[slot] = node;
+        }
+        bonesRef.current = bones;
+        return () => {
+            bonesRef.current = {};
+        };
+    }, [scene, map]);
+    useEffect(() => {
+        if (!active)
+            return;
+        scene.updateMatrixWorld(true);
+        const positions = [];
+        const worldPosition = new THREE.Vector3();
+        const worldQuaternion = new THREE.Quaternion();
+        for (const slot of Object.keys(bonesRef.current)) {
+            const bone = bonesRef.current[slot];
+            if (bone === undefined)
+                continue;
+            bone.getWorldPosition(worldPosition);
+            bone.getWorldQuaternion(worldQuaternion);
+            positions.push({
+                slot,
+                position: [worldPosition.x, worldPosition.y, worldPosition.z],
+                orientation: [worldQuaternion.x, worldQuaternion.y, worldQuaternion.z, worldQuaternion.w],
+            });
+        }
+        if (positions.length < 2)
+            return;
+        posesRef.current = positions;
+        ragdollRef.current = createRagdoll(world, ragdollConfigFromPoses(map, positions, { scale: height / REFERENCE_HEIGHT }));
+        return () => {
+            ragdollRef.current?.remove();
+            for (const id of Object.values(ragdollRef.current?.bones ?? {}))
+                world.removeBody(id);
+            ragdollRef.current = null;
+            posesRef.current = [];
+        };
+    }, [active, scene, map, world, height]);
+    useFrame((_state, delta) => {
+        const ragdoll = ragdollRef.current;
+        if (ragdoll === null || delta <= 0)
+            return;
+        world.step(delta);
+        const positions = {};
+        for (const [slot, id] of Object.entries(ragdoll.bones)) {
+            positions[slot] = [world.posX[id], world.posY[id], world.posZ[id]];
+        }
+        const orientations = ragdollBoneOrientations(posesRef.current, positions);
+        const worldPosition = new THREE.Vector3();
+        const worldQuaternion = new THREE.Quaternion();
+        const parentQuaternion = new THREE.Quaternion();
+        for (const [slot, id] of Object.entries(ragdoll.bones)) {
+            const bone = bonesRef.current[slot];
+            const orientation = orientations[slot];
+            if (bone === undefined || orientation === undefined)
+                continue;
+            worldPosition.set(world.posX[id], world.posY[id], world.posZ[id]);
+            worldQuaternion.set(orientation[0], orientation[1], orientation[2], orientation[3]);
+            const parent = bone.parent;
+            if (parent === null) {
+                bone.position.copy(worldPosition);
+                bone.quaternion.copy(worldQuaternion);
+            }
+            else {
+                parent.updateWorldMatrix(true, false);
+                bone.position.copy(parent.worldToLocal(worldPosition));
+                bone.quaternion.copy(parent.getWorldQuaternion(parentQuaternion).invert().multiply(worldQuaternion));
+            }
+            bone.updateMatrixWorld(true);
+        }
+    });
+}

package/dist/scatter/scatterModels.js

@@ -3,6 +3,7 @@ import { parseModelHiddenNodes } from "@jgengine/core/editor/modelNodeVisibility
 import { applyMaterialOverride } from "../materialOverride.js";
 import { cloneModelScene, disposeModelScene, ownModelMaterial } from "../render/modelRender.js";
 import { applyModelSurface } from "../render/modelSurface.js";
+import { applyModelWindToScene } from "../render/modelWind.js";
 /** The scale + position offset a `ModelConfig` applies before any per-instance transform — same anchor/targetHeight rules as the single-instance entity renderer. */
 function scatterModelBaseTransform(scene, model) {
     let scale = model.scale ?? 1;
@@ -43,6 +44,7 @@ export function buildScatterModelSources(gltfScene, model) {
         throw new Error("Instanced model override maps require an owned texture loader; use EntityModel for authored maps");
     applyModelSurface(gltfScene);
     const root = cloneModelScene(gltfScene, { shadows: model.shadows, surfaceDetail: model.surfaceDetail });
+    applyModelWindToScene(root, model.wind, model.dims?.maxY ?? model.targetHeight ?? 4);
     if (model.material !== undefined)
         applyMaterialOverride(root, model.material, { clone: false, ownMaterial: material => ownModelMaterial(root, material) });
     root.updateMatrixWorld(true);

package/dist/scene/DecalRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `decal` marker renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerDecalRenderer(): void;

package/dist/scene/DecalRenderer.js

@@ -0,0 +1,74 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { resolveDecalObject } from "@jgengine/core/world/decalKind";
+import { createDecalDrapeGeometry } from "../render/decalGeometry.js";
+import { createDecalTexture } from "../render/decalTexture.js";
+import { useDisposable } from "../render/useDisposable.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Tilts at or above this stand the decal up on a wall instead of draping it on the ground. */
+const WALL_TILT = 45;
+function dataTexture(style, seed) {
+    const baked = createDecalTexture(style, seed);
+    const texture = new THREE.DataTexture(baked.data, baked.size, baked.size, THREE.RGBAFormat, THREE.UnsignedByteType);
+    texture.colorSpace = THREE.SRGBColorSpace;
+    texture.magFilter = THREE.LinearFilter;
+    texture.minFilter = THREE.LinearMipmapLinearFilter;
+    texture.generateMipmaps = true;
+    texture.wrapS = THREE.ClampToEdgeWrapping;
+    texture.wrapT = THREE.ClampToEdgeWrapping;
+    texture.needsUpdate = true;
+    return texture;
+}
+function OneDecal({ object, context }) {
+    const resolved = useMemo(() => resolveDecalObject(object), [object]);
+    const rules = resolved?.rules;
+    const style = rules?.style ?? "dirt";
+    const seed = rules?.seed ?? "";
+    const texture = useDisposable(() => dataTexture(style, seed), [style, seed]);
+    const wall = (rules?.tilt ?? 0) >= WALL_TILT;
+    const geometry = useDisposable(() => {
+        if (resolved === null || rules === undefined)
+            return new THREE.BufferGeometry();
+        if (wall)
+            return new THREE.PlaneGeometry(rules.size, rules.size);
+        const draped = createDecalDrapeGeometry({
+            size: rules.size,
+            rotationY: resolved.rotationY,
+            heightAt: context.field.sampleHeight,
+            lift: rules.lift,
+        });
+        const next = new THREE.BufferGeometry();
+        next.setAttribute("position", new THREE.BufferAttribute(draped.positions, 3));
+        next.setAttribute("normal", new THREE.BufferAttribute(draped.normals, 3));
+        next.setAttribute("uv", new THREE.BufferAttribute(draped.uvs, 2));
+        next.setIndex(new THREE.BufferAttribute(draped.indices, 1));
+        next.computeBoundingSphere();
+        return next;
+    }, [resolved, rules, wall, context.field]);
+    const material = useDisposable(() => new THREE.MeshStandardMaterial({
+        map: texture,
+        transparent: true,
+        depthWrite: false,
+        opacity: rules?.opacity ?? 1,
+        roughness: 0.92,
+        metalness: 0,
+        polygonOffset: true,
+        polygonOffsetFactor: -4,
+        polygonOffsetUnits: -4,
+    }), [texture, rules?.opacity]);
+    if (resolved === null || rules === undefined)
+        return null;
+    const [px, py, pz] = resolved.position;
+    if (!wall) {
+        return _jsx("mesh", { geometry: geometry, material: material, position: [px, py, pz], receiveShadow: true, frustumCulled: true });
+    }
+    // A standing decal is pushed out along its own normal so it clears the wall it describes.
+    const normalX = Math.sin(resolved.rotationY);
+    const normalZ = Math.cos(resolved.rotationY);
+    return (_jsx("mesh", { geometry: geometry, material: material, position: [px + normalX * rules.offset, py + rules.lift, pz + normalZ * rules.offset], rotation: [THREE.MathUtils.degToRad(rules.tilt - 90), resolved.rotationY, 0], receiveShadow: true, frustumCulled: true }));
+}
+/** Registers the `decal` marker renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerDecalRenderer() {
+    registerSceneKindRenderer("decal", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneDecal, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/GrassFieldRenderer.js

@@ -1,9 +1,10 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useMemo } from "react";
 import { resolveGrassObject } from "@jgengine/core/world/grassKind";
 import { clearanceMasksFrom, DEFAULT_CLEARANCE_KINDS } from "@jgengine/core/world/scatterRegion";
 import { masksInfluence } from "@jgengine/core/world/geometry";
 import { GrassField } from "../terrain/GrassField.js";
+import { GrassCover } from "../terrain/GrassCover.js";
 import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
 /** Volume kinds turf yields to — blades never grow through cracked soil or out of open water. */
 const GRASS_YIELDS_TO = new Set(["soil", "water"]);
@@ -86,7 +87,7 @@ function OneGrass({ object, context }) {
     // footprint, and the fade only thins how many *draw* at range in the vertex shader — so a deeper
     // meadow reads expansive without raising the instance ceiling.
     const instanceCount = Math.max(1500, Math.min(250000, Math.ceil(rules.density * area[0] * area[1])));
-    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude }));
+    return (_jsxs(_Fragment, { children: [_jsx(GrassCover, { position: [center[0], center[1], center[2]], area: area, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), colorBase: rules.colorBase, colorTip: rules.colorTip, strength: rules.groundCover, edgeFeather: 2.2, heightAt: heightAt, coverageAt: coverageAt }), _jsx(GrassField, { position: [center[0], center[1], center[2]], area: area, count: instanceCount, density: rules.density, bladeHeight: bladeHeight, bladeWidth: bladeWidth, bladeBend: bladeBend, tuftRadius: rules.tuftRadius, normalLift: rules.normalLift, colorBase: rules.colorBase, colorTip: rules.colorTip, colorGround: context.groundColorAt?.(center[0], center[2]), colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: heightAt, coverageAt: coverageAt, wind: wind, edgeFeather: 2.2, exclude: exclude })] }));
 }
 /** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
 export function registerGrassFieldRenderer() {

package/dist/scene/builtinSceneKindRenderers.js

@@ -11,6 +11,7 @@ import { registerWaterRenderer } from "./WaterRenderer.js";
 import { registerSoilPatchRenderer } from "./SoilPatchRenderer.js";
 import { registerCityRenderer } from "./CityRenderer.js";
 import { registerPoleLineRenderer } from "./PoleLineRenderer.js";
+import { registerDecalRenderer } from "./DecalRenderer.js";
 let registered = false;
 /** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
 export function registerBuiltinSceneKindRenderers() {
@@ -23,4 +24,5 @@ export function registerBuiltinSceneKindRenderers() {
     registerSoilPatchRenderer();
     registerCityRenderer();
     registerPoleLineRenderer();
+    registerDecalRenderer();
 }

package/dist/settings/SettingsMenu.d.ts

@@ -1,4 +1,4 @@
-import { type SettingsController } from "./settingsController.js";
+import type { SettingsController } from "./settingsController.js";
 export declare function SettingsMenu({ controller, onClose, initialTab, }: {
     controller: SettingsController;
     onClose: () => void;

package/dist/settings/SettingsMenu.js

@@ -1,64 +1,23 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { ScrollRail } from "@jgengine/react/scrollRail";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
 import { useDialogBehavior } from "@jgengine/react/dialogBehavior";
-import { useDebouncedCommit } from "@jgengine/react/useDebouncedCommit";
-import {} from "./settingsController.js";
+import { ScrollRail } from "@jgengine/react/scrollRail";
+import { SettingsSection } from "@jgengine/react/settingsBlocks";
 const surface = "var(--jg-surface, #16161d)";
 const surfaceDeep = "var(--jg-surface-deep, #0b0b11)";
 const edge = "var(--jg-edge, #2b2b35)";
 const text = "var(--jg-text, #ececef)";
 const textDim = "var(--jg-text-dim, #9494a0)";
 const accent = "var(--jg-accent, #6ee7a8)";
-const accentGlow = "var(--jg-accent-glow, rgba(110,231,168,0.35))";
 const onAccent = "var(--jg-surface-deep, #0b0b0f)";
 const danger = "var(--jg-danger, #e0574e)";
 const fontDisplay = "var(--jg-font-display, inherit)";
-const rowStyle = { background: "rgba(255,255,255,0.045)", border: "1px solid rgba(255,255,255,0.08)" };
-const badgeStyle = { background: surfaceDeep, border: "1px solid rgba(255,255,255,0.12)", color: text };
 function GlyphClose() {
     return (_jsx("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", className: "h-4 w-4", "aria-hidden": true, children: _jsx("path", { d: "M6 6l12 12M18 6L6 18" }) }));
 }
-function GlyphReset() {
-    return (_jsxs("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", className: "h-3.5 w-3.5", "aria-hidden": true, children: [_jsx("path", { d: "M3 12a9 9 0 1 0 3-6.7L3 8" }), _jsx("path", { d: "M3 3v5h5" })] }));
-}
 function CloseButton({ onClose }) {
     return (_jsx("button", { type: "button", onClick: onClose, "aria-label": "Close settings", className: "flex h-9 w-9 shrink-0 items-center justify-center rounded-lg transition hover:bg-white/10", style: { color: textDim, border: "1px solid rgba(255,255,255,0.1)" }, children: _jsx(GlyphClose, {}) }));
 }
-function RowShell({ label, control }) {
-    return (_jsxs("div", { className: "flex items-center justify-between gap-4 rounded-xl px-3.5 py-3", style: rowStyle, children: [_jsx("span", { className: "text-sm", style: { color: text }, children: label }), control] }));
-}
-function SliderRow({ row }) {
-    // Mirror the thumb + readout locally; debounce the persisting `set` so a drag doesn't storm the
-    // settings store (and any graphics rebuild it drives), flushing on release/blur (#1372).
-    const { value: local, onInput, flush } = useDebouncedCommit(Number(row.value), (next) => row.set(next));
-    const readout = row.format?.(local) ?? String(local);
-    return (_jsx(RowShell, { label: row.label, control: _jsxs("div", { className: "flex flex-1 items-center gap-3 pl-4", children: [_jsx("input", { type: "range", min: row.min, max: row.max, step: row.step, value: local, "aria-label": row.label, className: "h-1.5 flex-1 cursor-pointer", style: { accentColor: accent }, onChange: (event) => onInput(Number(event.target.value)), onPointerUp: flush, onKeyUp: flush, onBlur: flush }), _jsx("span", { className: "w-12 shrink-0 text-right text-sm tabular-nums", style: { color: text }, children: readout })] }) }));
-}
-function ToggleRow({ row }) {
-    const on = Boolean(row.value);
-    return (_jsx(RowShell, { label: row.label, control: _jsx("button", { type: "button", role: "switch", "aria-checked": on, "aria-label": row.label, onClick: () => row.set(!on), className: "relative h-7 w-12 shrink-0 rounded-full transition", style: { background: on ? accent : "rgba(255,255,255,0.16)", boxShadow: on ? `0 0 12px ${accentGlow}` : "none" }, children: _jsx("span", { className: `absolute top-1 h-5 w-5 rounded-full bg-white shadow transition-all ${on ? "left-6" : "left-1"}` }) }) }));
-}
-function SelectRow({ row }) {
-    const options = row.options ?? [];
-    const current = String(row.value);
-    return (_jsx(RowShell, { label: row.label, control: _jsx("div", { role: "group", "aria-label": row.label, className: "flex flex-wrap justify-end gap-1 rounded-lg p-1", style: { background: surfaceDeep }, children: options.map((option) => {
-                const selected = option.value === current;
-                return (_jsx("button", { type: "button", onClick: () => row.set(option.value), "aria-pressed": selected, className: "min-h-[34px] rounded-md px-3 text-sm font-medium transition", style: selected ? { background: accent, color: onAccent } : { color: textDim }, children: option.label }, option.value));
-            }) }) }));
-}
-function RowControl({ row }) {
-    if (row.kind === "slider")
-        return _jsx(SliderRow, { row: row });
-    if (row.kind === "toggle")
-        return _jsx(ToggleRow, { row: row });
-    return _jsx(SelectRow, { row: row });
-}
-function KeybindRowView({ row, capturing, onCapture, }) {
-    return (_jsxs("div", { className: "flex items-center justify-between gap-3 rounded-xl px-3.5 py-3", style: rowStyle, children: [_jsx("span", { className: "text-sm", style: { color: text }, children: row.label }), _jsxs("div", { className: "flex shrink-0 items-center gap-2", children: [_jsx("button", { type: "button", onClick: onCapture, disabled: capturing, title: "Click to rebind \u2014 Esc to cancel", className: "inline-flex min-h-[34px] min-w-[3.75rem] items-center justify-center rounded-lg px-3 font-mono text-sm transition hover:brightness-125", style: capturing
-                            ? { background: accentGlow, color: accent, border: `1px solid ${accent}` }
-                            : badgeStyle, children: capturing ? "Press…" : row.bindingLabel }), _jsx("button", { type: "button", onClick: () => row.reset(), "aria-label": `Reset ${row.label}`, title: "Reset to default", className: `flex h-8 w-8 items-center justify-center rounded-lg transition hover:bg-white/10 ${row.isDefault ? "invisible" : ""}`, style: { color: textDim }, children: _jsx(GlyphReset, {}) })] })] }));
-}
 function ActionRow({ action, onClose }) {
     const isDanger = action.kind === "danger";
     return (_jsxs("button", { type: "button", onClick: () => {
@@ -72,10 +31,10 @@ function ActionRow({ action, onClose }) {
 function TabButton({ tab, selected, orientation, onSelect }) {
     return (_jsx("button", { type: "button", onClick: onSelect, className: `shrink-0 min-h-[44px] whitespace-nowrap rounded-lg px-4 text-sm font-medium transition ${orientation === "col" ? "w-full text-left" : ""} ${selected ? "" : "hover:bg-white/5"}`, style: selected ? { background: accent, color: onAccent } : { color: textDim }, children: tab.label }));
 }
-function Body({ tab, actions, capturing, setCapturing, onClose }) {
+function Body({ tab, actions, onClose }) {
     return (_jsx("div", { className: "jg-settings-scroll min-h-0 flex-1 space-y-2 overflow-y-auto p-4", children: tab.category === null
             ? actions.map((action) => _jsx(ActionRow, { action: action, onClose: onClose }, action.id))
-            : (_jsxs(_Fragment, { children: [tab.category.rows.map((row) => (_jsx(RowControl, { row: row }, row.id))), tab.category.keybinds.map((row) => (_jsx(KeybindRowView, { row: row, capturing: capturing?.action === row.action, onCapture: () => setCapturing(row) }, row.action)))] })) }));
+            : _jsx(SettingsSection, { category: tab.category, heading: false }) }));
 }
 const panelStyle = {
     background: surface,
@@ -95,41 +54,13 @@ export function SettingsMenu({ controller, onClose, initialTab, }) {
         ...controller.categories.map((category) => ({ id: category.id, label: category.label, category })),
     ];
     const [activeId, setActiveId] = useState(initialTab !== undefined && tabs.some((tab) => tab.id === initialTab) ? initialTab : (tabs[0]?.id ?? ""));
-    const [capturing, setCapturing] = useState(null);
     const active = tabs.find((tab) => tab.id === activeId) ?? tabs[0] ?? null;
-    const dialogRef = useDialogBehavior({ open: active !== null, onClose: capturing === null ? onClose : undefined });
-    useEffect(() => {
-        if (capturing === null)
-            return;
-        const onKey = (event) => {
-            event.preventDefault();
-            event.stopPropagation();
-            if (event.code === "Escape") {
-                setCapturing(null);
-                return;
-            }
-            capturing.rebind(event.code);
-            setCapturing(null);
-        };
-        const onPointer = (event) => {
-            event.preventDefault();
-            event.stopPropagation();
-            capturing.rebind(`mouse${event.button}`);
-            setCapturing(null);
-        };
-        const onContext = (event) => event.preventDefault();
-        window.addEventListener("keydown", onKey, true);
-        window.addEventListener("pointerdown", onPointer, true);
-        window.addEventListener("contextmenu", onContext, true);
-        return () => {
-            window.removeEventListener("keydown", onKey, true);
-            window.removeEventListener("pointerdown", onPointer, true);
-            window.removeEventListener("contextmenu", onContext, true);
-        };
-    }, [capturing]);
+    // A keybind capture consumes Escape at the window, before the dialog's document listener, so close
+    // stays available without waiting for the capture state to re-render.
+    const dialogRef = useDialogBehavior({ open: active !== null, onClose });
     if (active === null)
         return null;
-    const bodyProps = { tab: active, actions: controller.actions, capturing, setCapturing, onClose };
+    const bodyProps = { tab: active, actions: controller.actions, onClose };
     const title = (_jsx("h2", { className: "text-base font-semibold tracking-wide", style: { color: text }, children: "Settings" }));
     if (controller.variant === "fullscreen") {
         return (_jsx("div", { ref: dialogRef, role: "dialog", "aria-modal": "true", "aria-label": "Settings", tabIndex: -1, className: "pointer-events-auto absolute inset-0 z-40 flex flex-col", style: { background: surface, color: text, fontFamily: fontDisplay }, children: _jsxs("div", { className: "mx-auto flex h-full w-full max-w-2xl flex-col px-4", children: [_jsxs("div", { className: "flex items-center justify-between gap-3 pb-4 pt-6", children: [_jsx("h2", { className: "text-2xl font-bold tracking-wide", style: { color: text }, children: "Settings" }), _jsx(CloseButton, { onClose: onClose })] }), _jsx(ScrollRail, { label: "settings categories", style: { paddingBottom: 16 }, children: tabs.map((tab) => (_jsx(TabButton, { tab: tab, selected: tab.id === active.id, orientation: "row", onSelect: () => setActiveId(tab.id) }, tab.id))) }), _jsx(Body, { ...bodyProps })] }) }));