@threenative/core 0.3.11 → 0.3.12

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 (157) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10566 -22552
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
@@ -0,0 +1,510 @@
1
+ import {
2
+ Fn,
3
+ If,
4
+ Loop,
5
+ Return,
6
+ abs,
7
+ atomicAdd,
8
+ float,
9
+ instanceIndex,
10
+ int,
11
+ length,
12
+ max,
13
+ storage,
14
+ vec3,
15
+ } from "three/tsl";
16
+ import { biasedLodDistance } from "./model-lod.js";
17
+ import { type DepthPyramid, type IKernelOcclusion, occludedBy } from "./render/depth-pyramid.js";
18
+ import type {
19
+ IAssetSlot,
20
+ IGpuKernel,
21
+ IGpuPlacement,
22
+ IGpuSceneBuffers,
23
+ IKernelInput,
24
+ IKernelResult,
25
+ IRegion,
26
+ } from "./world-gpu-types.js";
27
+ import { PlacementStruct, nodes } from "./world-gpu-types.js";
28
+ import { DRAW_ARGS_WORDS, LIVE_MATRIX, LOCAL_WORDS, compose } from "./world-gpu-validation.js";
29
+
30
+ /**
31
+ * The per-instance cull and LOD selection, in plain TypeScript: the reference the TSL kernel mirrors
32
+ * branch for branch, and the answer the CPU path is judged against.
33
+ *
34
+ * It runs in node with no GPU behind it, which is why it is what the tests prove. Nothing here
35
+ * allocates a buffer or reads a device: given the placements, the camera's planes and an asset's
36
+ * gate table, it returns the compacted survivors and the per-key counts one dispatch would produce.
37
+ */
38
+
39
+ /**
40
+ * The level one placement draws with, from an asset's gate table and the placement's own scale.
41
+ *
42
+ * Every gate but a whole-asset impostor's terminal is an authored world-metre distance, compared
43
+ * directly. The impostor's terminal gate is the base-sphere *projected* distance: the atlas is
44
+ * built for the asset's own LOD0 size, so a placement scaled ten times reaches the atlas ten times
45
+ * as far — its threshold is `base * |scale|`, floored by the last source gate it must stay strictly
46
+ * beyond. The floor is nudged one representable step past that gate: sharing the gate's own switch
47
+ * distance would let the terminal overwrite the last source level at every distance past it, so the
48
+ * source level would never draw. Read by {@link cullAndSelect} and mirrored by the kernel and the
49
+ * CPU path, so all three cross the same switch.
50
+ */
51
+ export function levelAtGates(
52
+ slot: Pick<IAssetSlot, "distances" | "impostor">,
53
+ distance: number,
54
+ scale: number,
55
+ ): number {
56
+ const last = slot.distances.length - 1;
57
+ const magnitude = Number.isFinite(scale) ? Math.abs(scale) : 1;
58
+ let level = 0;
59
+ for (let index = 1; index < slot.distances.length; index += 1) {
60
+ const gate = slot.distances[index] as number;
61
+ const threshold =
62
+ slot.impostor === true && index === last && last >= 1
63
+ ? Math.max(strictlyAfterGate(slot.distances[last - 1] as number), gate * magnitude)
64
+ : gate;
65
+ if (distance > threshold) level = index;
66
+ }
67
+ return level;
68
+ }
69
+
70
+ /**
71
+ * The last level at or below `level` that the scene can actually draw, which is where a placement
72
+ * goes when the gates name one the prewarm has not minted keys for.
73
+ *
74
+ * `WorldCells#gatesOf` names every level of an asset from the moment it is adopted and fills in the
75
+ * keys minted so far, so a chain that has widened holds `parts: 2,0,0,0` while the loading screen is
76
+ * up. The CPU path draws `asset.levels[level]` whatever the gates name and always has a shape there;
77
+ * a dispatch that took the named level would loop its zero keys and draw the placement nowhere, and
78
+ * with the bias raised the placements past the last source gate are exactly the far ones — a forest
79
+ * 80-300 m out standing in its own shadows, while the shadow halves, which take no bias and key
80
+ * themselves, still draw. One level down is the finest shape the scene holds, which is the level the
81
+ * prewarm is one frame from minting.
82
+ */
83
+ function drawableLevel(slot: Pick<IAssetSlot, "levels">, level: number): number {
84
+ for (let at = level; at > 0; at -= 1) if ((slot.levels[at]?.parts ?? 0) > 0) return at;
85
+ return 0;
86
+ }
87
+
88
+ /**
89
+ * The level a shadow map draws a placement at, or -1 when no level of its asset casts. A placement
90
+ * whose main level casts nothing falls back only when its asset permits it: derived chains past
91
+ * `castLevels` keep their shadow, drawn in the last shape that has a twin, rather than
92
+ * leaving a hole in the map (PRD-541). The level is then floored at the map's base and clamped to
93
+ * the last level that casts, so a coarse map draws the coarsest shape that has a twin. `base` past
94
+ * the chain is clamped by the chain length first.
95
+ */
96
+ function shadowLevel(
97
+ slot: Pick<IAssetSlot, "levels" | "shadowFallback">,
98
+ regions: readonly IRegion[],
99
+ drawn: number,
100
+ base: number,
101
+ ): number {
102
+ const casts = (at: number): boolean => {
103
+ const gate = slot.levels[at];
104
+ return gate !== undefined && gate.parts > 0 && regions[gate.firstKey]?.uncast !== true;
105
+ };
106
+ if (slot.shadowFallback === false && casts(drawn) === false) return -1;
107
+ // At or below `drawn` any casting level qualifies, above it only up to the map's base, so the
108
+ // last casting level in `[0, max(drawn, base)]` is both rules at once.
109
+ const last = Math.max(drawn, Math.min(base, slot.levels.length - 1));
110
+ let level = -1;
111
+ for (let at = 0; at <= last; at += 1) if (casts(at)) level = at;
112
+ return level;
113
+ }
114
+
115
+ /**
116
+ * One representable Float32 step past a gate: `g * (1 + 2^-22)`, two f32 ULPs at `g`'s exponent.
117
+ *
118
+ * A floored terminal gate must start strictly after the source gate it is floored by and must stay
119
+ * so once the threshold is stored and compared in f32, which a bare `g` does not: the terminal
120
+ * shares `g`'s switch distance and the later gate wins every comparison, starving the source level.
121
+ * A relative step, not a fixed metre margin, so the ordering holds at every authored scale.
122
+ */
123
+ /** One representable step past a gate, which the kernel and the reference both floor an impostor with. */
124
+ export const GATE_STEP = 2 ** -22;
125
+
126
+ function strictlyAfterGate(gate: number): number {
127
+ return gate + Math.abs(gate) * GATE_STEP;
128
+ }
129
+
130
+ /**
131
+ * One shadow map's own three numbers, which is the whole of what a level render knows that the main
132
+ * camera does not.
133
+ *
134
+ * They are the level's, never the camera's: a map's frustum is the light's window, its gate is the
135
+ * texel size it can resolve, and its base is the chain level the cluster path hands it — `#probe`
136
+ * swaps a coarse level's geometry for the coarsest shape, so a coarse map draws that shape whatever a
137
+ * placement's own distance would have selected. The distance itself is the main pass's, from the
138
+ * eye: a placement's shape and its cast come from the key the main pass draws it in.
139
+ */
140
+ export interface IShadowLevel {
141
+ /** The six frustum planes of this map's own shadow camera. */
142
+ readonly planes: Float32Array;
143
+ /** This map's texel gate in world metres: a placement narrower than it casts nothing here. */
144
+ readonly gate: number;
145
+ /**
146
+ * The chain level this map draws at, floored over the placement's own. 0 is the placement's own
147
+ * LOD by distance — what the finest map draws — and the coarsest index is what every level past
148
+ * the first draws. A base whose keys are not minted draws nothing, which is why a caller settling
149
+ * the prewarm first is the contract rather than a fallback.
150
+ *
151
+ * {@link COARSEST_SHADOW_LEVEL} is past every chain, and means the coarsest shape an asset has: a
152
+ * map that coarsens its casters does not know how long each asset's chain is, and the floor is
153
+ * clamped per asset, so one number asks every chain for its own coarsest level.
154
+ */
155
+ readonly base: number;
156
+ }
157
+
158
+ /**
159
+ * A {@link IShadowLevel.base} past every chain: the map draws every asset's coarsest shape, whatever
160
+ * distance selected it. Clamped to each asset's own last level, so an owner with no level count to
161
+ * hand — `VirtualShadowNode`, which coarsens a coarse level's casters without knowing an asset —
162
+ * can still ask.
163
+ */
164
+ export const COARSEST_SHADOW_LEVEL = 1 << 20;
165
+
166
+ /**
167
+ * The per-instance kernel, in plain TypeScript. The TSL kernel in {@link WorldGpuScene} is this
168
+ * loop with the same branches, and the test proves this one against the CPU path.
169
+ *
170
+ * One placement, in the order the source buffer holds them: a released record and a record whose
171
+ * asset is unknown are skipped, the bounding sphere is tested against the camera's six planes, the
172
+ * XZ distance picks the level through the asset's own gates and culls a record beyond its cull
173
+ * distance, and each part of that level takes the next free slot in its key's region and writes
174
+ * `placement * part offset` there. A region that is full is a dropped instance, never a write past
175
+ * the end of the buffer.
176
+ */
177
+ export function cullAndSelect(input: IKernelInput): IKernelResult {
178
+ return select(input, undefined);
179
+ }
180
+
181
+ /**
182
+ * The same kernel with a shadow map's own four numbers in place of the camera's, and nothing else
183
+ * changed: same regions, same keys, same `placement * part offset`, same capacity guard.
184
+ *
185
+ * The gate is applied to the placement's own diameter, where the cluster path applies it to the
186
+ * whole mesh and drops the square with it — so on a uniform-size fixture the two sets are the same
187
+ * set, and where a square mixes sizes this one is the finer of the two.
188
+ */
189
+ export function cullAndSelectShadow(input: IKernelInput, level: IShadowLevel): IKernelResult {
190
+ return select(input, level);
191
+ }
192
+
193
+ /**
194
+ * The one loop both references share. `shadow` is what makes the second one a variant rather than a
195
+ * fork: the main camera's planes, eye, no gate and no base are the degenerate case, so the two can
196
+ * never disagree by having been edited apart.
197
+ */
198
+ function select(input: IKernelInput, shadow: IShadowLevel | undefined): IKernelResult {
199
+ const { placements, camera, regions, slots } = input;
200
+ // A shadow map has no main camera to reproject into, so the test is the main pass's alone — a
201
+ // caster the eye cannot see still casts.
202
+ const occlusion = shadow === undefined ? input.occlusion : undefined;
203
+ const planes = shadow?.planes ?? camera.planes;
204
+ const metres = shadow?.gate ?? 0;
205
+ const base = shadow?.base ?? 0;
206
+ const counts = new Uint32Array(input.regionCount);
207
+ const args = new Uint32Array(input.regionCount * DRAW_ARGS_WORDS);
208
+ // The drawn buffer is the regions' own, so the reference allocates exactly what the GPU holds.
209
+ const capacity = regions.reduce(
210
+ (sum, region) => Math.max(sum, region.start + region.capacity),
211
+ 0,
212
+ );
213
+ const matrix = new Float32Array(capacity * LOCAL_WORDS);
214
+ for (const region of regions) {
215
+ args[region.argsIndex * DRAW_ARGS_WORDS + 4] = region.start;
216
+ }
217
+ let occludedInstances = 0;
218
+ let occludedTriangles = 0;
219
+ for (let index = 0; index < input.count; index += 1) {
220
+ const placement = placements[index];
221
+ if (placement === undefined || placement.slot < 0) continue;
222
+ const slot = slots[placement.slot];
223
+ if (slot === undefined) continue;
224
+ const at = placement.centre;
225
+ const radius = at[3] as number;
226
+ let visible = true;
227
+ for (let plane = 0; plane < 6; plane += 1) {
228
+ const offset = plane * 4;
229
+ const signed =
230
+ (planes[offset] as number) * (at[0] as number) +
231
+ (planes[offset + 1] as number) * (at[1] as number) +
232
+ (planes[offset + 2] as number) * (at[2] as number) +
233
+ (planes[offset + 3] as number);
234
+ if (signed < -radius) {
235
+ visible = false;
236
+ break;
237
+ }
238
+ }
239
+ if (visible === false) continue;
240
+ // Sub-texel, exactly as `#probe` decides it for a mesh: a caster this map cannot resolve casts
241
+ // no shadow a fragment could tell from ground cover.
242
+ if (radius * 2 < metres) continue;
243
+ const distance = Math.hypot((at[0] as number) - camera.x, (at[2] as number) - camera.z);
244
+ if (slot.cull !== undefined && distance > slot.cull) continue;
245
+ // Cull above is the authored distance; the level below is the biased one for the main pass — the
246
+ // same multiplier the kernel's uniform carries, so the reference and the dispatch cross a switch
247
+ // together. A shadow map takes the main pass's own level, from the eye: that is the key a
248
+ // placement is drawn in, and the cluster path casts each key's placements from that key's mesh.
249
+ const drawn = drawableLevel(
250
+ slot,
251
+ levelAtGates(slot, biasedLodDistance(distance), placement.scale ?? 1),
252
+ );
253
+ const level = shadow === undefined ? drawn : shadowLevel(slot, regions, drawn, base);
254
+ if (level < 0) continue;
255
+ const gate = slot.levels[level];
256
+ if (gate === undefined) continue;
257
+ const hidden =
258
+ occlusion !== undefined && occludedBy(occlusion, at, radius) ? occlusion : undefined;
259
+ for (let part = 0; part < gate.parts; part += 1) {
260
+ const region = regions[gate.firstKey + part];
261
+ if (region === undefined) continue;
262
+ // Counted either way: a measured run draws what it hides, so the count is the only place the
263
+ // answer can live.
264
+ if (hidden !== undefined) {
265
+ occludedInstances += 1;
266
+ occludedTriangles += region.indexCount / 3;
267
+ if (hidden.cull) continue;
268
+ }
269
+ const taken = counts[gate.firstKey + part] as number;
270
+ if (taken >= region.capacity) continue;
271
+ counts[gate.firstKey + part] = taken + 1;
272
+ args[region.argsIndex * DRAW_ARGS_WORDS + 1] = taken + 1;
273
+ compose(placement.matrix, region.local, matrix, (region.start + taken) * LOCAL_WORDS);
274
+ }
275
+ }
276
+ return {
277
+ args,
278
+ counts,
279
+ drawn: matrix,
280
+ ...(occlusion === undefined
281
+ ? {}
282
+ : { occluded: { instances: occludedInstances, triangles: occludedTriangles } }),
283
+ };
284
+ }
285
+
286
+ /**
287
+ * One asset's gates as its owner last published them: the source representation and its
288
+ * `asset.distances`/`cullDistance(definition.maxDistance)` snapshot at the completed swap boundary.
289
+ *
290
+ * Deliberately not an {@link IAssetSlot}. A slot is what this class wrote into its own table, and a
291
+ * table written before the owner's model widened its chain is the exact thing the check exists to
292
+ * catch — feeding it back in as the reference is the check agreeing with itself.
293
+ */
294
+ export interface ILiveAsset {
295
+ /** The asset id a main key is named `asset:level:part` with, which is the owner's own convention. */
296
+ readonly id: string;
297
+ /** Level switch distances, ascending, `0` first — the CPU publication snapshot. */
298
+ readonly distances: readonly number[];
299
+ /** `maxDistance` less its eighth, or `undefined`. */
300
+ readonly cull: number | undefined;
301
+ /** Index-aligned with `distances`; each level's parts, each part's own offset inside the model. */
302
+ readonly locals: readonly (readonly Float32Array[])[];
303
+ /** Whether the last level is a whole-asset impostor whose gate the placement's scale scales. */
304
+ readonly impostor?: boolean;
305
+ }
306
+
307
+ /**
308
+ * Every placement's own answer, from the owner's live gates, as the instances each main key must be
309
+ * holding: the same six-plane sphere test, the same `cull`, the same ascending `distance > gate`
310
+ * level test and the same `placement * part offset` composition {@link cullAndSelect} runs — over
311
+ * gates this file did not write.
312
+ *
313
+ * This is the one reference in the module that is not a mirror of the kernel's inputs. `cullAndSelect`
314
+ * reads the gate table out of the same class the kernel's buffer is written from, so a table holding
315
+ * the wrong distances makes both agree; here the caller passes the owner's own `distances`, so a
316
+ * table that was written before the chain widened, or before the last `maxDistance`, answers
317
+ * differently from the picture the CPU path draws.
318
+ */
319
+ export function liveKeyInstances(
320
+ placements: readonly IGpuPlacement[],
321
+ asset: (slot: number) => ILiveAsset | undefined,
322
+ camera: {
323
+ readonly planes: Float32Array;
324
+ readonly x: number;
325
+ readonly y: number;
326
+ readonly z: number;
327
+ },
328
+ ): Map<string, Float32Array> {
329
+ const words = new Map<string, number[]>();
330
+ for (const placement of placements) {
331
+ if (placement.slot < 0) continue;
332
+ const held = asset(placement.slot);
333
+ if (held === undefined) continue;
334
+ const at = placement.centre;
335
+ const radius = at[3] as number;
336
+ let visible = true;
337
+ for (let plane = 0; plane < 6; plane += 1) {
338
+ const offset = plane * 4;
339
+ const signed =
340
+ (camera.planes[offset] as number) * (at[0] as number) +
341
+ (camera.planes[offset + 1] as number) * (at[1] as number) +
342
+ (camera.planes[offset + 2] as number) * (at[2] as number) +
343
+ (camera.planes[offset + 3] as number);
344
+ if (signed < -radius) {
345
+ visible = false;
346
+ break;
347
+ }
348
+ }
349
+ if (visible === false) continue;
350
+ const distance = Math.hypot((at[0] as number) - camera.x, (at[2] as number) - camera.z);
351
+ if (held.cull !== undefined && distance > held.cull) continue;
352
+ // The dispatch's own bias and the same gate rule: this reference is what the dressed mesh's
353
+ // instances are checked against, so it must cross the impostor switch exactly as the kernel does.
354
+ const level = levelAtGates(held, biasedLodDistance(distance), placement.scale ?? 1);
355
+ const locals = held.locals[level];
356
+ if (locals === undefined) continue;
357
+ for (const [part, local] of locals.entries()) {
358
+ const key = `${held.id}:${String(level)}:${String(part)}`;
359
+ let run = words.get(key);
360
+ if (run === undefined) {
361
+ run = [];
362
+ words.set(key, run);
363
+ }
364
+ compose(placement.matrix, local, LIVE_MATRIX, 0);
365
+ for (const word of LIVE_MATRIX) run.push(word);
366
+ }
367
+ }
368
+ return new Map([...words].map(([key, run]) => [key, Float32Array.from(run)]));
369
+ }
370
+
371
+ /** One completed manual frame check, identified by the caller's frame and this scene's dispatch. */
372
+
373
+ /**
374
+ * What a built cull pass reads: the scene's buffers, the camera uniforms the dispatch wrote, and —
375
+ * only when a launch asked to measure — the pyramid it reprojects into.
376
+ *
377
+ * The measurement is a binding rather than a mode string: `view()` is the uniform the kernel was
378
+ * given last time, made on first use by the caller that owns the matrix, so a scene whose GPU pass
379
+ * never measures asks the backend for no extra uniform.
380
+ */
381
+ export interface ICullKernelInput {
382
+ readonly buffers: IGpuSceneBuffers;
383
+ /** The six frustum planes, as uniforms the dispatch wrote this frame. */
384
+ readonly planes: readonly unknown[];
385
+ /** `(placements, slots, keys, keys)`, written by the dispatch before it submits. */
386
+ readonly counts: unknown;
387
+ /** The eye the placement distance is measured from. */
388
+ readonly eye: unknown;
389
+ /** The adaptive LOD bias the gate compare is scaled by. */
390
+ readonly bias: unknown;
391
+ readonly occlusion?: {
392
+ readonly pyramid: DepthPyramid;
393
+ readonly cut: unknown;
394
+ view(): unknown;
395
+ };
396
+ }
397
+
398
+ /**
399
+ * The two dispatches, mirroring {@link cullAndSelect} branch for branch: one thread per key
400
+ * zeroes that key's instance count, one thread per resident placement appends its matrix to each
401
+ * of its level's parts.
402
+ */
403
+ export function buildCullKernel(input: ICullKernelInput): IGpuKernel {
404
+ const { buffers } = input;
405
+ const source = nodes(storage(buffers.source, PlacementStruct, buffers.source.count));
406
+ const drawn = nodes(storage(buffers.drawn, "mat4", buffers.drawn.count));
407
+ const argsPlain = nodes(storage(buffers.args, "uint", buffers.args.count));
408
+ const argsAtomic = nodes(storage(buffers.args, "uint", buffers.args.count).toAtomic());
409
+ const keys = nodes(storage(buffers.keys, "vec4", buffers.keys.count));
410
+ const locals = nodes(storage(buffers.locals, "mat4", buffers.locals.count));
411
+ const gates = nodes(storage(buffers.gates, "vec4", buffers.gates.count));
412
+ const levels = nodes(storage(buffers.levels, "vec4", buffers.levels.count));
413
+ const counts = nodes(input.counts);
414
+ const eye = nodes(input.eye);
415
+ const bias = nodes(input.bias);
416
+ const planes = input.planes.map((plane) => nodes(plane));
417
+ // Measuring doubles the clear: the second thread per key zeroes that key's word of the
418
+ // measured-occlusion tally, which is why the args buffer is sized for it (see `argsWords`).
419
+ // A run that is not measuring never pays the second thread.
420
+ const clearWidth = input.occlusion === undefined ? 1 : 2;
421
+ const clear = Fn(() => {
422
+ If(instanceIndex.greaterThanEqual(counts.w.mul(clearWidth)), () => Return());
423
+ If(instanceIndex.lessThan(counts.w), () => {
424
+ const key = keys.element(instanceIndex);
425
+ argsPlain.element(key.z.mul(DRAW_ARGS_WORDS).add(1)).assign(int(0));
426
+ });
427
+ If(instanceIndex.greaterThanEqual(counts.w), () => {
428
+ argsPlain
429
+ .element(
430
+ nodes(counts.w.mul(DRAW_ARGS_WORDS)).add(
431
+ nodes(float(instanceIndex).sub(counts.w).floor()),
432
+ ),
433
+ )
434
+ .assign(int(0));
435
+ });
436
+ })().compute(Math.max(1, buffers.keys.count * clearWidth));
437
+ const cull = Fn(() => {
438
+ If(instanceIndex.greaterThanEqual(counts.x), () => Return());
439
+ const placement = source.element(instanceIndex);
440
+ const centre = placement.get("centre");
441
+ const matrix = placement.get("matrix");
442
+ const slot = placement.get("info").x;
443
+ If(slot.lessThan(0.0), () => Return());
444
+ If(slot.greaterThanEqual(counts.y), () => Return());
445
+ const radius = centre.w;
446
+ for (const plane of planes) If(plane.dot(centre.xyz).lessThan(radius.negate()), () => Return());
447
+ const gate = gates.element(slot);
448
+ const distance = length(vec3(centre.x.sub(eye.x), 0.0, centre.z.sub(eye.z)));
449
+ If(gate.w.mod(2.0).greaterThan(0.5).and(distance.greaterThan(gate.z)), () => Return());
450
+ // Cull above is the authored distance; the level below is the same distance scaled by the
451
+ // adaptive bias, mirroring `cullAndSelect` and the CPU `model-lod` path.
452
+ const lodDistance = nodes(distance).mul(bias as never);
453
+ // The level, by the same ascending test the CPU runs: the last gate the placement is past.
454
+ // The loop is bounded by `gate.y` rather than unrolled, because a baked chain can carry more
455
+ // levels than any fixed count, and a level the loop stopped short of is a placement drawn at
456
+ // the wrong shape by however many levels it missed.
457
+ const level = int(0).toVar();
458
+ // The placement's own uniform scale, written into `info.y`; the whole-asset impostor's terminal
459
+ // gate is the base projected distance and is scaled by it. A mirrored placement's scale is
460
+ // negative, and the extent it reaches is the same, so the kernel takes the magnitude exactly as
461
+ // `levelAtGates` does; `info.y` is already finite-sanitised when the record is written.
462
+ const scale = abs(placement.get("info").y);
463
+ Loop({ start: int(1), end: gate.y, type: "int", condition: "<" }, ({ i }: { i: unknown }) => {
464
+ const candidate = levels.element(gate.x.add(i as never));
465
+ const threshold = nodes(candidate.x).toVar();
466
+ // Only the terminal level carries this mark: its stored distance is the base-sphere projected
467
+ // one, so its real threshold is `max(strictly after last source gate, base * |scale|)`. The
468
+ // source floor is the previous level's own authored gate, unscaled and nudged one f32 step,
469
+ // so a small scale cannot starve the last source level by sharing its switch distance.
470
+ If(candidate.w.greaterThan(0.5), () => {
471
+ const previous = levels.element(gate.x.add(i as never).sub(1)).x;
472
+ const floor = previous.add(abs(previous).mul(GATE_STEP));
473
+ threshold.assign(max(floor, candidate.x.mul(scale)));
474
+ });
475
+ // A level the prewarm has minted no key for is not taken: the gate table names every level of
476
+ // an asset from the moment it is adopted, and the draw loop below would run this level's
477
+ // zero keys, so the placement would be selected and drawn nowhere while the CPU path drew it
478
+ // and its shadow halves drew under it. The last level that has keys keeps it. See
479
+ // `drawableLevel`, which the reference mirrors.
480
+ If(lodDistance.greaterThan(threshold), () => {
481
+ If(candidate.z.greaterThan(0.5), () => {
482
+ level.assign(i as never);
483
+ });
484
+ });
485
+ });
486
+ const at = levels.element(gate.x.add(level));
487
+ // The pyramid test, once per placement: a placement the frustum and the gates kept, reprojected
488
+ // into the previous frame's pyramid. Measured only, so the write below happens either way and
489
+ // the indirect counts are develop's.
490
+ const hidden = float(0).toVar();
491
+ const measure = input.occlusion;
492
+ if (measure !== undefined && measure.pyramid.levels > 0) {
493
+ hidden.assign(measure.pyramid.occluded(centre.xyz, radius, measure.view(), measure.cut));
494
+ }
495
+ Loop({ start: int(0), end: at.z, type: "int", condition: "<" }, ({ i }: { i: unknown }) => {
496
+ const keyIndex = at.y.add(i as never);
497
+ const key = keys.element(keyIndex);
498
+ If(hidden.greaterThan(0.5), () => {
499
+ atomicAdd(argsAtomic.element(counts.w.mul(DRAW_ARGS_WORDS).add(keyIndex)), int(1));
500
+ });
501
+ const taken = nodes(atomicAdd(argsAtomic.element(key.z.mul(DRAW_ARGS_WORDS).add(1)), int(1)));
502
+ If(taken.toFloat().lessThan(key.y), () => {
503
+ drawn.element(key.x.add(taken)).assign(matrix.mul(locals.element(keyIndex)));
504
+ });
505
+ });
506
+ })().compute(Math.max(1, buffers.source.count));
507
+ clear.setName("worldGpuSceneClear");
508
+ cull.setName("worldGpuSceneCull");
509
+ return { clear, cull };
510
+ }