@jgengine/shell 0.27.0 → 0.29.0

package/dist/render/SceneWarmupGate.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useThree } from "@react-three/fiber";
+import { useEffect } from "react";
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { createShaderWarmup } from "./shaderWarmup.js";
+/** Warmup state before the gate has run, so the loading screen covers the very first frame. @internal */
+export const SCENE_WARMUP_PENDING = { phase: "waiting", rounds: 0, programs: 0, elapsedMs: 0 };
+/**
+ * Compiles the mounted scene's shaders behind the loading screen and reports progress to it.
+ * Mounted inside the canvas, after the world, so the first round sees the world's materials.
+ * @internal
+ */
+export function SceneWarmupGate({ onState }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    const camera = useThree((state) => state.camera);
+    useEffect(() => {
+        const warmup = createShaderWarmup({ renderer: gl, scene, camera, onState });
+        const unregister = devtools.probes.register("sceneWarmup", () => {
+            const state = warmup.state();
+            return `${state.phase}, ${state.rounds} rounds, ${state.programs} programs, ${state.elapsedMs}ms`;
+        });
+        return () => {
+            warmup.cancel();
+            unregister();
+        };
+    }, [gl, scene, camera, onState]);
+    return null;
+}
+/**
+ * Opaque cover over the canvas while the scene warms: the first frames of a scene compile its
+ * materials, and a player should not see those frames. Game UI and menus mount after this and
+ * paint over it, so a title screen stays usable.
+ * @internal
+ */
+export function SceneWarmupCover({ state }) {
+    if (state.phase === "ready" || state.phase === "failed")
+        return null;
+    return (_jsx("div", { "data-shell-code-loading": true, "data-shell-warmup": true, role: "status", "aria-live": "polite", style: {
+            position: "absolute",
+            inset: 0,
+            display: "grid",
+            placeItems: "center",
+            background: "#0f172a",
+            color: "#e2e8f0",
+            fontFamily: "ui-sans-serif, system-ui, sans-serif",
+        }, children: state.phase === "compiling" && state.programs > 0 ? `Preparing scene (${state.programs} shaders)` : "Preparing scene." }));
+}

package/dist/render/characterLod.d.ts

@@ -0,0 +1,62 @@
+import type { ModelLodConfig } from "@jgengine/core/game/playableGame";
+import type { SystemProbe } from "@jgengine/core/devtools/types";
+/** Distance policy a character model's {@link ModelLodConfig} resolves to; every distance is metres. */
+export interface CharacterLodPolicy {
+    fullRateDistance: number;
+    halfRateDistance: number;
+    crowdDistance: number;
+    crowdHysteresis: number;
+}
+/** The engine's default character tiers: full under 15 m, half under 40 m, GPU crowd beyond 25 m. */
+export declare const DEFAULT_CHARACTER_LOD: CharacterLodPolicy;
+/** What a character's distance from the camera costs it this frame. */
+export type CharacterLodTier = "full" | "half" | "quarter" | "crowd";
+/**
+ * Fills a model's authoring gaps with {@link DEFAULT_CHARACTER_LOD}. A missing, negative or
+ * non-finite distance falls back to the default rather than producing a tier that never matches.
+ * @internal
+ */
+export declare function characterLodPolicy(config: ModelLodConfig | undefined): CharacterLodPolicy;
+/**
+ * The tier a character at `distance` falls in. Passing the tier it held last frame applies the crowd
+ * hysteresis, so a character walking along the crowd boundary does not swap representation every frame.
+ */
+export declare function characterLodTier(distance: number, config: ModelLodConfig | undefined, previous?: CharacterLodTier): CharacterLodTier;
+/** Share of frames a tier poses the rig: 1, 0.5, 0.25, and 0 once the GPU crowd draws it. */
+export declare function characterLodRate(tier: CharacterLodTier): number;
+/** Frames between pose updates for a tier: 1, 2, 4, and `0` meaning "never" for the crowd tier. */
+export declare function characterLodInterval(tier: CharacterLodTier): number;
+/** Record a mounted character rig so the probe can report its parts and bones. @internal */
+export declare function registerCharacterRig(instanceId: string, parts: number, bones: number): void;
+/** Drop a character rig that unmounted. @internal */
+export declare function unregisterCharacterRig(instanceId: string): void;
+/** The tier the world marker decided this frame; the animation driver reads it instead of measuring distance twice. @internal */
+export declare function setCharacterLodTier(instanceId: string, tier: CharacterLodTier): void;
+/** Forget a tier when its marker unmounts. @internal */
+export declare function clearCharacterLodTier(instanceId: string): void;
+/** The tier a mounted character is on; full rate when nothing decided (previews, custom renderers). @internal */
+export declare function characterLodTierOf(instanceId: string | undefined): CharacterLodTier;
+/** Record one pose write (a mixer update) for a rig, in bones. @internal */
+export declare function noteCharacterPose(instanceId: string): void;
+/** Publish the clip and time a rig is posing at, so the crowd can continue the same pose at the swap. @internal */
+export declare function noteAnimationPhase(instanceId: string, clip: string, time: number): void;
+/** The clip phase a character was last posed at, or `undefined` when it never posed. @internal */
+export declare function animationPhaseOf(instanceId: string): {
+    clip: string;
+    time: number;
+} | undefined;
+/** Record how many crowd members each batch drew this frame. @internal */
+export declare function noteCrowdInstances(kind: string, count: number): void;
+/** Drop a crowd batch's instance count when it unmounts. @internal */
+export declare function clearCrowdKind(kind: string): void;
+/** Count one animated frame, so pose writes report as a per-frame average. @internal */
+export declare function noteCharacterFrame(): void;
+/** Clear every character counter. For tests and between capture runs. @internal */
+export declare function resetCharacterLodStats(): void;
+/**
+ * The character-LOD system probe: rigs by tier, skinned parts, and the bone pose writes per frame the
+ * distance tiers leave. Mounted by the world's crowd layer, so `debug_snapshot` names the cost a
+ * character change removed instead of leaving it to a profile.
+ * @internal
+ */
+export declare function characterLodProbe(): SystemProbe;

package/dist/render/characterLod.js

@@ -0,0 +1,165 @@
+/** The engine's default character tiers: full under 15 m, half under 40 m, GPU crowd beyond 25 m. */
+export const DEFAULT_CHARACTER_LOD = {
+    fullRateDistance: 15,
+    halfRateDistance: 40,
+    crowdDistance: 25,
+    crowdHysteresis: 2,
+};
+/**
+ * Fills a model's authoring gaps with {@link DEFAULT_CHARACTER_LOD}. A missing, negative or
+ * non-finite distance falls back to the default rather than producing a tier that never matches.
+ * @internal
+ */
+export function characterLodPolicy(config) {
+    const finite = (value, fallback) => value !== undefined && Number.isFinite(value) && value >= 0 ? value : fallback;
+    const policy = {
+        fullRateDistance: finite(config?.fullRateDistance, DEFAULT_CHARACTER_LOD.fullRateDistance),
+        halfRateDistance: finite(config?.halfRateDistance, DEFAULT_CHARACTER_LOD.halfRateDistance),
+        crowdDistance: finite(config?.crowdDistance, DEFAULT_CHARACTER_LOD.crowdDistance),
+        crowdHysteresis: finite(config?.crowdHysteresis, DEFAULT_CHARACTER_LOD.crowdHysteresis),
+    };
+    // Tiers read in order, so a game that sets half below full would otherwise make "full" unreachable.
+    policy.halfRateDistance = Math.max(policy.halfRateDistance, policy.fullRateDistance);
+    return policy;
+}
+/**
+ * The tier a character at `distance` falls in. Passing the tier it held last frame applies the crowd
+ * hysteresis, so a character walking along the crowd boundary does not swap representation every frame.
+ */
+export function characterLodTier(distance, config, previous) {
+    const policy = characterLodPolicy(config);
+    const crowdBoundary = previous === "crowd" ? policy.crowdDistance - policy.crowdHysteresis : policy.crowdDistance;
+    if (distance >= crowdBoundary)
+        return "crowd";
+    if (distance < policy.fullRateDistance)
+        return "full";
+    if (distance < policy.halfRateDistance)
+        return "half";
+    return "quarter";
+}
+/** Share of frames a tier poses the rig: 1, 0.5, 0.25, and 0 once the GPU crowd draws it. */
+export function characterLodRate(tier) {
+    switch (tier) {
+        case "full":
+            return 1;
+        case "half":
+            return 0.5;
+        case "quarter":
+            return 0.25;
+        case "crowd":
+            return 0;
+    }
+}
+/** Frames between pose updates for a tier: 1, 2, 4, and `0` meaning "never" for the crowd tier. */
+export function characterLodInterval(tier) {
+    const rate = characterLodRate(tier);
+    return rate === 0 ? 0 : Math.round(1 / rate);
+}
+const rigs = new Map();
+const tiers = new Map();
+const phases = new Map();
+let poseWrites = 0;
+let poses = 0;
+let frames = 0;
+const crowdInstances = new Map();
+/** Record a mounted character rig so the probe can report its parts and bones. @internal */
+export function registerCharacterRig(instanceId, parts, bones) {
+    rigs.set(instanceId, { parts, bones });
+}
+/** Drop a character rig that unmounted. @internal */
+export function unregisterCharacterRig(instanceId) {
+    rigs.delete(instanceId);
+    tiers.delete(instanceId);
+    phases.delete(instanceId);
+}
+/** The tier the world marker decided this frame; the animation driver reads it instead of measuring distance twice. @internal */
+export function setCharacterLodTier(instanceId, tier) {
+    tiers.set(instanceId, tier);
+}
+/** Forget a tier when its marker unmounts. @internal */
+export function clearCharacterLodTier(instanceId) {
+    tiers.delete(instanceId);
+}
+/** The tier a mounted character is on; full rate when nothing decided (previews, custom renderers). @internal */
+export function characterLodTierOf(instanceId) {
+    return instanceId === undefined ? "full" : tiers.get(instanceId) ?? "full";
+}
+/** Record one pose write (a mixer update) for a rig, in bones. @internal */
+export function noteCharacterPose(instanceId) {
+    const rig = rigs.get(instanceId);
+    if (rig === undefined)
+        return;
+    poseWrites += rig.bones;
+    poses += 1;
+}
+/** Publish the clip and time a rig is posing at, so the crowd can continue the same pose at the swap. @internal */
+export function noteAnimationPhase(instanceId, clip, time) {
+    phases.set(instanceId, { clip, time });
+}
+/** The clip phase a character was last posed at, or `undefined` when it never posed. @internal */
+export function animationPhaseOf(instanceId) {
+    return phases.get(instanceId);
+}
+/** Record how many crowd members each batch drew this frame. @internal */
+export function noteCrowdInstances(kind, count) {
+    crowdInstances.set(kind, count);
+}
+/** Drop a crowd batch's instance count when it unmounts. @internal */
+export function clearCrowdKind(kind) {
+    crowdInstances.delete(kind);
+}
+/** Count one animated frame, so pose writes report as a per-frame average. @internal */
+export function noteCharacterFrame() {
+    frames += 1;
+}
+/** Clear every character counter. For tests and between capture runs. @internal */
+export function resetCharacterLodStats() {
+    rigs.clear();
+    tiers.clear();
+    phases.clear();
+    poseWrites = 0;
+    poses = 0;
+    frames = 0;
+    crowdInstances.clear();
+}
+function readCharacterLod() {
+    const counts = { full: 0, half: 0, quarter: 0, crowd: 0 };
+    let parts = 0;
+    let bones = 0;
+    for (const [id, rig] of rigs) {
+        parts += rig.parts;
+        bones += rig.bones;
+        counts[tiers.get(id) ?? "full"] += 1;
+    }
+    const boneWrites = frames === 0 ? 0 : Math.round(poseWrites / frames);
+    let crowd = 0;
+    for (const count of crowdInstances.values())
+        crowd += count;
+    return {
+        counters: {
+            rigs: rigs.size,
+            skinnedParts: parts,
+            bones,
+            boneWritesPerFrame: boneWrites,
+            poses,
+            crowdInstances: crowd,
+            fullRate: counts.full,
+            halfRate: counts.half,
+            quarterRate: counts.quarter,
+            crowdRate: counts.crowd,
+        },
+        line: `${rigs.size} rigs · ${parts} skinned parts · ${boneWrites}/${bones} bone writes/frame · crowd ${crowd}`,
+    };
+}
+/**
+ * The character-LOD system probe: rigs by tier, skinned parts, and the bone pose writes per frame the
+ * distance tiers leave. Mounted by the world's crowd layer, so `debug_snapshot` names the cost a
+ * character change removed instead of leaving it to a profile.
+ * @internal
+ */
+export function characterLodProbe() {
+    return {
+        counters: () => readCharacterLod().counters,
+        state: () => readCharacterLod().line,
+    };
+}

package/dist/render/crowdRegistry.d.ts

@@ -0,0 +1,48 @@
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
+/** One character the GPU crowd path is drawing instead of its own rig. @internal */
+export interface CrowdMember {
+    x: number;
+    y: number;
+    z: number;
+    rotationY: number;
+    /** Ground speed in metres per second, which picks the crowd's idle/walk/run clip. */
+    speed: number;
+}
+/**
+ * The identity a character model shares with every other model the GPU crowd can draw: rig url,
+ * height normalization and material tint. Two entity kinds with the same key can share one instanced
+ * draw; a different tint or height needs its own.
+ */
+export declare function crowdKindOf(model: ModelConfig): string;
+/** Whether a model can leave its own rig for the GPU crowd path: a rigged, clip-played, plain model. */
+export declare function crowdEligible(model: ModelConfig | undefined): model is ModelConfig;
+/**
+ * The clips a crowd batch bakes for a model: its resolved idle, walk and run, in that order. Empty
+ * when the rig's clip names do not resolve to locomotion roles, which leaves the character on its own
+ * rig instead of drawing a frozen crowd copy.
+ */
+export declare function crowdClipsOf(model: ModelConfig, clipNames: readonly string[]): string[];
+/** The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf} orders them. */
+export declare function crowdClipForSpeed(clips: readonly string[], speed: number): string | undefined;
+/** Mark a crowd batch drawable, so markers may hand it characters. @internal */
+export declare function setCrowdKindReady(kind: string, ready: boolean): void;
+/** Whether a character kind has a crowd batch that can draw it. @internal */
+export declare function crowdKindReady(kind: string): boolean;
+/**
+ * The characters the crowd layer is currently drawing, written by their entity markers each frame.
+ * It holds poses rather than React state: 71 pedestrians writing matrices must not re-render the
+ * world, and the crowd batch reads the same entries back to fill its instance buffers.
+ */
+export declare class CharacterCrowdRegistry {
+    private readonly members;
+    /** Record the pose an entity is showing as a crowd instance this frame. */
+    set(id: string, kind: string, member: CrowdMember): void;
+    /** The entity went back to its own rig, or unmounted. */
+    delete(id: string): void;
+    /** How many characters this kind is drawing; zero means the batch can skip its work. */
+    count(kind: string): number;
+    /** Visit every character of one kind, in insertion order. */
+    forEach(kind: string, visit: (id: string, member: CrowdMember) => void): void;
+    /** Drop every entry; called when the crowd layer unmounts. */
+    clear(): void;
+}

package/dist/render/crowdRegistry.js

@@ -0,0 +1,97 @@
+import { resolveAnimationConfig } from "@jgengine/core/game/clipRoles";
+/** Below this ground speed a crowd character idles; a walk until the run speed. */
+const WALK_CLIP_SPEED = 0.25;
+const RUN_CLIP_SPEED = 2.6;
+/**
+ * The identity a character model shares with every other model the GPU crowd can draw: rig url,
+ * height normalization and material tint. Two entity kinds with the same key can share one instanced
+ * draw; a different tint or height needs its own.
+ */
+export function crowdKindOf(model) {
+    return `${model.url}\u0000${model.targetHeight ?? 0}\u0000${model.scale ?? 1}\u0000${JSON.stringify(model.material ?? null)}`;
+}
+/** Whether a model can leave its own rig for the GPU crowd path: a rigged, clip-played, plain model. */
+export function crowdEligible(model) {
+    if (model === undefined || model.lod === false)
+        return false;
+    if (model.ik !== undefined || model.attachments !== undefined || model.parts !== undefined)
+        return false;
+    return model.animation !== undefined && model.animation !== "none";
+}
+/**
+ * The clips a crowd batch bakes for a model: its resolved idle, walk and run, in that order. Empty
+ * when the rig's clip names do not resolve to locomotion roles, which leaves the character on its own
+ * rig instead of drawing a frozen crowd copy.
+ */
+export function crowdClipsOf(model, clipNames) {
+    const animation = resolveAnimationConfig(model.animation, clipNames);
+    const states = animation?.states;
+    const clips = [];
+    for (const name of [states?.idle, states?.walk, states?.run]) {
+        if (typeof name === "string" && name.length > 0 && clipNames.includes(name) && !clips.includes(name))
+            clips.push(name);
+    }
+    return clips;
+}
+/** The baked clip a crowd member at `speed` plays; clips are `[idle, walk, run]` as {@link crowdClipsOf} orders them. */
+export function crowdClipForSpeed(clips, speed) {
+    if (clips.length === 0)
+        return undefined;
+    if (speed >= RUN_CLIP_SPEED)
+        return clips[2] ?? clips[1] ?? clips[0];
+    if (speed >= WALK_CLIP_SPEED)
+        return clips[1] ?? clips[0];
+    return clips[0];
+}
+/** Kind keys whose crowd batch has a baked rig and can draw; a character stays on its own rig until then. @internal */
+const readyKinds = new Set();
+/** Mark a crowd batch drawable, so markers may hand it characters. @internal */
+export function setCrowdKindReady(kind, ready) {
+    if (ready)
+        readyKinds.add(kind);
+    else
+        readyKinds.delete(kind);
+}
+/** Whether a character kind has a crowd batch that can draw it. @internal */
+export function crowdKindReady(kind) {
+    return readyKinds.has(kind);
+}
+/**
+ * The characters the crowd layer is currently drawing, written by their entity markers each frame.
+ * It holds poses rather than React state: 71 pedestrians writing matrices must not re-render the
+ * world, and the crowd batch reads the same entries back to fill its instance buffers.
+ */
+export class CharacterCrowdRegistry {
+    members = new Map();
+    /** Record the pose an entity is showing as a crowd instance this frame. */
+    set(id, kind, member) {
+        const existing = this.members.get(id);
+        if (existing !== undefined && existing.kind === kind) {
+            Object.assign(existing.member, member);
+            return;
+        }
+        this.members.set(id, { kind, member: { ...member } });
+    }
+    /** The entity went back to its own rig, or unmounted. */
+    delete(id) {
+        this.members.delete(id);
+    }
+    /** How many characters this kind is drawing; zero means the batch can skip its work. */
+    count(kind) {
+        let count = 0;
+        for (const entry of this.members.values())
+            if (entry.kind === kind)
+                count += 1;
+        return count;
+    }
+    /** Visit every character of one kind, in insertion order. */
+    forEach(kind, visit) {
+        for (const [id, entry] of this.members)
+            if (entry.kind === kind)
+                visit(id, entry.member);
+    }
+    /** Drop every entry; called when the crowd layer unmounts. */
+    clear() {
+        this.members.clear();
+    }
+}

package/dist/render/materialAsset.js

@@ -6,6 +6,7 @@ import { MATERIAL_TEXTURE_SEMANTICS, validateMaterialAsset, validateMaterialAssi
 import { applyMaterialOverrideToMaterial, MATERIAL_TEXTURE_PROPERTIES, requiresPhysicalMaterial } from "../materialOverride.js";
 import { configureAuthoredSurface } from "./authoredSurfaceMaterial.js";
 import { ownModelMaterial } from "./modelRender.js";
+import { meshMatchesName } from "./modelMeshMerge.js";
 import { useDisposable } from "./useDisposable.js";
 import { detectKtx2Support, materialKtx2Loader } from "./modelLoad.js";
 import { resolveAssetBaseUrl } from "./assetBase.js";
@@ -200,7 +201,7 @@ function materialAssignmentTargets(root, assets, assignments, options = {}) {
         const selected = [];
         root.traverse(node => {
             const mesh = node;
-            if (!mesh.isMesh || (assignment.selector.mesh !== undefined && mesh.name !== assignment.selector.mesh))
+            if (!mesh.isMesh || (assignment.selector.mesh !== undefined && !meshMatchesName(mesh, assignment.selector.mesh)))
                 return;
             const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
             materials.forEach((material, index) => {

package/dist/render/modelLoad.js

@@ -6,6 +6,7 @@ import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.j
 import { classifyAssetResponse, } from "@jgengine/core/scene/assetDiagnostics";
 import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors";
 import { resolveAssetBaseUrl } from "./assetBase.js";
+import { mergeModelSubMeshes, mergeSkinnedModelParts } from "./modelMeshMerge.js";
 import { applyModelSurface } from "./modelSurface.js";
 /** Model containers already covered by the whole-model fallback probe; not "texture" errors. @internal */
 const MODEL_URL_RE = /\.(glb|gltf)(\?|#|$)/i;
@@ -212,6 +213,8 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         super.load(url, (gltf) => {
             recordModelTriangles(url, countSceneTriangles(gltf.scene));
             applyModelSurface(gltf.scene);
+            mergeSkinnedModelParts(gltf.scene);
+            mergeModelSubMeshes(gltf.scene, gltf.animations);
             onLoad(gltf);
         }, onProgress, (event) => {
             if (onError === undefined)

package/dist/render/modelMeshMerge.d.ts

@@ -0,0 +1,49 @@
+import * as THREE from "three";
+/**
+ * Turn load-time sub-mesh merging on or off. On (the default) every loaded model whose meshes share a
+ * material collapses to one mesh per material, which is what a game with many instances of a
+ * multi-mesh prop needs; a game that must keep per-mesh nodes (named material slots, node visibility)
+ * turns it off.
+ * @internal
+ */
+export declare function setModelSubMeshMerge(enabled: boolean): void;
+/** The node names a merged mesh absorbed, in the order they were merged. Empty for an unmerged mesh. @internal */
+export declare function mergedMeshNames(mesh: THREE.Object3D): readonly string[];
+/**
+ * Whether a mesh answers to `name`: its own name, or one of the sub-meshes a load-time merge folded
+ * into it. Name-based lookups (material assignment selectors) go through this so a merged model keeps
+ * resolving the names its source meshes had.
+ * @internal
+ */
+export declare function meshMatchesName(mesh: THREE.Object3D, name: string): boolean;
+/** What {@link mergeModelSubMeshes} did to one loaded model. @internal */
+export interface ModelMeshMergeReport {
+    /** Meshes removed from the graph because their geometry joined a same-material sibling. */
+    merged: number;
+    /** Meshes left in place. */
+    kept: number;
+}
+/**
+ * Collapse a freshly loaded model's meshes that share a material into one mesh per material, baking
+ * each mesh's transform relative to `root` into the merged vertices. Runs once per load, so every
+ * instance cloned from the model inherits the lower draw count.
+ *
+ * Skinned meshes, instanced meshes, meshes with morph targets or rigged ancestors, meshes with
+ * children, hidden meshes, mirrored meshes, and every model carrying an animation clip are left
+ * untouched: a clip can move any node in the file, so baking an animated model's transforms would
+ * freeze it.
+ * @internal
+ */
+export declare function mergeModelSubMeshes(root: THREE.Object3D, animations?: readonly THREE.AnimationClip[]): ModelMeshMergeReport;
+/**
+ * Collapse a rigged model's skinned parts that share a skeleton and a material into one skinned mesh,
+ * so one character is one draw and one bone matrix upload instead of one per body part. Vertices move
+ * into bind space (each part's own `bindMatrix` baked in) and skin indices are remapped onto the
+ * union of the parts' bones, which leaves the posed result unchanged. Runs once per load, before any
+ * clone, so every instance inherits the lower part count.
+ *
+ * Parts with a different material, a different attribute layout, morph targets, several materials or
+ * children stay as they are. A model that only has one part is untouched.
+ * @internal
+ */
+export declare function mergeSkinnedModelParts(root: THREE.Object3D): ModelMeshMergeReport;