Virtualize fixed instanced scene roots

This commit is contained in:
eust-w 2026-06-25 13:20:45 +08:00
parent eeacb06934
commit bdb03ba5d7
5 changed files with 157 additions and 58 deletions

View File

@ -425,15 +425,17 @@ Scene evidence:
static-subtree traversal and spin scan when the source has no animated nodes.
- Fixed repeated mesh instancing: in large scenes, repeated fixed mesh assets
render through shared `InstancedMesh` batches while each manifest object keeps
its own root, body binding, cached bounds, editable group, and backend sync path.
This reduces WebGL draw work for shelf/product inventory without turning the
objects into frontend-only decorations.
- Instanced local-pose elision: repeated fixed mesh assets no longer allocate a
persistent local-pose `Object3D` for every shelf/product item. Each item keeps
a cached local transform matrix plus source bounds, and the instanced matrix is
computed from `root.matrixWorld * localMatrix * sourceMatrix`. This keeps
backend bindings intact while removing hundreds of Three.js nodes from the
visible/data scene graph.
its body binding, cached bounds, editable group, and backend sync path. Fixed
instances now use a virtual identity root instead of one detached Three.js root
per shelf/product item. This reduces initialization matrix/object work without
turning the objects into frontend-only decorations.
- Instanced local-pose/root elision: repeated fixed mesh assets no longer
allocate a persistent local-pose `Object3D` or per-item root for every
shelf/product item. Each item keeps a cached local transform matrix plus source
bounds, and the instanced matrix is computed directly from
`localMatrix * sourceMatrix` for fixed virtual-root instances. This keeps
backend bindings intact while removing hundreds of Three.js nodes and inverse
bounds transforms from the large-scene build path.
- Finalized instanced batch culling: after all instance matrices are written,
each `InstancedMesh` computes a batch bounding box/sphere, switches its
instance buffer to static usage, and re-enables frustum culling. The release
@ -520,8 +522,9 @@ Scene evidence:
`preserveDrawingBuffer=false`, avoiding the persistent framebuffer retention
cost. Pixel sampling and exported PNG screenshots call an explicit readback
render, and positive pixel evidence is cached until the next scene reload.
- Manual root matrices: every manifest object root disables automatic matrix
recomputation after construction. Runtime state, drag, and robot-offset
- Manual and virtual root matrices: dynamic/stateful manifest objects keep manual
roots with automatic matrix updates disabled, while repeated fixed instanced
inventory uses virtual identity roots. Runtime state, drag, and robot-offset
changes explicitly update only the roots that actually move.
- Safe physical template pose: `/compose` applies the builder `robotPose` to
the included G1 MJCF before loading MotrixSim, and the default physical
@ -532,13 +535,13 @@ Scene evidence:
Bundle evidence:
- JavaScript chunks: `4`
- App entry chunk: `213.59 kB raw / 54.90 kB gzip`
- App entry chunk: `215.57 kB raw / 55.26 kB gzip`
- Largest JavaScript gzip chunk: `140.96 KiB / 170.00 KiB`
- Total JavaScript gzip: `218.44 KiB / 230.00 KiB`
- Total JavaScript gzip: `218.79 KiB / 230.00 KiB`
- Large-scene performance mode: `large-scene`, target `45 fps`,
actual idle render rate `0.8 fps`, DPR cap observed at `1.00` in release
actual idle render rate `0.7 fps`, DPR cap observed at `1.00` in release
gate, `preserveDrawingBuffer=false`, `1` explicit readback render, shadows
`off`, hover picking throttled to `32ms`, `1138` empty frames
`off`, hover picking throttled to `32ms`, `1096` empty frames
skipped, `135` static visual nodes frozen, `568` instanced local-pose nodes
elided, `59` remaining mesh clones using
pre-frozen source state, `627` repeated spin scans skipped, `568` repeated
@ -546,21 +549,23 @@ Bundle evidence:
draw units, `568` matrix uploads, and all `16` draw units finalized with
frustum culling plus static instance matrices, `7` primitive geometry shapes
cached, `51` mesh source assets retained, `24/51` mesh cache hit/miss in the
primary large scene, `636` cached object bounds, `627` fast pick-target
primary large scene, `568` virtual fixed instance roots, `68` manual roots,
`636` cached object bounds, `627` fast pick-target
bounds from `51` cached source bounds, real hover proof `hoverProxy 2` with
cached bounds and `fallback 0`, with `0` camera-fit traversals, `4/84`
progressive scene root batches under the computed `84` root cap and `5`
batch cap, `327` no-op loading frames
batch cap, `826` no-op loading frames
suppressed during the primary load, `26` browser event-loop yields during
scene construction, active state payload `34/602` with `1` reduced frame and
`2` incremental body-map merges, semantic poll forwarding `6/2/4`
`2` incremental body-map merges, semantic poll forwarding `2/2/5`
parsed/forwarded/duplicate-skip,
UI physics-profile cache `24/3` hit/miss, UI builder-profile cache `27/1`
hit/miss, UI text write gating `101/418` write/skip, text selector cache
`473/46` hit/miss, scratch bounds transforms `1263`, diagnostics panel
throttling `19/3` render/skip, `88/636`
state-hash polling `7/5/0` hash/hash-skip/semantic-skip with `5` real
`304 Not Modified` responses, UI physics-profile cache `25/3` hit/miss, UI
builder-profile cache `28/1` hit/miss, UI text write gating `105/445`
write/skip, text selector cache `504/46` hit/miss, scratch bounds transforms
`695`, diagnostics panel throttling `20/3` render/skip, `88/636`
hover targets over cached bounds used for bounds-only ray tests,
and a stable paused backend state cache reported `manual roots 636 updates
and a stable paused backend state cache reported `manual roots 68 updates
67` with `state apply 0/skip 67`.
- Mesh cache lifecycle evidence: the Scene Builder compose switch reported
cumulative `99/51` mesh cache hit/miss with `51` retained geometries and
@ -616,20 +621,21 @@ Bundle evidence:
- Camera-fit traversal gate: `browser-large-scene-performance-mode` now checks
`bounds cache 636` and `camera traversals 0`.
- Pick-proxy bounds gate: `browser-large-scene-performance-mode` now checks
`fast=627`, `scratch=1263`, and `source=51`, proving repeated mesh pick bounds
are served from cached source bounds and transformed through the reduced-
allocation scratch path.
`fast=627`, `scratch=695`, and `source=51`, proving repeated mesh pick bounds
are served from cached source bounds, with fixed instanced objects taking the
virtual-root one-transform path instead of the older root inverse path.
- Pre-frozen mesh clone gate: `browser-large-scene-performance-mode` now checks
`prefrozen + instanced >= repeated mesh threshold` and `spinSkip=627`,
proving repeated mesh assets avoid re-traversing static visual subtrees and
non-spinning clone trees.
- Instanced mesh gate: `browser-large-scene-performance-mode` now checks
`instanced=568/16/16`, `matrices=568`, `cull=16`, `static=16`,
`elidedLocal=568`, and that instanced draw units are fewer than instanced
objects, proving repeated fixed inventory renders through shared GPU batches
with safe frustum culling instead of one cloned render tree per item. The same
gate also requires `frozen + elidedLocal >= 500`, so removing local-pose nodes
cannot be mistaken for losing static-scene optimization coverage.
`elidedLocal=568`, `virtualRoots=568`, and that instanced draw units are fewer
than instanced objects, proving repeated fixed inventory renders through shared
GPU batches with virtual per-item roots and safe frustum culling instead of one
cloned render tree per item. The same gate also requires
`frozen + elidedLocal >= 500`, so removing local-pose nodes cannot be mistaken
for losing static-scene optimization coverage.
- Hover bounds gate: `browser-hover-proxy-bounds` moves the mouse over the real
canvas and now checks both `hoverProxy` and cached hover bounds increase while
`fallback=0`, proving hover highlight uses the pruned cached bounds list
@ -652,29 +658,29 @@ Control evidence:
- Active state endpoint: full `/state` returned `602` bodies; active
`/state?bodies=active` returned `34` bodies in `62ms`, filtered `568` fixed
bodies, and retained `4/4` composed dynamic bodies.
- Scene Builder UI compose: representative run `3756ms` end to end with real
- Scene Builder UI compose: representative run `3544ms` end to end with real
backend diagnostics.
- Share-link restore: representative full browser restore `13118ms`.
- Config import restore: representative full browser restore `14236ms`.
- Share-link restore: representative full browser restore `20138ms`.
- Config import restore: representative full browser restore `18889ms`.
- Composed object body edit: `47ms`.
- Fixed inventory edit rejection: `59ms`.
- Dynamic composed object drop: `0.48012m`.
- Static shelf anchor stability: `max drift 0.00000m` after a 2500 ms resume
window.
- Resume backend state: `44ms paused=false`
- Resume visible UI state: `35ms`
- Pause backend state: `54ms paused=true`
- Pause visible UI state: `43ms`
- Resume backend state: `55ms paused=false`
- Resume visible UI state: `46ms`
- Pause backend state: `258ms paused=true`
- Pause visible UI state: `44ms`
- Desktop acceptance wait: `1243ms` total, product telemetry `0ms`
- Mobile acceptance wait: `277ms` total, product telemetry `0ms`
- Runtime diagnostics panel:
`state=http://127.0.0.1:18090/state`,
`control=http://127.0.0.1:18090/control`,
`latency=响应 43 ms / 确认 43 ms / 可见 43 ms`,
`latency=响应 44 ms / 确认 44 ms / 可见 44 ms`,
`acceptanceLatency=0 ms / 11-0-0`,
`binding=635/636; 4/568`,
`builderPhysics=已添加物体 4: 后端动态 4 / 仅视觉 0`,
`renderPerformance=large-scene; target 45 fps; actual 0.9 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 255; hover 32ms; frozen 135 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16 elidedLocal 568; manual roots 636 updates 67; primitive geometries 7; mesh cache 51 sources 24/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 scratch 1263 source 51 hoverProxy 1 cached 1/fallback 0 camera traversals 0; scene batches 4/84 suppressed 273 yields 26; state payload 34/602 reduced 2 incremental 3; ui cache physics 30/3 builder 33/1 text 107/521 selector 582/46 diagnostics 22/5; pick targets 88/636; state apply 0/skip 67; unchanged frames 2; released 0g/0m/0t`.
`renderPerformance=large-scene; target 45 fps; actual 0.7 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 1096; hover 32ms; frozen 135 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16 elidedLocal 568 virtualRoots 568; manual roots 68 updates 67; primitive geometries 7; mesh cache 51 sources 24/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 scratch 695 source 51 hoverProxy 2 cached 2/fallback 0 camera traversals 0; scene batches 4/84 suppressed 826 yields 26; state payload 34/602 reduced 1 incremental 2; ui cache physics 25/3 builder 28/1 text 103/435 selector 492/46 diagnostics 20/3; pick targets 88/636; state apply 0/skip 67; unchanged frames 1; released 0g/0m/0t`.
- Evidence screenshot artifacts:
`builder page; share page; import page; visual-only boundary canvas; desktop canvas; debug PNG; mobile canvas`
- Evidence export artifacts:
@ -771,13 +777,16 @@ Current performance boundaries:
first load, Scene Builder compose, share restore, and config import restore
still include browser asset creation and scene graph setup time.
- The real backend control path is not the observed bottleneck in the current
gate: pause/resume visible UI confirmation is `56-60ms`, and the backend
physics step sample during pause verification reports `0.51ms` mean and
`0.81ms` p95 step time.
gate: resume visible UI confirmation is `46ms`, pause visible UI confirmation
is `44ms`, and the backend physics step sample during pause verification
reports `0.51ms` mean and `0.81ms` p95 step time.
- The remaining high-impact optimization area is asset-level rendering and
static-scene packaging: more aggressive shelf/product instancing, material
reduction, LODs, and eventually moving repeated fixed inventory into a
backend static-state channel.
static-scene packaging: the current virtual-root instancing path reduces
per-item scene construction (`virtualRoots=568`, `manualRoots=68`), but
share/config restore still spends `18-20s` in full browser page load, compose
restore, asset setup, and screenshots. The next tier is material reduction,
LODs, static asset manifests, and eventually moving repeated fixed inventory
into a backend static-state channel.
## Handoff Criteria

View File

@ -693,6 +693,7 @@ async function readBrowserStats(page) {
instancedMeshFrustumCulledCount: numberData("instancedMeshFrustumCulledCount"),
instancedMeshStaticMatrixCount: numberData("instancedMeshStaticMatrixCount"),
instancedLocalObjectElisionCount: numberData("instancedLocalObjectElisionCount"),
virtualInstancedRootCount: numberData("virtualInstancedRootCount"),
manualMatrixRootCount: numberData("manualMatrixRootCount"),
manualMatrixUpdateCount: numberData("manualMatrixUpdateCount"),
primitiveGeometryCount: numberData("primitiveGeometryCount"),
@ -1847,14 +1848,17 @@ async function verifyBrowser() {
&& (renderPerformance.instancedMeshFrustumCulledCount ?? 0) === (renderPerformance.instancedMeshDrawCount ?? -1)
&& (renderPerformance.instancedMeshStaticMatrixCount ?? 0) === (renderPerformance.instancedMeshDrawCount ?? -1)
&& (renderPerformance.instancedLocalObjectElisionCount ?? 0) >= (renderPerformance.instancedMeshObjectCount ?? 0)
&& (renderPerformance.manualMatrixRootCount ?? 0) >= objectCount
&& (renderPerformance.virtualInstancedRootCount ?? 0) >= (renderPerformance.instancedMeshObjectCount ?? 0)
&& (renderPerformance.manualMatrixRootCount ?? 0) + (renderPerformance.virtualInstancedRootCount ?? 0) >= objectCount
&& (renderPerformance.manualMatrixRootCount ?? Number.POSITIVE_INFINITY) < objectCount
&& (renderPerformance.primitiveGeometryCount ?? 0) > 0
&& (renderPerformance.meshCacheSourceCount ?? 0) > 0
&& (renderPerformance.meshCacheHitCount ?? 0) > 0
&& (renderPerformance.retainedMeshGeometryCount ?? 0) > 0
&& (renderPerformance.sceneObjectBoundsCount ?? 0) >= objectCount
&& (renderPerformance.fastPickProxyBoundsCount ?? 0) >= thresholds.minMeshes
&& (renderPerformance.pickBoundsScratchTransformCount ?? 0) >= (renderPerformance.fastPickProxyBoundsCount ?? 0) * 2
&& (renderPerformance.pickBoundsScratchTransformCount ?? 0) >= (renderPerformance.fastPickProxyBoundsCount ?? 0)
&& (renderPerformance.pickBoundsScratchTransformCount ?? Number.POSITIVE_INFINITY) < (renderPerformance.fastPickProxyBoundsCount ?? 0) * 2
&& (renderPerformance.meshSourceBoundsCount ?? 0) > 0
&& (renderPerformance.hoverCachedBoundsHitCount ?? 0) > 0
&& (renderPerformance.cameraFitTraversalCount ?? Number.POSITIVE_INFINITY) === 0
@ -1892,7 +1896,7 @@ async function verifyBrowser() {
&& (renderPerformance.hoverPickTargetCount ?? Number.POSITIVE_INFINITY) <= maxHoverPickTargets
&& (renderPerformance.skippedBodyStateCount ?? 0) > 0
&& desktopStats.diagnostics.renderPerformance.includes("large-scene"),
`mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} statsRefresh=${renderPerformance.statsRefreshIntervalMs ?? "-"}ms ${renderPerformance.statsRefreshRenderCount ?? "-"}/${renderPerformance.statsRefreshSkipCount ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} buffer=${renderPerformance.preserveDrawingBufferEnabled} readback=${renderPerformance.readbackRenderCount ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} prefrozen=${renderPerformance.preFrozenMeshCloneCount ?? "-"} spinSkip=${renderPerformance.spinningScanSkippedCount ?? "-"} instanced=${renderPerformance.instancedMeshObjectCount ?? "-"}/${renderPerformance.instancedMeshBatchCount ?? "-"}/${renderPerformance.instancedMeshDrawCount ?? "-"} matrices=${renderPerformance.instancedMeshMatrixUpdateCount ?? "-"} cull=${renderPerformance.instancedMeshFrustumCulledCount ?? "-"} static=${renderPerformance.instancedMeshStaticMatrixCount ?? "-"} elidedLocal=${renderPerformance.instancedLocalObjectElisionCount ?? "-"} manualRoots=${renderPerformance.manualMatrixRootCount ?? "-"} manualUpdates=${renderPerformance.manualMatrixUpdateCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} meshCache=${renderPerformance.meshCacheSourceCount ?? "-"} hit=${renderPerformance.meshCacheHitCount ?? "-"} miss=${renderPerformance.meshCacheMissCount ?? "-"} retained=${renderPerformance.retainedMeshGeometryCount ?? "-"}g/${renderPerformance.retainedMeshMaterialCount ?? "-"}m bounds=${renderPerformance.sceneObjectBoundsCount ?? "-"} fast=${renderPerformance.fastPickProxyBoundsCount ?? "-"} scratch=${renderPerformance.pickBoundsScratchTransformCount ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} maxSceneRoots=${maxInstancedSceneRoots} maxBatches=${maxProgressiveSceneRootBatches} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} poll=${renderPerformance.stateBasePollIntervalMs ?? "-"}/${renderPerformance.statePausedPollIntervalMs ?? "-"}/${renderPerformance.stateLastScheduledPollIntervalMs ?? "-"}ms ${renderPerformance.statePollRequestCount ?? "-"}/${renderPerformance.stateActivePollRequestCount ?? "-"}/${renderPerformance.statePausedPollRequestCount ?? "-"} semantic=${renderPerformance.stateParsedPollFrameCount ?? "-"}/${renderPerformance.stateForwardedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicatePollFrameCount ?? "-"} hash=${renderPerformance.stateHashedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateHashPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateSemanticPollFrameCount ?? "-"} notModified=${renderPerformance.stateNotModifiedPollFrameCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} builderPanels=${renderPerformance.builderPanelRenderCount ?? "-"}/${renderPerformance.builderPanelDeferredRenderCount ?? "-"}/${renderPerformance.builderPanelCoalescedRenderCount ?? "-"} pickTargets=${renderPerformance.hoverPickTargetCount ?? "-"}/${renderPerformance.pickProxyCount ?? "-"} hoverBudget=${maxHoverPickTargets} stateApply=${renderPerformance.appliedBodyStateCount ?? "-"}/skip=${renderPerformance.skippedBodyStateCount ?? "-"} unchanged=${renderPerformance.unchangedFrameCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`,
`mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} statsRefresh=${renderPerformance.statsRefreshIntervalMs ?? "-"}ms ${renderPerformance.statsRefreshRenderCount ?? "-"}/${renderPerformance.statsRefreshSkipCount ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} buffer=${renderPerformance.preserveDrawingBufferEnabled} readback=${renderPerformance.readbackRenderCount ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} prefrozen=${renderPerformance.preFrozenMeshCloneCount ?? "-"} spinSkip=${renderPerformance.spinningScanSkippedCount ?? "-"} instanced=${renderPerformance.instancedMeshObjectCount ?? "-"}/${renderPerformance.instancedMeshBatchCount ?? "-"}/${renderPerformance.instancedMeshDrawCount ?? "-"} matrices=${renderPerformance.instancedMeshMatrixUpdateCount ?? "-"} cull=${renderPerformance.instancedMeshFrustumCulledCount ?? "-"} static=${renderPerformance.instancedMeshStaticMatrixCount ?? "-"} elidedLocal=${renderPerformance.instancedLocalObjectElisionCount ?? "-"} virtualRoots=${renderPerformance.virtualInstancedRootCount ?? "-"} manualRoots=${renderPerformance.manualMatrixRootCount ?? "-"} manualUpdates=${renderPerformance.manualMatrixUpdateCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} meshCache=${renderPerformance.meshCacheSourceCount ?? "-"} hit=${renderPerformance.meshCacheHitCount ?? "-"} miss=${renderPerformance.meshCacheMissCount ?? "-"} retained=${renderPerformance.retainedMeshGeometryCount ?? "-"}g/${renderPerformance.retainedMeshMaterialCount ?? "-"}m bounds=${renderPerformance.sceneObjectBoundsCount ?? "-"} fast=${renderPerformance.fastPickProxyBoundsCount ?? "-"} scratch=${renderPerformance.pickBoundsScratchTransformCount ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} maxSceneRoots=${maxInstancedSceneRoots} maxBatches=${maxProgressiveSceneRootBatches} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} poll=${renderPerformance.stateBasePollIntervalMs ?? "-"}/${renderPerformance.statePausedPollIntervalMs ?? "-"}/${renderPerformance.stateLastScheduledPollIntervalMs ?? "-"}ms ${renderPerformance.statePollRequestCount ?? "-"}/${renderPerformance.stateActivePollRequestCount ?? "-"}/${renderPerformance.statePausedPollRequestCount ?? "-"} semantic=${renderPerformance.stateParsedPollFrameCount ?? "-"}/${renderPerformance.stateForwardedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicatePollFrameCount ?? "-"} hash=${renderPerformance.stateHashedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateHashPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateSemanticPollFrameCount ?? "-"} notModified=${renderPerformance.stateNotModifiedPollFrameCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} builderPanels=${renderPerformance.builderPanelRenderCount ?? "-"}/${renderPerformance.builderPanelDeferredRenderCount ?? "-"}/${renderPerformance.builderPanelCoalescedRenderCount ?? "-"} pickTargets=${renderPerformance.hoverPickTargetCount ?? "-"}/${renderPerformance.pickProxyCount ?? "-"} hoverBudget=${maxHoverPickTargets} stateApply=${renderPerformance.appliedBodyStateCount ?? "-"}/skip=${renderPerformance.skippedBodyStateCount ?? "-"} unchanged=${renderPerformance.unchangedFrameCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`,
);
check(
"browser-debug-capture-png",

View File

@ -189,6 +189,7 @@ interface RuntimeDiagnostics {
instancedMeshFrustumCulledCount: number;
instancedMeshStaticMatrixCount: number;
instancedLocalObjectElisionCount: number;
virtualInstancedRootCount: number;
manualMatrixRootCount: number;
manualMatrixUpdateCount: number;
primitiveGeometryCount: number;
@ -2683,6 +2684,7 @@ function currentRuntimeDiagnostics(
instancedMeshFrustumCulledCount: stats.instancedMeshFrustumCulledCount,
instancedMeshStaticMatrixCount: stats.instancedMeshStaticMatrixCount,
instancedLocalObjectElisionCount: stats.instancedLocalObjectElisionCount,
virtualInstancedRootCount: stats.virtualInstancedRootCount,
manualMatrixRootCount: stats.manualMatrixRootCount,
manualMatrixUpdateCount: stats.manualMatrixUpdateCount,
primitiveGeometryCount: stats.primitiveGeometryCount,
@ -2805,7 +2807,7 @@ function currentDiagnosticsReport(): string {
function renderPerformanceLabel(stats: RuntimeDiagnostics["stats"]): string {
const mode = stats.largeSceneMode ? "large-scene" : "standard";
const shadows = stats.shadowsEnabled ? "shadows on" : "shadows off";
return `${mode}; target ${stats.targetRenderFps} fps; actual ${stats.actualRenderFps.toFixed(1)} fps; stats refresh ${stats.statsRefreshIntervalMs}ms ${stats.statsRefreshRenderCount}/${stats.statsRefreshSkipCount}; dpr ${stats.renderPixelRatio.toFixed(2)}; buffer preserved ${stats.preserveDrawingBufferEnabled}; readback renders ${stats.readbackRenderCount}; ${shadows}; skipped ${stats.renderSkipCount}; hover ${stats.hoverPickIntervalMs}ms; frozen ${stats.frozenStaticObjectCount} prefrozen ${stats.preFrozenMeshCloneCount} spinSkip ${stats.spinningScanSkippedCount}; instanced ${stats.instancedMeshObjectCount}/${stats.instancedMeshBatchCount}/${stats.instancedMeshDrawCount} matrices ${stats.instancedMeshMatrixUpdateCount} cull ${stats.instancedMeshFrustumCulledCount} static ${stats.instancedMeshStaticMatrixCount} elidedLocal ${stats.instancedLocalObjectElisionCount}; manual roots ${stats.manualMatrixRootCount} updates ${stats.manualMatrixUpdateCount}; primitive geometries ${stats.primitiveGeometryCount}; mesh cache ${stats.meshCacheSourceCount} sources ${stats.meshCacheHitCount}/${stats.meshCacheMissCount} hit/miss retained ${stats.retainedMeshGeometryCount}g/${stats.retainedMeshMaterialCount}m; bounds cache ${stats.sceneObjectBoundsCount} fast ${stats.fastPickProxyBoundsCount} scratch ${stats.pickBoundsScratchTransformCount} source ${stats.meshSourceBoundsCount} hoverProxy ${stats.hoverProxyBoundsHitCount} cached ${stats.hoverCachedBoundsHitCount}/fallback ${stats.hoverRootBoundsFallbackCount} camera traversals ${stats.cameraFitTraversalCount}; scene batches ${stats.sceneRootBatchCount}/${stats.batchedSceneRootCount} suppressed ${stats.sceneLoadSuppressedRenderCount} yields ${stats.sceneBuildYieldCount}; state payload ${stats.statePayloadBodyCount}/${stats.mergedBodyStateCount} reduced ${stats.reducedStateFrameCount} incremental ${stats.incrementalBodyMergeCount} poll ${stats.stateBasePollIntervalMs}/${stats.statePausedPollIntervalMs}/${stats.stateLastScheduledPollIntervalMs}ms ${stats.statePollRequestCount}/${stats.stateActivePollRequestCount}/${stats.statePausedPollRequestCount} semantic ${stats.stateParsedPollFrameCount}/${stats.stateForwardedPollFrameCount}/${stats.stateSkippedDuplicatePollFrameCount} hash ${stats.stateHashedPollFrameCount}/${stats.stateSkippedDuplicateHashPollFrameCount}/${stats.stateSkippedDuplicateSemanticPollFrameCount} notModified ${stats.stateNotModifiedPollFrameCount}; ui cache physics ${stats.objectPhysicsProfileCacheHitCount}/${stats.objectPhysicsProfileCacheMissCount} builder ${stats.builderPhysicsProfileCacheHitCount}/${stats.builderPhysicsProfileCacheMissCount} text ${stats.textWriteCount}/${stats.textWriteSkipCount} selector ${stats.textSelectorCacheHitCount}/${stats.textSelectorCacheMissCount} diagnostics ${stats.diagnosticsPanelRenderCount}/${stats.diagnosticsPanelSkipCount} builderPanels ${stats.builderPanelRenderCount}/${stats.builderPanelDeferredRenderCount}/${stats.builderPanelCoalescedRenderCount}; drag ${stats.dragMoveEventCount}/${stats.dragAppliedMoveCount}/${stats.dragCoalescedMoveCount}; pick targets ${stats.hoverPickTargetCount}/${stats.pickProxyCount}; state apply ${stats.appliedBodyStateCount}/skip ${stats.skippedBodyStateCount}; unchanged frames ${stats.unchangedFrameCount}; released ${stats.releasedGeometryCount}g/${stats.releasedMaterialCount}m/${stats.releasedTextureCount}t`;
return `${mode}; target ${stats.targetRenderFps} fps; actual ${stats.actualRenderFps.toFixed(1)} fps; stats refresh ${stats.statsRefreshIntervalMs}ms ${stats.statsRefreshRenderCount}/${stats.statsRefreshSkipCount}; dpr ${stats.renderPixelRatio.toFixed(2)}; buffer preserved ${stats.preserveDrawingBufferEnabled}; readback renders ${stats.readbackRenderCount}; ${shadows}; skipped ${stats.renderSkipCount}; hover ${stats.hoverPickIntervalMs}ms; frozen ${stats.frozenStaticObjectCount} prefrozen ${stats.preFrozenMeshCloneCount} spinSkip ${stats.spinningScanSkippedCount}; instanced ${stats.instancedMeshObjectCount}/${stats.instancedMeshBatchCount}/${stats.instancedMeshDrawCount} matrices ${stats.instancedMeshMatrixUpdateCount} cull ${stats.instancedMeshFrustumCulledCount} static ${stats.instancedMeshStaticMatrixCount} elidedLocal ${stats.instancedLocalObjectElisionCount} virtualRoots ${stats.virtualInstancedRootCount}; manual roots ${stats.manualMatrixRootCount} updates ${stats.manualMatrixUpdateCount}; primitive geometries ${stats.primitiveGeometryCount}; mesh cache ${stats.meshCacheSourceCount} sources ${stats.meshCacheHitCount}/${stats.meshCacheMissCount} hit/miss retained ${stats.retainedMeshGeometryCount}g/${stats.retainedMeshMaterialCount}m; bounds cache ${stats.sceneObjectBoundsCount} fast ${stats.fastPickProxyBoundsCount} scratch ${stats.pickBoundsScratchTransformCount} source ${stats.meshSourceBoundsCount} hoverProxy ${stats.hoverProxyBoundsHitCount} cached ${stats.hoverCachedBoundsHitCount}/fallback ${stats.hoverRootBoundsFallbackCount} camera traversals ${stats.cameraFitTraversalCount}; scene batches ${stats.sceneRootBatchCount}/${stats.batchedSceneRootCount} suppressed ${stats.sceneLoadSuppressedRenderCount} yields ${stats.sceneBuildYieldCount}; state payload ${stats.statePayloadBodyCount}/${stats.mergedBodyStateCount} reduced ${stats.reducedStateFrameCount} incremental ${stats.incrementalBodyMergeCount} poll ${stats.stateBasePollIntervalMs}/${stats.statePausedPollIntervalMs}/${stats.stateLastScheduledPollIntervalMs}ms ${stats.statePollRequestCount}/${stats.stateActivePollRequestCount}/${stats.statePausedPollRequestCount} semantic ${stats.stateParsedPollFrameCount}/${stats.stateForwardedPollFrameCount}/${stats.stateSkippedDuplicatePollFrameCount} hash ${stats.stateHashedPollFrameCount}/${stats.stateSkippedDuplicateHashPollFrameCount}/${stats.stateSkippedDuplicateSemanticPollFrameCount} notModified ${stats.stateNotModifiedPollFrameCount}; ui cache physics ${stats.objectPhysicsProfileCacheHitCount}/${stats.objectPhysicsProfileCacheMissCount} builder ${stats.builderPhysicsProfileCacheHitCount}/${stats.builderPhysicsProfileCacheMissCount} text ${stats.textWriteCount}/${stats.textWriteSkipCount} selector ${stats.textSelectorCacheHitCount}/${stats.textSelectorCacheMissCount} diagnostics ${stats.diagnosticsPanelRenderCount}/${stats.diagnosticsPanelSkipCount} builderPanels ${stats.builderPanelRenderCount}/${stats.builderPanelDeferredRenderCount}/${stats.builderPanelCoalescedRenderCount}; drag ${stats.dragMoveEventCount}/${stats.dragAppliedMoveCount}/${stats.dragCoalescedMoveCount}; pick targets ${stats.hoverPickTargetCount}/${stats.pickProxyCount}; state apply ${stats.appliedBodyStateCount}/skip ${stats.skippedBodyStateCount}; unchanged frames ${stats.unchangedFrameCount}; released ${stats.releasedGeometryCount}g/${stats.releasedMaterialCount}m/${stats.releasedTextureCount}t`;
}
function renderDiagnosticsPanel(
@ -2862,6 +2864,7 @@ function renderDiagnosticsPanel(
data.instancedMeshFrustumCulledCount = String(diagnostics.stats.instancedMeshFrustumCulledCount);
data.instancedMeshStaticMatrixCount = String(diagnostics.stats.instancedMeshStaticMatrixCount);
data.instancedLocalObjectElisionCount = String(diagnostics.stats.instancedLocalObjectElisionCount);
data.virtualInstancedRootCount = String(diagnostics.stats.virtualInstancedRootCount);
data.manualMatrixRootCount = String(diagnostics.stats.manualMatrixRootCount);
data.manualMatrixUpdateCount = String(diagnostics.stats.manualMatrixUpdateCount);
data.primitiveGeometryCount = String(diagnostics.stats.primitiveGeometryCount);

View File

@ -166,6 +166,7 @@ export class UniversalPreviewer {
private readonly spinningObjects: THREE.Object3D[] = [];
private readonly hoverOutlineBounds = new THREE.Box3();
private readonly hoverOutline = new THREE.Box3Helper(this.hoverOutlineBounds, "#38bdf8");
private readonly virtualInstancedRoot = new THREE.Object3D();
private readonly scratchBounds = new THREE.Box3();
private readonly scratchPickWorldBounds = new THREE.Box3();
private readonly scratchPickLocalBounds = new THREE.Box3();
@ -234,6 +235,7 @@ export class UniversalPreviewer {
private instancedMeshFrustumCulledCount = 0;
private instancedMeshStaticMatrixCount = 0;
private instancedLocalObjectElisionCount = 0;
private virtualInstancedRootCount = 0;
private manualMatrixRootCount = 0;
private manualMatrixUpdateCount = 0;
private releasedGeometryCount = 0;
@ -316,6 +318,9 @@ export class UniversalPreviewer {
this.scene.environment = this.environmentTarget.texture;
environmentGenerator.dispose();
this.scene.add(this.root);
this.virtualInstancedRoot.name = "virtual_instanced_root";
this.virtualInstancedRoot.matrixAutoUpdate = false;
this.virtualInstancedRoot.updateMatrixWorld(true);
this.focusMarker.visible = false;
this.focusMarker.renderOrder = 50;
this.scene.add(this.focusMarker);
@ -557,6 +562,7 @@ export class UniversalPreviewer {
instancedMeshFrustumCulledCount: this.instancedMeshFrustumCulledCount,
instancedMeshStaticMatrixCount: this.instancedMeshStaticMatrixCount,
instancedLocalObjectElisionCount: this.instancedLocalObjectElisionCount,
virtualInstancedRootCount: this.virtualInstancedRootCount,
manualMatrixRootCount: this.manualMatrixRootCount,
manualMatrixUpdateCount: this.manualMatrixUpdateCount,
primitiveGeometryCount: this.primitiveGeometryCache.size,
@ -1159,6 +1165,7 @@ export class UniversalPreviewer {
this.instancedMeshFrustumCulledCount = 0;
this.instancedMeshStaticMatrixCount = 0;
this.instancedLocalObjectElisionCount = 0;
this.virtualInstancedRootCount = 0;
this.manualMatrixRootCount = 0;
this.manualMatrixUpdateCount = 0;
this.sceneObjectBounds.makeEmpty();
@ -2128,9 +2135,13 @@ export class UniversalPreviewer {
}
binding.root.updateWorldMatrix(true, false);
this.scratchLocalWorldMatrix.multiplyMatrices(binding.root.matrixWorld, binding.localMatrix);
for (const submesh of binding.batch.submeshes) {
this.scratchMatrix.multiplyMatrices(this.scratchLocalWorldMatrix, submesh.sourceMatrix);
submesh.mesh.setMatrixAt(binding.index, this.scratchMatrix);
this.writeInstancedVisualMatrix(binding.batch, binding.index, this.scratchLocalWorldMatrix);
}
private writeInstancedVisualMatrix(batch: InstancedVisualBatch, index: number, matrix: THREE.Matrix4): void {
for (const submesh of batch.submeshes) {
this.scratchMatrix.multiplyMatrices(matrix, submesh.sourceMatrix);
submesh.mesh.setMatrixAt(index, this.scratchMatrix);
submesh.mesh.instanceMatrix.needsUpdate = true;
}
this.instancedMeshMatrixUpdateCount += 1;
@ -2154,6 +2165,10 @@ export class UniversalPreviewer {
}
private async addObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise<void> {
if (await this.addVirtualInstancedObject(object, token, sceneRoots)) {
return;
}
const root = new THREE.Group();
root.name = object.name ?? object.id;
root.visible = object.visible !== false;
@ -2210,6 +2225,64 @@ export class UniversalPreviewer {
this.updateInstancedVisualMatrix(object.id);
}
this.objectsById.set(object.id, { manifest: object, root });
this.registerObjectMetadata(object, root);
}
private async addVirtualInstancedObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise<boolean> {
if (!this.isInstancedMeshCandidate(object)) {
return false;
}
const key = this.meshCacheKey(object.geometry, object.material);
if (!this.instancedMeshBatchCapacities.has(key)) {
return false;
}
let batch: InstancedVisualBatch;
try {
batch = await this.getInstancedMeshBatch(object.geometry, object.material, key, sceneRoots);
} catch {
return false;
}
if (token !== this.loadToken) {
return true;
}
const sourceBounds = this.meshSourceBounds.get(key);
if (!sourceBounds || sourceBounds.isEmpty() || batch.submeshes.length === 0 || batch.used >= batch.capacity) {
return false;
}
const localMatrix = this.createPoseMatrix(object.pose);
const index = batch.used;
batch.used += 1;
this.instancedVisualBindings.set(object.id, {
batch,
index,
root: this.virtualInstancedRoot,
localMatrix,
});
this.writeInstancedVisualMatrix(batch, index, localMatrix);
this.instancedMeshObjectCount += 1;
this.instancedLocalObjectElisionCount += 1;
this.virtualInstancedRootCount += 1;
this.loadedMeshCount += 1;
this.spinningScanSkippedCount += 1;
const pickTarget = this.createPickTargetFromWorldMatrix(sourceBounds, localMatrix, object.id);
if (pickTarget) {
this.fastPickProxyBoundsCount += 1;
this.sceneObjectBounds.union(pickTarget.worldBounds);
this.sceneObjectBoundsCount += 1;
this.pickBoundsById.set(object.id, pickTarget);
if (this.shouldIncludeHoverPickTarget(object, true)) {
this.pickTargets.push(pickTarget);
}
}
this.objectsById.set(object.id, { manifest: object, root: this.virtualInstancedRoot });
this.registerObjectMetadata(object, this.virtualInstancedRoot);
return true;
}
private registerObjectMetadata(object: PreviewObject, root: THREE.Object3D): void {
if (object.editableGroup) {
const group = this.editableGroups.get(object.editableGroup) ?? [];
if (!group.includes(object.id)) {
@ -2228,16 +2301,13 @@ export class UniversalPreviewer {
if (!this.bodySourceOffsets.has(object.body)) {
this.bodySourceOffsets.set(object.body, [...sourcePose] as [number, number, number]);
}
} else {
this.objectBodyIds.set(object.id, []);
}
if (object.body) {
const items = this.bodyBindings.get(object.body) ?? [];
items.push({ manifest: object, root });
this.bodyBindings.set(object.body, items);
this.bodyBoundObjectCount += 1;
return;
}
this.objectBodyIds.set(object.id, []);
}
private async addObjects(objects: PreviewObject[], token: number): Promise<void> {
@ -2448,6 +2518,18 @@ export class UniversalPreviewer {
return this.createPickTargetFromBounds(localBounds, worldBounds, manifestId);
}
private createPickTargetFromWorldMatrix(
sourceBounds: THREE.Box3,
worldMatrix: THREE.Matrix4,
manifestId: string,
): PickBoundsTarget | undefined {
const worldBounds = this.transformBoundsInto(sourceBounds, worldMatrix, this.scratchPickWorldBounds);
if (worldBounds.isEmpty()) {
return undefined;
}
return this.createPickTargetFromBounds(worldBounds, worldBounds, manifestId);
}
private createPickTargetFromBounds(
localBounds: THREE.Box3,
worldBounds: THREE.Box3,

View File

@ -218,6 +218,7 @@ export interface RendererStats {
instancedMeshFrustumCulledCount: number;
instancedMeshStaticMatrixCount: number;
instancedLocalObjectElisionCount: number;
virtualInstancedRootCount: number;
manualMatrixRootCount: number;
manualMatrixUpdateCount: number;
primitiveGeometryCount: number;