@jgengine/shell 0.19.0 → 0.22.0

package/dist/world/WorldScene.js

@@ -1,7 +1,14 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { modelWithAuthoredMaterials } from "@jgengine/core/editor/materialAuthoring";
+import { modelWithAuthoredNodeVisibility } from "@jgengine/core/editor/modelNodeVisibility";
 import { useFrame } from "@react-three/fiber";
 import { useEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { createEmptyEditorDocument } from "@jgengine/core/editor/index";
+import { resolveAuthoredObjects } from "@jgengine/core/world/authoredObjects";
+import { useLiveEditorDocument } from "../scene/AuthoredScene.js";
+import { StaticObjectModels } from "./StaticObjectModels.js";
+import { groupStaticObjects } from "./staticObjectBatches.js";
 import { objectVisualScale } from "@jgengine/core/scene/objectStore";
 import { WORLD_ITEM_ENTITY_NAME } from "@jgengine/core/game/worldItem";
 import { beginFallbackSeam, endFallbackPass, reportFallbackSeam, } from "@jgengine/core/devtools/fallbackSeams";
@@ -12,11 +19,12 @@ import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
 import { useDisposable } from "../render/useDisposable.js";
 import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
-import { resolveModel, resolveEntityModel, tryResolveCatalogModel } from "../render/resolveModel.js";
+import { resolveEntityModel, resolveObjectModel } from "../render/resolveModel.js";
 import { useRenderVisibility } from "../visibility/CullingProvider.js";
 import { writeEntityPose, writeRenderPose } from "./entityPose.js";
 import { createSnapshotBuffer } from "@jgengine/core/runtime/snapshotBuffer";
 import { POINTER_ENTITY_KEY, POINTER_OBJECT_KEY } from "../pointer/pointerService.js";
+const EMPTY_DOCUMENT = createEmptyEditorDocument();
 const GROUND_SIZE = 160;
 const GROUND_SEGMENTS = 80;
 function EntityMarker({ entity, custom, model, sprite, isLocal, targeted, selected, onSelect, }) {
@@ -130,10 +138,15 @@ function WorldEnvironment({ environment: Environment }) {
     reportFallbackSeam("ground", "noScene");
     return (_jsxs(_Fragment, { children: [_jsx(GroundPlane, {}), _jsx(RockField, {})] }));
 }
-function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
+function WorldActors({ entitySprites, entityModels, objectModels, objectStyles, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
     const ctx = useGameContext();
     const entityIds = useSceneEntityIds();
     const objectIds = useSceneObjectIds();
+    const document = useLiveEditorDocument(editorLayers ?? EMPTY_DOCUMENT, editorLayers !== undefined);
+    const materialMarkers = useMemo(() => new Map(document.markers.map((marker) => [marker.id, marker])), [document]);
+    const authoredIds = useMemo(() => new Set(resolveAuthoredObjects(document).map((object) => object.instanceId)), [document]);
+    const batchCache = useRef(new Map());
+    const modelCache = useMemo(() => new Map(), [objectModels, assets]);
     const player = usePlayer();
     const targetId = useTarget(player.userId);
     const controlledId = useGameStore((c) => c.player.possession.active(player.userId));
@@ -148,6 +161,29 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
     useEffect(() => {
         endFallbackPass();
     });
+    const candidates = objectIds.flatMap((instanceId) => {
+        const object = ctx.scene.object.get(instanceId);
+        if (object === null)
+            return [];
+        const custom = renderObject?.(object);
+        const model = modelWithAuthoredNodeVisibility(modelWithAuthoredMaterials(resolveObjectModel(object, objectModels, assets, modelCache), { materialAssets: document.materialAssets, markers: materialMarkers.has(object.instanceId) ? [materialMarkers.get(object.instanceId)] : [] }, object.instanceId), materialMarkers.get(object.instanceId));
+        const style = objectStyles?.[object.catalogId];
+        // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
+        // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
+        if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
+            reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
+        }
+        return [{ object, model, custom, style, authored: authoredIds.has(instanceId), catalog: ctx.scene.object.catalog(instanceId) }];
+    });
+    const grouped = groupStaticObjects(candidates.map((candidate) => ({ ...candidate, custom: candidate.custom !== undefined && candidate.custom !== null })), 24, batchCache.current);
+    batchCache.current = new Map(grouped.batches.map((batch) => [batch.key, batch]));
+    const candidatesById = new Map(candidates.map((candidate) => [candidate.object.instanceId, candidate]));
+    const renderSingle = (object) => {
+        object = ctx.scene.object.get(object.instanceId) ?? object;
+        const candidate = candidatesById.get(object.instanceId);
+        const model = modelWithAuthoredNodeVisibility(modelWithAuthoredMaterials(resolveObjectModel(object, objectModels, assets, modelCache), { materialAssets: document.materialAssets, markers: materialMarkers.has(object.instanceId) ? [materialMarkers.get(object.instanceId)] : [] }, object.instanceId), materialMarkers.get(object.instanceId));
+        return _jsx(ObjectMarker, { object: object, custom: object === candidate.object ? candidate.custom : renderObject?.(object), model: model, style: objectStyles?.[object.catalogId] }, object.instanceId);
+    };
     return (_jsxs(_Fragment, { children: [entityIds.map((entityId) => {
                 const entity = ctx.scene.entity.get(entityId);
                 if (entity === null || entity.name === WORLD_ITEM_ENTITY_NAME)
@@ -163,31 +199,10 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
                     reportFallbackSeam("entity", "omittedMapping");
                 }
                 return (_jsx(EntityMarker, { entity: entity, custom: custom, model: model, sprite: sprite, isLocal: entityId === controlledId, targeted: entityId === targetId, selected: selectedIds.has(entityId), onSelect: handleSelect }, entityId));
-            }), objectIds.map((instanceId) => {
-                const object = ctx.scene.object.get(instanceId);
-                if (object === null)
-                    return null;
-                const custom = renderObject?.(object);
-                const resolved = resolveModel(objectModels?.[object.catalogId], assets, {
-                    seam: "objectModels",
-                    key: object.catalogId,
-                }) ?? tryResolveCatalogModel(object.catalogId, assets);
-                // An authored per-placement animation override (marker.meta.animation → SceneObject.animation,
-                // #1276) wins over catalog resolution's default "auto"; absent, the resolved config is untouched.
-                const model = resolved !== undefined && object.animation !== undefined
-                    ? { ...resolved, animation: object.animation }
-                    : resolved;
-                const style = objectStyles?.[object.catalogId];
-                // Reaching the primitive box means no model resolved. A present-but-unresolved objectModels
-                // key implies its asset pack is not pulled; an absent key is an omitted (often intended) mapping.
-                if ((custom === undefined || custom === null) && model === undefined && style?.hidden !== true) {
-                    reportFallbackSeam("object", objectModels?.[object.catalogId] === undefined ? "omittedMapping" : "unpulledPack");
-                }
-                return (_jsx(ObjectMarker, { object: object, custom: custom, model: model, style: style }, instanceId));
-            })] }));
+            }), grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
 }
-export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, }) {
-    return (_jsxs(_Fragment, { children: [_jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor })] }));
+export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
+    return (_jsxs(_Fragment, { children: [_jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));
 }
 export function RemotePlayers({ rows, presenceInterpolationMs = 100 }) {
     const groups = useRef(new Map());

package/dist/world/staticObjectBatches.d.ts

@@ -0,0 +1,35 @@
+import * as THREE from "three";
+import type { ModelConfig, ObjectStyle } from "@jgengine/core/game/playableGame";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import type { GameContextObjectEntry } from "@jgengine/core/runtime/gameContext";
+import type { ScatterModelSource } from "../scatter/scatterModels.js";
+/** @internal */
+export interface StaticObjectCandidate {
+    object: SceneObject;
+    model?: ModelConfig;
+    authored: boolean;
+    custom: boolean;
+    catalog: GameContextObjectEntry | null;
+    style?: ObjectStyle | undefined;
+}
+/** @internal */
+export interface StaticObjectBatch {
+    key: string;
+    model: ModelConfig;
+    objects: SceneObject[];
+}
+/** The same compatibility gate is used when live placements change after grouping. @internal */
+export declare function canBatchStaticObject(candidate: StaticObjectCandidate): boolean;
+/** Checks a live placement without constructing a grouping candidate. @internal */
+export declare function isCompatibleStaticObject(object: SceneObject, model: ModelConfig | undefined, catalog: GameContextObjectEntry | null): boolean;
+/** Stable exclusion snapshot; only compatibility transitions allocate. @internal */
+export declare function incompatibleStaticObjectIds(batch: StaticObjectBatch, get: (id: string) => SceneObject | null, catalog: (id: string) => GameContextObjectEntry | null, previous: readonly string[], fallbackObjects?: Map<string, SceneObject>): readonly string[];
+/** Groups compatible authored props above eight placements per spatial cell. @internal */
+export declare function groupStaticObjects(candidates: readonly StaticObjectCandidate[], chunkSize?: number, previous?: ReadonlyMap<string, StaticObjectBatch>): {
+    batches: StaticObjectBatch[];
+    singles: StaticObjectCandidate[];
+};
+/** Rejects loaded scenes whose behavior cannot be represented by static instanced draws. @internal */
+export declare function canInstanceStaticScene(scene: THREE.Object3D, clips: readonly THREE.AnimationClip[]): boolean;
+/** Compact visible placements and update picking identities without allocating per instance. @internal */
+export declare function syncStaticObjectSource(mesh: THREE.InstancedMesh, source: ScatterModelSource, objects: readonly SceneObject[], get: (id: string) => SceneObject | null, visible: (id: string) => boolean, scratch: THREE.Object3D): void;

package/dist/world/staticObjectBatches.js

@@ -0,0 +1,163 @@
+import * as THREE from "three";
+import { POINTER_OBJECT_INSTANCES_KEY } from "../pointer/pointerService.js";
+/** The same compatibility gate is used when live placements change after grouping. @internal */
+export function canBatchStaticObject(candidate) {
+    const { object, model, catalog } = candidate;
+    return candidate.authored && !candidate.custom && candidate.style === undefined &&
+        isCompatibleStaticObject(object, model, catalog);
+}
+/** Checks a live placement without constructing a grouping candidate. @internal */
+export function isCompatibleStaticObject(object, model, catalog) {
+    const animation = object.animation ?? model?.animation;
+    return model !== undefined &&
+        object.visual === undefined && object.state === undefined && object.slots === undefined &&
+        catalog?.proximityPrompt === undefined && (catalog?.verbs?.length ?? 0) === 0 &&
+        (catalog?.breakable === undefined || catalog.breakable === false) && catalog?.slotInventory === undefined &&
+        (animation === undefined || animation === "auto" || animation === "none") && model.ik === undefined &&
+        (model.scale ?? 1) >= 0 && (model.parts?.length ?? 0) === 0 && (model.attachments?.length ?? 0) === 0 &&
+        model.partMotion === undefined && model.material?.maps === undefined && (model.materialAssignments?.length ?? 0) === 0 &&
+        (model.hiddenNodes === undefined || (Array.isArray(model.hiddenNodes) && model.hiddenNodes.length === 0));
+}
+/** Stable exclusion snapshot; only compatibility transitions allocate. @internal */
+export function incompatibleStaticObjectIds(batch, get, catalog, previous, fallbackObjects) {
+    const compatible = (object) => object.catalogId === batch.objects[0].catalogId &&
+        isCompatibleStaticObject(object, batch.model, catalog(object.instanceId));
+    let count = 0;
+    let changed = false;
+    for (const object of batch.objects) {
+        const live = get(object.instanceId);
+        if (live !== null && !compatible(live)) {
+            changed ||= previous[count] !== live.instanceId;
+            const before = fallbackObjects?.get(live.instanceId);
+            if (before !== undefined)
+                changed ||= before.catalogId !== live.catalogId || before.animation !== live.animation ||
+                    before.visual !== live.visual || before.state !== live.state || before.slots !== live.slots;
+            fallbackObjects?.set(live.instanceId, live);
+            count++;
+        }
+    }
+    if (fallbackObjects !== undefined)
+        for (const id of fallbackObjects.keys()) {
+            const live = get(id);
+            if (live === null || compatible(live))
+                fallbackObjects.delete(id);
+        }
+    if (!changed && count === previous.length)
+        return previous;
+    return batch.objects.flatMap((object) => {
+        const live = get(object.instanceId);
+        return live !== null && !compatible(live) ? [live.instanceId] : [];
+    });
+}
+/** Groups compatible authored props above eight placements per spatial cell. @internal */
+export function groupStaticObjects(candidates, chunkSize = 24, previous) {
+    const groups = new Map();
+    const singles = [];
+    for (const candidate of candidates) {
+        const { object, model } = candidate;
+        if (model === undefined || !canBatchStaticObject(candidate)) {
+            singles.push(candidate);
+            continue;
+        }
+        const key = JSON.stringify([object.catalogId, Math.floor(object.position[0] / chunkSize), Math.floor(object.position[2] / chunkSize), model]);
+        let group = groups.get(key);
+        if (group === undefined) {
+            group = { batch: { key, model, objects: [] }, candidates: [] };
+            groups.set(key, group);
+        }
+        group.batch.objects.push(object);
+        group.candidates.push(candidate);
+    }
+    const batches = [];
+    for (const { batch, candidates: members } of groups.values()) {
+        if (batch.objects.length > 8) {
+            const cached = previous?.get(batch.key);
+            batches.push(cached !== undefined && cached.objects.length === batch.objects.length &&
+                cached.objects.every((object, index) => object.instanceId === batch.objects[index].instanceId) ? cached : batch);
+        }
+        else
+            singles.push(...members);
+    }
+    return { batches, singles };
+}
+/** Rejects loaded scenes whose behavior cannot be represented by static instanced draws. @internal */
+export function canInstanceStaticScene(scene, clips) {
+    if (clips.length > 0)
+        return false;
+    scene.updateMatrixWorld(true);
+    if (!scene.matrix.equals(new THREE.Matrix4()))
+        return false;
+    let supported = true;
+    scene.traverse((node) => {
+        if (node.layers.mask !== 1 || node.renderOrder !== 0 || node.matrix.determinant() < 0)
+            supported = false;
+        const mesh = node;
+        if (!mesh.isMesh) {
+            if (!node.isGroup && node.type !== "Object3D" && node.type !== "Scene")
+                supported = false;
+            return;
+        }
+        if (mesh.isSkinnedMesh || mesh.isInstancedMesh ||
+            mesh.morphTargetInfluences !== undefined || mesh.onBeforeRender !== THREE.Object3D.prototype.onBeforeRender ||
+            mesh.onAfterRender !== THREE.Object3D.prototype.onAfterRender)
+            supported = false;
+        const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        if (materials.some((material) => material.transparent || material.isShaderMaterial))
+            supported = false;
+        const elements = mesh.matrixWorld.elements;
+        for (let a = 0; a < 3; a++)
+            for (let b = a + 1; b < 3; b++) {
+                const dot = elements[a * 4] * elements[b * 4] + elements[a * 4 + 1] * elements[b * 4 + 1] + elements[a * 4 + 2] * elements[b * 4 + 2];
+                const lengthA = Math.hypot(elements[a * 4], elements[a * 4 + 1], elements[a * 4 + 2]);
+                const lengthB = Math.hypot(elements[b * 4], elements[b * 4 + 1], elements[b * 4 + 2]);
+                // Three's instanced normal transform assumes orthogonal matrix columns.
+                if (Math.abs(dot) > 1e-5 * lengthA * lengthB)
+                    supported = false;
+            }
+    });
+    return supported;
+}
+/** Compact visible placements and update picking identities without allocating per instance. @internal */
+export function syncStaticObjectSource(mesh, source, objects, get, visible, scratch) {
+    const ids = (mesh.userData[POINTER_OBJECT_INSTANCES_KEY] ??= []);
+    const poses = (mesh.userData["jgStaticObjectPoses"] ??= []);
+    if (mesh.userData["jgStaticObjectSource"] !== source) {
+        poses.length = 0;
+        mesh.userData["jgStaticObjectSource"] = source;
+    }
+    let count = 0;
+    let changed = false;
+    const composed = scratch.matrixWorld;
+    for (const object of objects) {
+        const live = get(object.instanceId);
+        if (live === null || !visible(live.instanceId))
+            continue;
+        if (poses[count] === live) {
+            ids[count++] = live.instanceId;
+            continue;
+        }
+        scratch.position.fromArray(live.position);
+        scratch.rotation.set(0, live.rotationY, 0);
+        scratch.updateMatrix();
+        composed.multiplyMatrices(scratch.matrix, source.localMatrix);
+        const offset = count * 16;
+        for (let axis = 0; axis < 16; axis += 1) {
+            if (mesh.instanceMatrix.array[offset + axis] !== Math.fround(composed.elements[axis])) {
+                changed = true;
+                break;
+            }
+        }
+        mesh.setMatrixAt(count, composed);
+        poses[count] = live;
+        ids[count++] = live.instanceId;
+    }
+    ids.length = count;
+    poses.length = count;
+    changed ||= mesh.count !== count;
+    mesh.count = count;
+    mesh.visible = count > 0;
+    if (changed) {
+        mesh.instanceMatrix.needsUpdate = true;
+        mesh.computeBoundingSphere();
+    }
+}

package/dist/world/worldBarSamples.d.ts

@@ -1,7 +1,8 @@
-import type { SceneEntity } from "@jgengine/core/scene/entityStore";
-import type { CatalogEntityRole } from "@jgengine/core/runtime/gameContext";
-import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { SceneEntity, EntityPosition } from "@jgengine/core/scene/entityStore";
+import type { CatalogEntityRole, GameContext } from "@jgengine/core/runtime/gameContext";
 export interface WorldBarSample {
+    /** Live anchor id used by retained samples; omitted for caller-painted screen samples. */
+    entityId?: string;
     x: number;
     y: number;
     percent: number;
@@ -16,49 +17,52 @@ export interface Projectable {
     y: number;
     z: number;
 }
-/**
- * True when world geometry stands between the player's eye and `target`. World bars and nameplates
- * are DOM/canvas overlays projected to screen space, so nothing in the depth buffer can hide them —
- * without this test an enemy's health bar reads straight through the building it is standing behind.
- * @internal
- */
-export declare function worldBarOccluded(ctx: GameContext, from: readonly [number, number, number], target: readonly [number, number, number], eyeHeight: number): boolean;
-/**
- * Projects every non-local, role/distance-filtered entity carrying `statId` into `into` as a
- * `WorldBarSample`. Pure data step behind `WorldHealthBars` — call it directly to paint the bars
- * with your own renderer.
- * @internal
- */
-export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
-    matrixWorldInverse: unknown;
+/** Render camera matrices; world translation supplies the overlay's viewpoint. */
+export interface WorldOverlayCamera {
+    matrixWorld: {
+        elements: ArrayLike<number>;
+    };
+    matrixWorldInverse: {
+        elements: ArrayLike<number>;
+    };
     projectionMatrix: unknown;
-}, viewport: {
+}
+/** Sampling policy shared by health bars and nameplates. */
+export interface WorldOverlaySampleOptions {
+    /** Maximum sampled overlays and visibility rays per refresh. Default 64; unchecked entities stay hidden. */
+    maxSamples?: number;
+    /** Match a renderer's visibility or membership policy. */
+    isVisible?: (id: string) => boolean;
+    /** Authored display name; return null to omit the nameplate. */
+    resolveName?: (entity: SceneEntity) => string | null;
+}
+/** True when blocking scene geometry lies between the render camera and overlay anchor. @internal */
+export declare function worldBarOccluded(ctx: GameContext, from: EntityPosition, target: EntityPosition): boolean;
+/** Project nearby live non-local entities carrying `statId`; occlusion defaults on. @internal */
+export declare function collectWorldBarSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: WorldOverlayCamera, viewport: {
     width: number;
     height: number;
-}, into: WorldBarSample[], project: Projectable, maxDistance?: number, occlude?: boolean): number;
-/** One entity's projected nameplate: screen `x`/`y`, display `name`, health `percent` (or `null` when statless), and world `distance` from the player. */
+}, into: WorldBarSample[], project: Projectable, maxDistance?: number, occlude?: boolean, options?: WorldOverlaySampleOptions): number;
+/** Reproject retained bar anchors without a nearby query or visibility ray. @internal */
+export declare function refreshWorldBarSamples(ctx: GameContext, height: number, camera: WorldOverlayCamera, viewport: {
+    width: number;
+    height: number;
+}, samples: WorldBarSample[], project: Projectable, maxDistance?: number, options?: WorldOverlaySampleOptions): void;
+/** Projected nameplate with optional health and distance from the render camera. */
 export interface NameplateSample {
     id: string;
     name: string;
     x: number;
     y: number;
-    /** Health-stat fraction 0..1, or `null` when the entity carries no `statId` stat (name-only nameplate). */
+    /** Health-stat fraction 0..1, or null for a statless entity. */
     percent: number | null;
     distance: number;
 }
-/**
- * Projects every non-local, role/distance-filtered entity into `into` as a
- * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
- * own renderer by calling this directly instead of the component.
- * @internal
- */
-export declare function collectNameplateSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: {
-    matrixWorldInverse: unknown;
-    projectionMatrix: unknown;
-}, viewport: {
+/** Project nearby live non-local nameplates; occlusion defaults on. @internal */
+export declare function collectNameplateSamples(ctx: GameContext, statId: string, height: number, roles: readonly CatalogEntityRole[] | undefined, resolveRole: ((entity: SceneEntity) => CatalogEntityRole | undefined) | undefined, camera: WorldOverlayCamera, viewport: {
     width: number;
     height: number;
-}, into: NameplateSample[], project: Projectable, maxDistance?: number, occlude?: boolean): number;
+}, into: NameplateSample[], project: Projectable, maxDistance?: number, occlude?: boolean, options?: WorldOverlaySampleOptions): number;
 /** @internal */
 export declare function paintWorldBarSamples(canvas: {
     width: number;

package/dist/world/worldBarSamples.js

@@ -1,98 +1,140 @@
 import { worldHealthBarAllowsRole } from "@jgengine/core/game/playableGame";
-/**
- * True when world geometry stands between the player's eye and `target`. World bars and nameplates
- * are DOM/canvas overlays projected to screen space, so nothing in the depth buffer can hide them —
- * without this test an enemy's health bar reads straight through the building it is standing behind.
- * @internal
- */
-export function worldBarOccluded(ctx, from, target, eyeHeight) {
-    const origin = [from[0], from[1] + eyeHeight, from[2]];
-    const dx = target[0] - origin[0];
-    const dy = target[1] + eyeHeight - origin[1];
-    const dz = target[2] - origin[2];
+/** True when blocking scene geometry lies between the render camera and overlay anchor. @internal */
+export function worldBarOccluded(ctx, from, target) {
+    const dx = target[0] - from[0];
+    const dy = target[1] - from[1];
+    const dz = target[2] - from[2];
     const length = Math.hypot(dx, dy, dz);
     if (length < 0.001)
         return false;
-    const hit = ctx.scene.object.raycast({
-        origin,
+    return ctx.scene.raycast({
+        origin: from,
         direction: [dx / length, dy / length, dz / length],
-        // Stop short of the entity so its own collider never counts as its own occluder.
-        maxDistance: length - 0.5,
-    });
-    return hit !== null;
+        maxDistance: length - 0.001,
+        filter: { entities: false },
+        accept: (hit) => hit.blocks,
+    }) !== null;
 }
-/**
- * Projects every non-local, role/distance-filtered entity carrying `statId` into `into` as a
- * `WorldBarSample`. Pure data step behind `WorldHealthBars` — call it directly to paint the bars
- * with your own renderer.
- * @internal
- */
-export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60, occlude = false) {
+function cameraOrigin(camera) {
+    const matrix = camera.matrixWorld.elements;
+    return [matrix[12], matrix[13], matrix[14]];
+}
+function projectAnchor(entity, height, camera, project) {
+    const anchor = [entity.position[0], entity.position[1] + height, entity.position[2]];
+    const inverse = camera.matrixWorldInverse.elements;
+    const cameraZ = inverse[2] * anchor[0] + inverse[6] * anchor[1] + inverse[10] * anchor[2] + inverse[14];
+    if (!Number.isFinite(cameraZ) || cameraZ >= 0)
+        return null;
+    project.set(...anchor).project(camera);
+    if (!Number.isFinite(project.x) || !Number.isFinite(project.y) || !Number.isFinite(project.z))
+        return null;
+    if (Math.abs(project.x) > 1 || Math.abs(project.y) > 1 || Math.abs(project.z) > 1)
+        return null;
+    return anchor;
+}
+function healthFraction(stat) {
+    const range = stat.max - stat.min;
+    return range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
+}
+function eligibleEntity(ctx, id, options) {
+    if (id === ctx.player.userId || id === ctx.player.possession.active(ctx.player.userId) || options.isVisible?.(id) === false)
+        return null;
+    const entity = ctx.scene.entity.get(id);
+    if (entity === null || entity.hidden === true)
+        return null;
+    const health = ctx.scene.entity.stats.get(id, "health");
+    if (health !== null && health.current <= health.min)
+        return null;
+    return entity;
+}
+function sampleLimit(options) {
+    return Math.max(0, Math.min(256, Math.floor(options.maxSamples ?? 64) || 0));
+}
+/** Project nearby live non-local entities carrying `statId`; occlusion defaults on. @internal */
+export function collectWorldBarSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 60, occlude = true, options = {}) {
     into.length = 0;
-    const playerId = ctx.player.userId;
-    const player = ctx.scene.entity.get(playerId);
-    for (const entity of ctx.scene.entity.list()) {
-        if (entity.id === playerId)
+    const origin = cameraOrigin(camera);
+    const limit = sampleLimit(options);
+    if (limit === 0 || !Number.isFinite(maxDistance) || maxDistance <= 0)
+        return 0;
+    let checked = 0;
+    for (const id of ctx.scene.entity.inRadius(origin, maxDistance)) {
+        const entity = eligibleEntity(ctx, id, options);
+        if (entity === null || !worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
             continue;
-        if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+        const stat = ctx.scene.entity.stats.get(id, statId);
+        if (stat === null)
             continue;
-        if (player !== null &&
-            Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]) >
-                maxDistance) {
+        const anchor = projectAnchor(entity, height, camera, project);
+        if (anchor === null)
             continue;
-        }
-        if (occlude && player !== null && worldBarOccluded(ctx, player.position, entity.position, 1.5))
+        if (checked++ >= limit)
+            break;
+        if (occlude && worldBarOccluded(ctx, origin, anchor))
             continue;
-        const stat = ctx.scene.entity.stats.get(entity.id, statId);
-        if (stat === null)
+        into.push({
+            entityId: id,
+            x: (project.x * 0.5 + 0.5) * viewport.width,
+            y: (-project.y * 0.5 + 0.5) * viewport.height,
+            percent: healthFraction(stat),
+        });
+    }
+    return into.length;
+}
+/** Reproject retained bar anchors without a nearby query or visibility ray. @internal */
+export function refreshWorldBarSamples(ctx, height, camera, viewport, samples, project, maxDistance = 60, options = {}) {
+    const origin = cameraOrigin(camera);
+    let kept = 0;
+    for (const sample of samples) {
+        if (sample.entityId === undefined)
+            continue;
+        const entity = eligibleEntity(ctx, sample.entityId, options);
+        if (entity === null || Math.hypot(entity.position[0] - origin[0], entity.position[1] - origin[1], entity.position[2] - origin[2]) > maxDistance)
             continue;
-        const range = stat.max - stat.min;
-        const percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
-        project.set(entity.position[0], entity.position[1] + height, entity.position[2]);
-        project.project(camera);
-        if (project.z < -1 || project.z > 1)
+        if (projectAnchor(entity, height, camera, project) === null)
             continue;
-        const x = (project.x * 0.5 + 0.5) * viewport.width;
-        const y = (-project.y * 0.5 + 0.5) * viewport.height;
-        into.push({ x, y, percent });
+        sample.x = (project.x * 0.5 + 0.5) * viewport.width;
+        sample.y = (-project.y * 0.5 + 0.5) * viewport.height;
+        samples[kept++] = sample;
     }
-    return into.length;
+    samples.length = kept;
+}
+function defaultDisplayName(entity) {
+    const name = entity.name.trim();
+    // Entity names also key catalogs; machine identifiers need an explicit display-name resolver.
+    return name === entity.id || /^[a-z0-9_-]+$/.test(name) || /[_:/]/.test(name) ? null : name || null;
 }
-/**
- * Projects every non-local, role/distance-filtered entity into `into` as a
- * `NameplateSample`. Pure data step powering `WorldNameplates` — swap in your
- * own renderer by calling this directly instead of the component.
- * @internal
- */
-export function collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 40, occlude = false) {
+/** Project nearby live non-local nameplates; occlusion defaults on. @internal */
+export function collectNameplateSamples(ctx, statId, height, roles, resolveRole, camera, viewport, into, project, maxDistance = 40, occlude = true, options = {}) {
     into.length = 0;
-    const playerId = ctx.player.userId;
-    const player = ctx.scene.entity.get(playerId);
-    for (const entity of ctx.scene.entity.list()) {
-        if (entity.id === playerId)
+    const origin = cameraOrigin(camera);
+    const limit = sampleLimit(options);
+    if (limit === 0 || !Number.isFinite(maxDistance) || maxDistance <= 0)
+        return 0;
+    let checked = 0;
+    for (const id of ctx.scene.entity.inRadius(origin, maxDistance)) {
+        const entity = eligibleEntity(ctx, id, options);
+        if (entity === null || !worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
             continue;
-        if (!worldHealthBarAllowsRole(roles, resolveRole?.(entity)))
+        const name = (options.resolveName ?? defaultDisplayName)(entity)?.trim();
+        if (!name)
             continue;
-        const distance = player === null
-            ? 0
-            : Math.hypot(entity.position[0] - player.position[0], entity.position[2] - player.position[2]);
-        if (player !== null && distance > maxDistance)
+        const anchor = projectAnchor(entity, height, camera, project);
+        if (anchor === null)
             continue;
-        if (occlude && player !== null && worldBarOccluded(ctx, player.position, entity.position, 1.5))
-            continue;
-        const stat = ctx.scene.entity.stats.get(entity.id, statId);
-        let percent = null;
-        if (stat !== null) {
-            const range = stat.max - stat.min;
-            percent = range <= 0 ? 0 : Math.max(0, Math.min(1, (stat.current - stat.min) / range));
-        }
-        project.set(entity.position[0], entity.position[1] + height, entity.position[2]);
-        project.project(camera);
-        if (project.z < -1 || project.z > 1)
+        if (checked++ >= limit)
+            break;
+        if (occlude && worldBarOccluded(ctx, origin, anchor))
             continue;
-        const x = (project.x * 0.5 + 0.5) * viewport.width;
-        const y = (-project.y * 0.5 + 0.5) * viewport.height;
-        into.push({ id: entity.id, name: entity.name, x, y, percent, distance });
+        const stat = ctx.scene.entity.stats.get(id, statId);
+        into.push({
+            id,
+            name,
+            x: (project.x * 0.5 + 0.5) * viewport.width,
+            y: (-project.y * 0.5 + 0.5) * viewport.height,
+            percent: stat === null ? null : healthFraction(stat),
+            distance: Math.hypot(entity.position[0] - origin[0], entity.position[1] - origin[1], entity.position[2] - origin[2]),
+        });
     }
     return into.length;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.19.0",
+  "version": "0.22.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.19.0",
-    "@jgengine/react": "^0.19.0",
-    "@jgengine/ws": "^0.19.0"
+    "@jgengine/core": "^0.22.0",
+    "@jgengine/react": "^0.22.0",
+    "@jgengine/ws": "^0.22.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",