@jgengine/shell 0.27.0 → 0.29.0

package/dist/render/useFootIk.js

@@ -134,6 +134,8 @@ export function resolveFootIkRig(scene, config) {
         legs,
         pelvis,
         head,
+        lookAtLimits: { ...(options.lookAt?.maxYaw === undefined ? {} : { maxYaw: options.lookAt.maxYaw }), ...(options.lookAt?.maxPitch === undefined ? {} : { maxPitch: options.lookAt.maxPitch }) },
+        lookAtWeight: Math.max(0, Math.min(1, options.lookAt?.weight ?? 1)),
         maxAdjust: options.maxAdjust ?? DEFAULT_MAX_ADJUST,
         alignToGround: Math.max(0, Math.min(1, options.alignToGround ?? 1)),
         poses: [...bones].map((bone) => ({
@@ -175,10 +177,11 @@ function restoreFootIkPose(rig) {
 /**
  * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
  * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
- * toward the animated knee, and tilts planted feet to the ground. Returns whether the feet are
- * grounded; `state` carries the faded weight between frames. Exported for tests and custom hosts.
+ * toward the animated knee, and tilts planted feet to the ground. Turns the look-at bone toward
+ * `lookAtTarget` when the rig has one. Returns whether the feet are grounded; `state` carries the
+ * faded weight between frames. Exported for tests and custom hosts.
  */
-export function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
+export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
     restoreFootIkPose(rig);
     for (const record of rig.poses) {
         record.animated.q.copy(record.bone.quaternion);
@@ -235,11 +238,12 @@ export function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
             writeWorldQuaternion(leg.tip, current.slerp(tilt.multiply(current), planted * weight * rig.alignToGround));
         }
     }
-    if (rig.head !== null && cameraTarget !== undefined) {
+    if (rig.head !== null && lookAtTarget !== undefined) {
         const from = rig.head.getWorldPosition(scratch.a);
-        const q = lookAt({ from: [from.x, from.y, from.z], target: cameraTarget, up: [0, 1, 0] });
+        const q = lookAt({ from: [from.x, from.y, from.z], target: lookAtTarget, up: [0, 1, 0], ...rig.lookAtLimits });
         const current = rig.head.getWorldQuaternion(scratch.q2);
-        writeWorldQuaternion(rig.head, current.slerp(scratch.q.set(q[0], q[1], q[2], q[3]), Math.max(weight, rig.legs.length === 0 ? 1 : 0)));
+        const reach = Math.max(weight, rig.legs.length === 0 ? 1 : 0) * rig.lookAtWeight;
+        writeWorldQuaternion(rig.head, current.slerp(scratch.q.set(q[0], q[1], q[2], q[3]), reach));
     }
     for (const record of rig.poses) {
         record.written.q.copy(record.bone.quaternion);
@@ -256,8 +260,11 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
     const camera = useThree((three) => three.camera);
     const rig = useMemo(() => (config === undefined ? null : resolveFootIkRig(scene, config)), [scene, config]);
     const state = useRef({ weight: 0, pelvis: 0 });
+    const lookAtConfig = config === undefined || config === "auto" ? undefined : config.lookAt;
+    const target = useRef(null);
     useLayoutEffect(() => {
         state.current = { weight: 0, pelvis: 0 };
+        target.current = null;
         return () => {
             if (rig !== null) {
                 restoreFootIkPose(rig);
@@ -271,11 +278,32 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
         const parent = scene.parent;
         const originY = parent === null ? scene.position.y : parent.localToWorld(scratch.a.set(0, groundOffset, 0)).y;
         const exclude = [instanceId];
+        const aim = resolveLookAtTarget(lookAtConfig?.target, ctx, target.current, lookAtConfig?.entityEyeHeight ?? DEFAULT_EYE_HEIGHT);
+        target.current = aim;
         applyFootIk(rig, originY, (input) => ctx.scene.raycast({
             ...input,
             excludeInstanceIds: exclude,
             filter: { entities: false, objects: true, walls: false, terrain: true },
             accept: (hit) => hit.blocks && hit.purpose === "physical",
-        }), state.current, delta, rig.head === null ? undefined : camera.getWorldPosition(scratch.b).toArray());
+        }), state.current, delta, aim === null ? camera.getWorldPosition(scratch.b).toArray() : [aim.x, aim.y, aim.z]);
     });
 }
+const DEFAULT_EYE_HEIGHT = 1.5;
+/**
+ * Where a look-at bone should aim this frame, or `null` when it aims at the camera. An entity
+ * target that is not spawned yet reuses `previous` rather than snapping back to the camera.
+ */
+function resolveLookAtTarget(spec, ctx, previous, eyeHeight) {
+    if (spec === undefined || spec === "camera")
+        return null;
+    if ("point" in spec) {
+        previous?.set(spec.point[0], spec.point[1], spec.point[2]);
+        return previous ?? new THREE.Vector3(spec.point[0], spec.point[1], spec.point[2]);
+    }
+    const entity = ctx.scene.entity.get(spec.entity);
+    if (entity === null || entity === undefined)
+        return previous;
+    const position = entity.position;
+    previous?.set(position[0], position[1] + eyeHeight, position[2]);
+    return previous ?? new THREE.Vector3(position[0], position[1] + eyeHeight, position[2]);
+}

package/dist/render/useModelAnimation.d.ts

@@ -13,14 +13,28 @@ export interface ModelAnimationDiagnostic {
  * @capability model-animation-diagnostics inspect imported clip mappings, layer masks and root-track compatibility
  */
 export declare function diagnoseModelAnimation(scene: THREE.Object3D, animation: ModelAnimationConfig, clips: readonly THREE.AnimationClip[]): readonly ModelAnimationDiagnostic[];
+/**
+ * One visual sample's measured motion, used to derive the directional locomotion parameters.
+ * `dx`/`dz` are world horizontal displacement since the previous sample, `dyaw` the yaw change in
+ * radians and `seconds` the time the sample covers.
+ */
+export interface ModelMotionStep {
+    dx: number;
+    dz: number;
+    dyaw: number;
+    seconds: number;
+}
 /**
  * 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 declare function readModelAnimationParams(ctx: GameContext, instanceId: string, speed: number, out: Record<string, AnimParamValue>): Record<string, AnimParamValue>;
+export declare function readModelAnimationParams(ctx: GameContext, instanceId: string, speed: number, out: Record<string, AnimParamValue>, step?: ModelMotionStep): Record<string, AnimParamValue>;
 /**
  * For a frame where a `rootMotion` state is current: pins the root bone's horizontal translation to
  * its bind pose, so the clip plays in place, and returns that step's root travel as a world-space

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" | "wind">;
+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,6 +2,7 @@ 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";
@@ -40,6 +41,28 @@ export function useModelInstance(model, options = {}) {
     }, [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/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 })] }) }));

package/dist/settings/settingsController.js

@@ -2,6 +2,7 @@ import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
 import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
 import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, GRAPHICS_POST_STAGES, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
 import { FRAME_RATE_LIMIT_DISPLAY, FRAME_RATE_LIMIT_OPTIONS } from "@jgengine/core/settings/frameRateLimit";
+import { accessibilitySettingRows } from "@jgengine/core/settings/accessibilitySettings";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANT_OPTIONS, TOUCH_STYLE_OPTIONS, } from "@jgengine/core/input/touchScheme";
 import { TOUCH_STYLE_AUTO, useSettingsRevision } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
@@ -11,6 +12,7 @@ const DEFAULT_CATEGORY_LABELS = {
     graphics: "Graphics",
     gameplay: "Gameplay",
     controls: "Controls",
+    accessibility: "Accessibility",
 };
 const percent = (value) => `${Math.round(value * 100)}%`;
 const TOUCH_STYLE_SELECT_OPTIONS = [
@@ -195,6 +197,7 @@ export function useSettingsCategories(config) {
         graphics: graphicsRows,
         gameplay: gameplayRows,
         controls: controlsRows,
+        accessibility: accessibilitySettingRows(store),
     };
     const builtInKeybinds = { controls: keybinds };
     const declaredLabels = new Map(config.categories.map((c) => [c.id, c.label]));