@threenative/core 0.3.11 → 0.3.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -0,0 +1,710 @@
1
+ import {
2
+ type Box3,
3
+ type Camera,
4
+ type InstancedMesh,
5
+ type Material,
6
+ Matrix4,
7
+ type Object3D,
8
+ Vector3,
9
+ } from "three";
10
+ import { renderGroup, uniform } from "three/tsl";
11
+ import type { BundleGroup } from "three/webgpu";
12
+ import { lodChainOf } from "./model-lod.js";
13
+ import {
14
+ VIRTUAL_SHADOW_KEY_LAYER,
15
+ VIRTUAL_SHADOW_SMALL_CASTER_LAYER,
16
+ } from "./render/virtual-shadow-layers.js";
17
+ import {
18
+ type ITemporalLod,
19
+ advanceTemporalLod,
20
+ worldLodMaterial,
21
+ } from "./render/world-impostor-surface.js";
22
+ import type { IRendererLike } from "./renderer.js";
23
+ import { markStatic } from "./static-transform.js";
24
+ import type { ICasterScaleMesh, SharedBatch } from "./world-cell-batches.js";
25
+ import { levelTriangles } from "./world-cell-chunks.js";
26
+ import type { IAssetPart, IBatchShape, ICellBatch, IKeyDescriptor } from "./world-cell-data.js";
27
+ import { cullDistance, isAlphaFoliage } from "./world-cell-impostors.js";
28
+ import type { IAssetState } from "./world-cell-models.js";
29
+ import {
30
+ UNDITHERED_LOD_WIDTH,
31
+ assertSlotFree,
32
+ freshMeshFor,
33
+ indirectView,
34
+ redressMaterial,
35
+ } from "./world-cell-render-util.js";
36
+ import type { ICellRenderHost } from "./world-cell-render.js";
37
+ import {
38
+ VIRTUAL_SHADOW_CASTER_LAYER,
39
+ VIRTUAL_SHADOW_WIDE_CASTER_LAYER,
40
+ } from "./world-chunk-shadow.js";
41
+ import {
42
+ DRAW_ARGS_BYTES,
43
+ type IAssetSlot,
44
+ type ILiveAsset,
45
+ type IMeshDraw,
46
+ type IShadowLevel,
47
+ type WorldGpuScene,
48
+ liveKeyInstances,
49
+ } from "./world-gpu-scene.js";
50
+ import { frustumPlanes } from "./world-gpu-types.js";
51
+ import { localClip, localPoint } from "./world-root-frame.js";
52
+
53
+ /**
54
+ * The mesh a key draws: its shape, its level's material, and the dress that points it at the GPU
55
+ * scene's own buffers once the scene can run.
56
+ *
57
+ * A key's mesh is a view over shared storage, not a copy of the world: the same attributes, a fresh
58
+ * object (three binds the `instanceMatrix` an object held when it built its node), and an indirect
59
+ * record that names the region the dispatch compacts into. Everything here is that translation, plus
60
+ * the gate table the dispatch reads for the asset the key belongs to.
61
+ */
62
+
63
+ /** The gate table one asset publishes to the dispatch: its slots plus the part offsets it draws. */
64
+ export interface IPublishedGpuGates extends IAssetSlot {
65
+ readonly locals: readonly (readonly Float32Array[])[];
66
+ }
67
+
68
+ /** What a dress needs from the renderer it dresses for. */
69
+ export interface ICellGpuDressHost {
70
+ // The render host, by the names this module calls.
71
+ add(object: Object3D): void;
72
+ asset(id: string): IAssetState | undefined;
73
+ camera(): Camera | undefined;
74
+ canonical(id: string): string;
75
+ carryPrewarm(old: ICasterScaleMesh, next: ICasterScaleMesh): void;
76
+ isBundleHome(shared: SharedBatch): boolean;
77
+ renderer(): IRendererLike | undefined;
78
+ /** The world root's own `matrixWorld`: the frame its placements are recorded in. */
79
+ root(): Matrix4;
80
+
81
+ // The batches, the scene and the state the dress shares with the rest of the renderer.
82
+ shared(): Map<string, SharedBatch>;
83
+ retired(): Map<string, SharedBatch>;
84
+ resident(): Map<string, number>;
85
+ gpuScene(): WorldGpuScene;
86
+ lodMaterials(): Map<string, { readonly source: Material; readonly material: Material }>;
87
+ /** The adaptive LOD bias the kernel and the materials scale distance by. */
88
+ lodDistanceBias(): Parameters<typeof worldLodMaterial>[6];
89
+ lodHysteresis(): number;
90
+ lodTransition(): "band" | "none" | "temporal";
91
+ lodSpatial(): boolean;
92
+ receiveShadow(): boolean;
93
+ preserveAuthoredParts(): boolean;
94
+ freshCount(): number;
95
+ extentBounds(): Box3;
96
+ visibleSquares(): Set<string>;
97
+ freshAllowance(): number;
98
+
99
+ // The bundle record and the shadow claims, asked through the facade.
100
+ attach(shared: SharedBatch): void;
101
+ bumpBundle(group: BundleGroup): void;
102
+ bundleIn(shared: SharedBatch, reuseSafety?: boolean): void;
103
+ bundleOut(shared: SharedBatch): void;
104
+ shardOf(shared: SharedBatch): BundleGroup;
105
+ shadowFloorOf(assetId: string): number;
106
+ shadowKeyFor(key: IKeyDescriptor, part: IAssetPart): void;
107
+ }
108
+
109
+ /** The scratch a draw's own planes are built in, reused per frame. */
110
+ const _gpuEye = new Vector3();
111
+ const _cullProjScreen = new Matrix4();
112
+
113
+ export class CellGpuDress {
114
+ readonly #host: ICellGpuDressHost;
115
+
116
+ constructor(host: ICellGpuDressHost) {
117
+ this.#host = host;
118
+ }
119
+
120
+ readonly #publishedGpuGates = new Map<string, IPublishedGpuGates>();
121
+ readonly #gpuLevelKeys = new Map<string, Array<{ firstKey: number; parts: number }>>();
122
+ readonly #gpuPlanes = new Float32Array(24);
123
+
124
+ readonly #lodEye = uniform(new Vector3()).setGroup(renderGroup);
125
+
126
+ /** UE's two lagged view origins and their blend, for `lodTransition: "temporal"`. */
127
+ readonly #temporalLod: ITemporalLod = {
128
+ from: new Vector3(),
129
+ to: new Vector3(),
130
+ fromTime: Number.NaN,
131
+ toTime: Number.NaN,
132
+ alpha: 1,
133
+ };
134
+
135
+ readonly #lodFrom = uniform(this.#temporalLod.from).setGroup(renderGroup);
136
+
137
+ readonly #lodTo = uniform(this.#temporalLod.to).setGroup(renderGroup);
138
+
139
+ readonly #lodAlpha = uniform(1).setGroup(renderGroup);
140
+
141
+ /** Seconds since this renderer started; a swap stamps it so `worldLodMaterial` can fade the change. */
142
+ readonly #lodClock = uniform(0).setGroup(renderGroup);
143
+
144
+ readonly #lodClockOrigin = performance.now();
145
+
146
+ /**
147
+ * The shape the coarse wide half draws for one `(level, part)`, or `fallback` when the level has no
148
+ * honest coarse counterpart. Shared by {@link #shapeFor} and the prewarm, so the mesh minted behind
149
+ * the gate carries the same geometry the swap would later ask for — a prewarm built from the
150
+ * coarsest level's part 0 and then handed back unchanged is the wrong shape for good.
151
+ */
152
+ wideShape(
153
+ asset: IAssetState | undefined,
154
+ level: number,
155
+ part: number,
156
+ fallback: IBatchShape,
157
+ ): IBatchShape {
158
+ if (this.#host.preserveAuthoredParts()) return fallback;
159
+ const terminal = asset?.levels.at(-1);
160
+ // The whole-asset impostor is the one case where a part index has no meaning: it is a single
161
+ // representation of every LOD0 part, so every part routes through it. `terminal?.[0]` is only
162
+ // that shape. On the source-only path the terminal must have a part at this index with the same
163
+ // role — an alpha slot drawn with an opaque part's shape (or vice versa) is a different object,
164
+ // and a terminal with fewer parts must not fall back to part 0's, which duplicates it.
165
+ if (asset?.impostor !== undefined) {
166
+ const coarse = terminal?.[0];
167
+ if (coarse !== undefined) return coarse;
168
+ }
169
+ const coarse = terminal?.[part];
170
+ const source = asset?.levels[level]?.[part];
171
+ if (
172
+ coarse !== undefined &&
173
+ source !== undefined &&
174
+ isAlphaFoliage(source.material) === isAlphaFoliage(coarse.material)
175
+ )
176
+ return coarse;
177
+ return fallback;
178
+ }
179
+
180
+ shapeFor(
181
+ entry: ICellBatch,
182
+ role: "cluster" | "key" | "main" | "wide",
183
+ level = entry.level,
184
+ ): IBatchShape {
185
+ // A batch cast at a finer level than its own (`#castLevelOf`) draws that level's part.
186
+ const own =
187
+ level === entry.level
188
+ ? { geometry: entry.batch.geometry, material: entry.batch.material }
189
+ : (this.#host.asset(entry.asset)?.levels[level]?.[entry.part] as IAssetPart);
190
+ const shape =
191
+ role === "wide"
192
+ ? this.wideShape(this.#host.asset(entry.asset), level, entry.part, {
193
+ geometry: own.geometry,
194
+ material: own.material,
195
+ })
196
+ : { geometry: own.geometry, material: own.material };
197
+ return {
198
+ ...shape,
199
+ material: this.lodSurface(entry.asset, level, entry.part, shape.material),
200
+ };
201
+ }
202
+
203
+ /** The material a batch of this level and part draws: `source` with the LOD gate's mask, when the asset has one. */
204
+ lodSurface(assetId: string, level: number, partIndex: number, source: Material): Material {
205
+ assertSlotFree(source, assetId);
206
+ const asset = this.#host.asset(assetId);
207
+ const part = asset?.levels[level]?.[partIndex];
208
+ if (this.#host.lodHysteresis() <= 0 || !asset || !part || asset.distances.length < 2)
209
+ return source;
210
+ const publishedRanges = !this.#host.gpuScene().on;
211
+ const floor = this.#host.shadowFloorOf(assetId);
212
+ const key = `${assetId}:${level}:${partIndex}:${asset.distances.length}:${publishedRanges ? 1 : 0}:${floor}`;
213
+ let cached = this.#host.lodMaterials().get(key);
214
+ if (cached !== undefined && cached.source !== source) {
215
+ cached.material.dispose();
216
+ this.#host.lodMaterials().delete(key);
217
+ cached = undefined;
218
+ }
219
+ if (cached === undefined) {
220
+ const material = worldLodMaterial(
221
+ source,
222
+ part.local,
223
+ asset.distances,
224
+ level,
225
+ // Outside "band" the gate is too thin to cover a pixel step: each placement takes one level.
226
+ this.#host.lodTransition() === "band" ? this.#host.lodHysteresis() : UNDITHERED_LOD_WIDTH,
227
+ this.#lodEye,
228
+ this.#host.lodDistanceBias(),
229
+ this.#host.lodSpatial(),
230
+ publishedRanges,
231
+ // "none" pops: no clock, so a late refilter does not dissolve either.
232
+ this.#host.lodTransition() === "none" ? undefined : this.#lodClock,
233
+ this.#host.lodTransition() === "temporal"
234
+ ? { from: this.#lodFrom, to: this.#lodTo, alpha: this.#lodAlpha }
235
+ : undefined,
236
+ floor,
237
+ );
238
+ cached = { source, material };
239
+ this.#host.lodMaterials().set(key, cached);
240
+ }
241
+ return cached.material;
242
+ }
243
+
244
+ updateLodEye(x: number, y: number, z: number): void {
245
+ this.#lodEye.value.set(x, y, z);
246
+ this.#lodClock.value = (performance.now() - this.#lodClockOrigin) / 1000;
247
+ if (this.#host.lodTransition() !== "temporal") return;
248
+ advanceTemporalLod(this.#temporalLod, this.#lodEye.value, this.#lodClock.value);
249
+ this.#lodAlpha.value = this.#temporalLod.alpha;
250
+ }
251
+
252
+ refreshLodMaterials(asset: IAssetState): void {
253
+ for (const shared of this.#host.shared().values()) {
254
+ if (!shared.mesh.name.startsWith(`${asset.id}:`)) continue;
255
+ const [levelText, partText] = shared.mesh.name.slice(asset.id.length + 1).split(":");
256
+ const level = Number(levelText);
257
+ const partIndex = Number(partText?.split("@")[0]);
258
+ const part = asset.levels[level]?.[partIndex];
259
+ if (part !== undefined) {
260
+ const material = this.lodSurface(asset.id, level, partIndex, part.material);
261
+ if (
262
+ material.userData.tnPublishedLodRange === true &&
263
+ shared.mesh.geometry.getAttribute("tnPublishedLodRange") === undefined &&
264
+ shared.mesh.count === 0
265
+ )
266
+ shared.rebind(part.geometry, material);
267
+ else shared.surface(material);
268
+ this.#host.bundleOut(shared);
269
+ this.#host.bundleIn(shared);
270
+ }
271
+ }
272
+ }
273
+
274
+ impostorDrawn(): number {
275
+ let drawn = 0;
276
+ for (const shared of this.#host.shared().values()) {
277
+ if (
278
+ shared.role === "main" &&
279
+ shared.mesh.visible &&
280
+ Reflect.get(shared.mesh.material, "userData")?.tnWholeAssetImpostor === true
281
+ )
282
+ drawn += shared.live;
283
+ }
284
+ return drawn;
285
+ }
286
+
287
+ /**
288
+ * The shadow half of the split, and the two granularities of it. A caster mesh lives alone on
289
+ * `VIRTUAL_SHADOW_CASTER_LAYER` — one per world-grid square, which a level whose window is a
290
+ * fraction of the ring culls down to the squares it covers — and a wide mesh alone on
291
+ * `VIRTUAL_SHADOW_WIDE_CASTER_LAYER`, one per key, which a level whose window covers the ring
292
+ * submits once. The level cameras draw one of the two layers and never both, so a key costs the
293
+ * main pass one draw, a fine level a few and a wide level one. Neither receives: nothing but a
294
+ * shadow level ever sees either. A main mesh keeps layer 0 and casts nothing, because its records
295
+ * reach the shadow maps only through a caster half.
296
+ */
297
+ dressMesh(shared: SharedBatch, receiveShadow: boolean): void {
298
+ const mesh = shared.mesh;
299
+ const role = shared.role;
300
+ // Every role's records are written into the instance buffer, never moved in the world, and the
301
+ // mesh is created and released per role — so this is the one place that covers a fresh mesh, a
302
+ // rebound one and the three roles. Static here is only safe because every write announces
303
+ // itself: `instanceMatrix.needsUpdate` bumps the attribute's version, which is what a settled
304
+ // draw watches to know it still has to scan.
305
+ markStatic(mesh);
306
+ if (role !== "main") {
307
+ mesh.layers.set(
308
+ role === "cluster"
309
+ ? VIRTUAL_SHADOW_CASTER_LAYER
310
+ : role === "key"
311
+ ? VIRTUAL_SHADOW_KEY_LAYER
312
+ : shared.smallCaster
313
+ ? VIRTUAL_SHADOW_SMALL_CASTER_LAYER
314
+ : VIRTUAL_SHADOW_WIDE_CASTER_LAYER,
315
+ );
316
+ mesh.castShadow = true;
317
+ mesh.receiveShadow = false;
318
+ return;
319
+ }
320
+ mesh.layers.set(0);
321
+ mesh.castShadow = false;
322
+ mesh.receiveShadow = receiveShadow;
323
+ // The origin a draw of this mesh is counted under until the GPU scene dresses it
324
+ // (`RenderPassBudget`). `#dressGpu` runs straight after this and overwrites it with `gpuScene`
325
+ // when the key really is dressed, so what survives here is a main batch the CPU path draws per
326
+ // object — a backend with no compute, `gpuScene: false`, or a dress that gave up. A caster half
327
+ // returns above and keeps no origin: it lives off layer 0, so the main pass never counts it.
328
+ mesh.userData.tnDrawSource = "instanced";
329
+ // Nothing to hang off a main mesh: the window is narrowed by `#cullMainPass` for the whole set,
330
+ // because a batch that drew nothing is hidden and three never reaches an invisible mesh's own
331
+ // hooks — a mesh that could only re-narrow itself in its `onBeforeRender` would stay hidden for
332
+ // as long as the camera looked away. That leaves `onBeforeRender` to the prewarm borrow alone.
333
+ }
334
+
335
+ /**
336
+ * Name one main key to the GPU scene, and dress its mesh against the scene's live buffers.
337
+ *
338
+ * A caster or wide key is named `@x,z` or `@*` and belongs to the shadow passes, which the GPU scene
339
+ * does not touch, so those are left exactly as they were.
340
+ *
341
+ * The key is recorded whether or not the scene is on, because a prewarm mints a whole ring before
342
+ * the first frame that can answer whether this backend can run the scene, and a key recorded only
343
+ * when the dress happened is a key the scene is never told about. `#seedGpuKeys` comes back for
344
+ * those; see there.
345
+ */
346
+ adoptGpu(shared: SharedBatch, assetId: string, key: string, level: number, part: number): void {
347
+ if (shared.role !== "main") return;
348
+ const named = { asset: this.#host.canonical(assetId), key, level, part };
349
+ shared.main = named;
350
+ if (this.#host.gpuScene().on === false) return;
351
+ shared.gpu = named;
352
+ this.dressGpu(shared, named);
353
+ }
354
+
355
+ /**
356
+ * The coarse gate for the GPU-dressed main pass, computed per asset and reused across every level
357
+ * and part of it.
358
+ *
359
+ * A key's own CPU squares are the level the follow point picked when it built them, and the
360
+ * dispatch re-picks the level from the camera every frame — so a key the CPU never gave a cell to
361
+ * can be exactly the one the dispatch draws, and a per-key answer hid it: a tree walked into at a
362
+ * level it was not built at disappeared. One conservative answer per asset — any key holds a
363
+ * visible cell, or still owes its prewarm draw — is what shows all of them, and the indirect
364
+ * record decides what each one actually draws.
365
+ */
366
+ applyGpuMain(dressed: readonly { asset: string; shared: SharedBatch }[]): void {
367
+ const shown = new Map<string, boolean>();
368
+ for (const { asset, shared } of dressed) {
369
+ if (shown.get(asset) === true || shared.seenIn(this.#host.visibleSquares()))
370
+ shown.set(asset, true);
371
+ else if (shown.has(asset) === false) shown.set(asset, false);
372
+ }
373
+ for (const { asset, shared } of dressed) shared.applyGpuVisible(shown.get(asset) === true);
374
+ }
375
+
376
+ /**
377
+ * Point one main key's mesh at the GPU scene's buffers, and hand the asset's gate table over.
378
+ *
379
+ * The mesh's `instanceMatrix` becomes the shared compacted matrix buffer, its geometry a clone that
380
+ * shares the part's own attributes and carries this key's indirect record, and its whole-mesh
381
+ * frustum test is off — the dispatch already tested every instance against the camera's six
382
+ * planes, and the mesh's own bounds are the whole resident ring. Idempotent: a settled frame's
383
+ * buffers are the ones it was dressed against, and a regrow, a rebind or a `grow` replaces them,
384
+ * which is the only thing that brings a dressed mesh back through here.
385
+ *
386
+ * A key whose placements outgrew its region is regrown here rather than silently dropping instances
387
+ * against the capacity guard, which is what a fixed ceiling did to any key a walk filled past.
388
+ *
389
+ * The buffers are read after `scene.key` rather than before it, because minting the first key is
390
+ * what allocates them: a dress that gave up on their absence was a dress that never happened, and
391
+ * the only frame that would have retried it was one whose fast path had already found the mesh
392
+ * dressed. A regrow replaces them, so the attribute handed to the mesh is the one a draw will read.
393
+ */
394
+ dressGpu(shared: SharedBatch, key: IKeyDescriptor): void {
395
+ const scene = this.#host.gpuScene();
396
+ const asset = this.#host.asset(key.asset);
397
+ const part = asset?.levels[key.level]?.[key.part];
398
+ if (asset === undefined || part === undefined) return;
399
+ // The asset's own resident placements, not one level's share of them: a placement's level is
400
+ // decided per frame from where the camera is, so every level's region has to hold all of them.
401
+ const capacity = Math.max(shared.liveCeiling, this.#host.resident().get(key.asset) ?? 0);
402
+ const settled = scene.drawn;
403
+ const held = scene.regionOf(key.key);
404
+ // The args buffer and the drawn buffer are allocated and grown independently: minting a key
405
+ // grows `args` and leaves `drawn` the object it was, so the mesh's `instanceMatrix` and its
406
+ // indirect record can point at two different generations. The fast path used to watch only
407
+ // `drawn`, and a mesh left holding an old args record was one the dispatch no longer wrote —
408
+ // a forest that drew nothing while the readback said the counts were correct.
409
+ const geometry = shared.mesh.geometry;
410
+ const liveArgs = scene.args;
411
+ const bound =
412
+ liveArgs !== undefined &&
413
+ geometry.indirect === liveArgs &&
414
+ geometry.indirectOffset === (held?.argsIndex ?? -1) * DRAW_ARGS_BYTES;
415
+ if (
416
+ settled !== undefined &&
417
+ shared.mesh.instanceMatrix === settled &&
418
+ shared.mesh.frustumCulled === false &&
419
+ (held?.capacity ?? 0) >= capacity &&
420
+ bound &&
421
+ // Where the mesh hangs is part of what this pass owns: a batch that was retired and handed back
422
+ // by a rebind is a child of the world again, and the bundle that last recorded it no longer
423
+ // draws it. Without this the walk would re-mint a key into a bundle that is missing it.
424
+ this.#host.isBundleHome(shared)
425
+ ) {
426
+ // A sibling may have grown the level's capacity without moving this mesh, so the submission
427
+ // bound follows the live region rather than the dress that wrote it. See `gpuCount`.
428
+ shared.gpuCount = held?.capacity ?? shared.gpuCount;
429
+ this.#host.shadowKeyFor(key, part);
430
+ return;
431
+ }
432
+ const region = scene.key(key.key, new Float32Array(part.local.elements), capacity, {
433
+ group: `${key.asset}:${String(key.level)}`,
434
+ part: key.part,
435
+ // The whole run at once, so a part minted later lands in the slot `firstKey + part` names
436
+ // rather than at the end of the key space, where another level's key is in between.
437
+ parts: (asset.levels[key.level] as readonly IAssetPart[]).length,
438
+ });
439
+ if (region === undefined) return;
440
+ const levels = this.#gpuLevelKeys.get(key.asset) ?? [];
441
+ levels[key.level] = {
442
+ firstKey: region - key.part,
443
+ parts: asset.levels[key.level]?.length ?? 0,
444
+ };
445
+ this.#gpuLevelKeys.set(key.asset, levels);
446
+ const drawn = scene.drawn;
447
+ const args = scene.args;
448
+ const args2 = scene.regionOf(key.key);
449
+ if (drawn === undefined || args === undefined || args2 === undefined) return;
450
+ // Before the mesh is dressed, so the republish a replacement does takes the dressed branch and
451
+ // submits at this bound rather than at a zero the CPU never drew. See `gpuCount`.
452
+ shared.gpuCount = args2.capacity;
453
+ // Before the mesh is dressed, so the republish a replacement does takes the dressed branch: a
454
+ // batch that draws from the scene's buffers is shown by the per-asset gate in `#cullMainPass`,
455
+ // not by its own count.
456
+ shared.gpu = key;
457
+ const mesh = shared.mesh;
458
+ // Its own geometry object, so the indirect record is this mesh's, over the SAME attributes: the
459
+ // original is the shape the caster halves and a rebind still draw with. `clone()` would copy
460
+ // every vertex buffer of every key a second time.
461
+ const view = indirectView(mesh.geometry, args, args2.argsIndex * DRAW_ARGS_BYTES);
462
+ // A mesh three has already compiled cannot be re-dressed by writing fields onto it: its node
463
+ // binds the `instanceMatrix` the object held at that compile, and three keeps that binding for
464
+ // the object's whole life. A regrow is the same case — a new `drawn` attribute is a new binding
465
+ // for the same reason — so both take the same road: a fresh object carrying everything the old
466
+ // one had, and the old one let go. Measured on machinefall, where the prewarm had compiled every
467
+ // main batch on the CPU path: 3,724 indirect draws submitted in 2 s over records that were
468
+ // correct at draw time, and a dressed forest that drew nothing, until the meshes were fresh
469
+ // objects; a material of its own (below) never changed that on its own.
470
+ if (mesh.instanceMatrix !== drawn) {
471
+ const next = freshMeshFor(mesh, view, mesh.count) as ICasterScaleMesh;
472
+ redressMaterial(next);
473
+ this.#host.carryPrewarm(mesh, next);
474
+ this.seat(shared.replaceMesh(next), next);
475
+ next.instanceMatrix = drawn;
476
+ next.frustumCulled = false;
477
+ } else {
478
+ mesh.geometry = view;
479
+ mesh.instanceMatrix = drawn;
480
+ mesh.frustumCulled = false;
481
+ }
482
+ // What the record has to say for the draw to name a triangle: the view's own index count, which
483
+ // is the shape this key draws. The scene is told rather than left to guess, so its validation can
484
+ // hold the record against it.
485
+ scene.indexCount(key.key, view.index?.count ?? 0);
486
+ // The asset's gate table is built from the keys minted so far, so a level whose key is not minted
487
+ // yet carries no parts and the dispatch draws that level nowhere. Re-registering is a no-op while
488
+ // the table holds, and a rewrite when a key joined it.
489
+ scene.slot(key.asset, this.gatesOf(key.asset, asset));
490
+ // The origin this key's main-pass draws are counted under, read off the object at the draw
491
+ // (`RenderPassBudget`). Written after the mesh swap above, so a re-dressed fresh object carries
492
+ // it, and before `#bundleIn`, which supersedes it with `tnBundled` for a world with bundles on.
493
+ shared.mesh.userData.tnDrawSource = "gpuScene";
494
+ // The bundle the last settled frame replayed is now wrong: this pass minted or regrown a key,
495
+ // swapped the geometry, or took a fresh mesh object onto the scene's new buffers. Reaching here
496
+ // is one of the three, which is why this is the only place a re-record happens — the fast path
497
+ // above is every other frame of the walk.
498
+ this.#host.bundleIn(shared);
499
+ if (shared.bundled === true) this.#host.bumpBundle(this.#host.shardOf(shared));
500
+ // The shadow twin of this key, minted and dressed on the same pass that named the main one: a
501
+ // level that draws keys finds its mesh in the same frame the main pass found its buffer, and a
502
+ // regrown twin is re-dressed here rather than left on the buffer the dispatch replaced.
503
+ this.#host.shadowKeyFor(key, part);
504
+ }
505
+
506
+ /**
507
+ * The replacement takes the old object's place, and the old one is let go: `InstancedMesh.dispose`
508
+ * frees nothing the replacement shares — the vertex buffers and the part's own material belong to
509
+ * the refcount path that made them.
510
+ *
511
+ * Through `add` and `removeFromParent` rather than by writing `parent` and `children`, because
512
+ * three fires `childadded`/`childremoved` on the way and the clustered-mesh tracker answers the
513
+ * world's arrivals and departures by those alone. The old slot is restored afterwards, so the
514
+ * parent's traversal order — and so every draw's order within a frame — is what it was.
515
+ */
516
+ seat(old: InstancedMesh, next: InstancedMesh): void {
517
+ const parent = old.parent;
518
+ if (parent === null) this.#host.add(next);
519
+ else {
520
+ const at = parent.children.indexOf(old);
521
+ old.removeFromParent();
522
+ parent.add(next);
523
+ const here = parent.children.indexOf(next);
524
+ if (at >= 0 && here >= 0) {
525
+ parent.children.splice(here, 1);
526
+ parent.children.splice(at, 0, next);
527
+ }
528
+ }
529
+ old.dispose();
530
+ }
531
+
532
+ /**
533
+ * The asset's own gates, as the kernel reads them: the CPU path's switch distances and cull
534
+ * distance, and the scene key each level's parts draw into. A level with no minted key has no parts,
535
+ * so the dispatch draws nothing at that level rather than reading a key that is not there.
536
+ */
537
+ publishGpuGates(asset: IAssetState): void {
538
+ const gates = this.gatesOf(asset.id, asset);
539
+ this.#publishedGpuGates.set(asset.id, {
540
+ cull: gates.cull,
541
+ distances: [...gates.distances],
542
+ impostor: gates.impostor,
543
+ shadowFallback: gates.shadowFallback,
544
+ levels: gates.levels.map((level) => ({ ...level })),
545
+ locals: asset.levels.map((parts) =>
546
+ parts.map((part) => Float32Array.from(part.local.elements)),
547
+ ),
548
+ });
549
+ }
550
+
551
+ gatesOf(id: string, asset: IAssetState): IAssetSlot {
552
+ const gates: { firstKey: number; parts: number }[] = [];
553
+ // The level's own contiguous run, which is what the kernel's `firstKey + part` addresses. The
554
+ // owner records it when dressing the key; reading it back from the scene would make the mesh
555
+ // check agree with a corrupted GPU gate table instead of checking that table independently.
556
+ const keyed = this.#gpuLevelKeys.get(id);
557
+ for (const [level] of asset.levels.entries())
558
+ gates.push(keyed?.[level] ?? { firstKey: 0, parts: 0 });
559
+ return {
560
+ cull: cullDistance(asset.definition.maxDistance),
561
+ distances: asset.distances,
562
+ // A generated terminal gate is based on the unit asset sphere and scales per placement. An
563
+ // authored impostorDistance is already a world-metre cutoff and stays fixed across scales.
564
+ impostor: asset.impostor !== undefined && asset.definition.impostorDistance === undefined,
565
+ shadowFallback: asset.definition.lods === undefined,
566
+ levels: gates,
567
+ };
568
+ }
569
+
570
+ /**
571
+ * Dress every main batch the world already holds, the mirror of {@link #seedGpuSources} for the
572
+ * keys rather than the sources: the keys a prewarm minted on the loading screen were minted with
573
+ * the scene off, and a key is only named at mint time, so a ring built that way came up with an
574
+ * empty region table and every batch still drawing from its own buffer. The dispatch was drawing
575
+ * 21,094 placements into no region at all, and the validation marker said so — `compared=0` — for
576
+ * a scene that reported itself on.
577
+ *
578
+ * The pool is seeded with the rest: a retained key's mesh is handed back by a rebind rather than
579
+ * re-minted, and rebinding replaces the instance buffer, so a parked batch is undressed by the
580
+ * park and dressing it here is what leaves the walk with a key that is already in the table. From
581
+ * here every main batch carries `gpu`, which is what puts it on the dispatch's per-instance answer
582
+ * and off the CPU repack and the refilter.
583
+ */
584
+ seedGpuKeys(): void {
585
+ for (const shared of [...this.#host.shared().values()]) this.seedGpuKey(shared);
586
+ for (const shared of this.#host.retired().values()) this.seedGpuKey(shared);
587
+ }
588
+
589
+ /** Dress one undressed main batch, or leave a batch the scene does not touch. */
590
+ seedGpuKey(shared: SharedBatch): void {
591
+ // `main` is the key; `gpu` is the mesh pointing at the scene's buffers. A dressed mesh is left
592
+ // alone, and `#dressGpu` says so itself — it is idempotent against the buffers it was given.
593
+ if (shared.main === undefined || shared.gpu !== undefined) return;
594
+ this.dressGpu(shared, shared.main);
595
+ }
596
+
597
+ /**
598
+ * The main meshes the scene owns and the main meshes the world holds, live and pooled, which is
599
+ * the `dressed=N/M` the marker carries. A scene reporting itself on over a ring it never dressed
600
+ * read `dressed=0/21094` on nothing, so the number is the owner's: the scene cannot see the meshes.
601
+ */
602
+ gpuCensus(): { readonly dressed: number; readonly meshes: number } {
603
+ let dressed = 0;
604
+ let meshes = 0;
605
+ for (const batch of [...this.#host.shared().values(), ...this.#host.retired().values()]) {
606
+ if (batch.role !== "main") continue;
607
+ meshes += 1;
608
+ if (batch.gpu !== undefined) dressed += 1;
609
+ }
610
+ return { dressed, meshes };
611
+ }
612
+
613
+ /**
614
+ * Every dressed main mesh's own draw, and what this class's **live** state says it must be holding.
615
+ *
616
+ * The scene's own validation mirrors its own kernel, so a key, a record, a gate table and a mesh
617
+ * that do not correspond are one both sides reproduce and a check that reports `ok` over a forest
618
+ * drawn with another tree's geometry. These are the three numbers that are not the scene's: the
619
+ * mesh's own name, the record its own geometry points at (`indirectOffset`, which a dress wrote),
620
+ * and the instances the owner's own state selects for that name — `asset.distances` as
621
+ * {@link levelAt} reads it right now, `cullDistance(definition.maxDistance)`, the camera's own six
622
+ * planes over the scene's own placements, and each part's own offset composed in exactly as the
623
+ * dispatch composes it.
624
+ *
625
+ * Not the per-cell records this path's own refilter left behind: the GPU scene bypasses that
626
+ * refilter, so the moment it does, the records a mesh is checked against are a snapshot of a
627
+ * level selection that no longer applies. A far placement is then compared against a set that
628
+ * counted it at its near level, and the check reads `ok` over the picture it cannot see.
629
+ */
630
+ gpuDraws(): readonly IMeshDraw[] {
631
+ const camera = this.#host.camera();
632
+ if (camera === undefined) return [];
633
+ const lives = this.liveGates();
634
+ if (lives.size === 0) return [];
635
+ // The dispatch's own camera, its own planes: this is asked for inside the dispatch that is
636
+ // running, so the eye and the six planes are the ones the kernel is reading now — and, like the
637
+ // dispatch's, in the root's frame, because that is the frame the placements are recorded in.
638
+ const root = this.#host.root();
639
+ const planes = this.#gpuPlanes;
640
+ frustumPlanes(localClip(_cullProjScreen, camera, root), planes);
641
+ localPoint(_gpuEye.setFromMatrixPosition(camera.matrixWorld), root);
642
+ const expected = liveKeyInstances(
643
+ this.#host.gpuScene().placements,
644
+ (slot) => {
645
+ const id = this.#host.gpuScene().slotAsset(slot);
646
+ return id === undefined ? undefined : lives.get(id);
647
+ },
648
+ { planes, x: _gpuEye.x, y: _gpuEye.y, z: _gpuEye.z },
649
+ );
650
+ const draws: IMeshDraw[] = [];
651
+ const args = this.#host.gpuScene().args;
652
+ for (const shared of this.#host.shared().values()) {
653
+ if (shared.role !== "main" || shared.gpu === undefined) continue;
654
+ const geometry = shared.mesh.geometry;
655
+ // `indirectOffset` is typed as an offset or a list of them; a scene's own record is one
656
+ // number, and a list is not a record this check can name, so it is not compared.
657
+ const offset = geometry.indirectOffset;
658
+ if (geometry.indirect === undefined || typeof offset !== "number") continue;
659
+ const region = this.#host.gpuScene().regionOf(shared.mesh.name);
660
+ draws.push({
661
+ // The actual binding, asked of the mesh and the scene at this turn, not the record number:
662
+ // an offset can name the right record while the mesh reads an older args buffer with the
663
+ // same layout, and the field is what lets the check see a stale binding at all.
664
+ bound:
665
+ args !== undefined &&
666
+ geometry.indirect === args &&
667
+ offset === (region?.argsIndex ?? -1) * DRAW_ARGS_BYTES,
668
+ instances: expected.get(shared.mesh.name) ?? new Float32Array(0),
669
+ name: shared.mesh.name,
670
+ record: offset / DRAW_ARGS_BYTES,
671
+ });
672
+ }
673
+ return draws;
674
+ }
675
+
676
+ /**
677
+ * Every adopted asset's own gates as they stand right now, keyed by id.
678
+ *
679
+ * The part offsets are copied out of each part's `Matrix4` once per check, because the composition
680
+ * reads them as `Float32Array`s and a part's matrix is what the dispatch already composed with.
681
+ */
682
+ liveGates(): Map<string, ILiveAsset> {
683
+ const out = new Map<string, ILiveAsset>();
684
+ const slots = this.#host.gpuScene().gates();
685
+ for (const [slot] of slots.entries()) {
686
+ const id = this.#host.gpuScene().slotAsset(slot);
687
+ const asset = id === undefined ? undefined : this.#host.asset(id);
688
+ const published = id === undefined ? undefined : this.#publishedGpuGates.get(id);
689
+ if (asset === undefined || published === undefined) continue;
690
+ out.set(asset.id, {
691
+ cull: published.cull,
692
+ distances: published.distances,
693
+ id: asset.id,
694
+ impostor: published.impostor,
695
+ locals: published.locals,
696
+ });
697
+ }
698
+ return out;
699
+ }
700
+ /** Give back the gate tables, which a lost device makes stale. */
701
+ release(): void {
702
+ this.#publishedGpuGates.clear();
703
+ this.#gpuLevelKeys.clear();
704
+ }
705
+
706
+ /** The clock a swap stamps a rebuilt key's ranges with, in seconds since this renderer started. */
707
+ get clockSeconds(): number {
708
+ return this.#lodClock.value as number;
709
+ }
710
+ }