@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
package/dist/world.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { Object3D, Mesh, LOD, Vector3, Camera, Material, Group, BufferGeometry } from 'three';
2
- import { I as IComputeDriven, a as ILodView, b as IModelLodPolicy, c as IGPUReadbackSample } from './model-lod-CTpZ6imz.js';
3
- import { I as IRendererLike } from './renderer-rZm0hVqq.js';
1
+ import { Group, Vector3, BufferGeometry, Mesh, Object3D, LOD, Camera, Texture, Material, Data3DTexture, Box3 } from 'three';
2
+ import { I as IComputeDriven, a as IGPUReadbackSample, b as ILodView, c as IModelLodPolicy } from './model-lod-B6BMqS1r.js';
3
+ import { I as IRendererLike } from './renderer-DvFVoAgj.js';
4
4
  import { I as IAssetLoader } from './assets-YUbXa3-Y.js';
5
5
  import { Node } from 'three/webgpu';
6
6
 
@@ -14,7 +14,402 @@ interface IWorldErosionOptions {
14
14
  readonly timeStep: number;
15
15
  }
16
16
 
17
+ /**
18
+ * `Heightfield`: one height buffer shared by world queries, rendered geometry, and a physics
19
+ * heightfield. Split out of `world.ts` so `world-tiles.ts` reads the field it streams without
20
+ * importing the module that re-exports the tiles (PRD-797); `world.ts` re-exports all of it, so
21
+ * `@threenative/core/world` keeps its surface.
22
+ */
23
+
24
+ interface IHeightfieldOrigin {
25
+ readonly x: number;
26
+ readonly z: number;
27
+ }
28
+ interface IHeightfieldOptions {
29
+ readonly columns: number;
30
+ readonly depth: number;
31
+ readonly heights: Float32Array;
32
+ readonly origin: IHeightfieldOrigin;
33
+ readonly rows: number;
34
+ readonly width: number;
35
+ readonly worldPasses?: IHeightfieldWorldPassOptions;
36
+ }
37
+ /** A rectangular window of a heightfield's canonical samples, in grid indices. */
38
+ /** Hands out the union of every window `updateHeights` wrote since the last `take`. */
39
+ interface IHeightfieldChangeTracker {
40
+ /** The changed window since the previous take, or undefined when nothing changed. */
41
+ take(): IHeightfieldRegionBounds | undefined;
42
+ /** Stop tracking. Idempotent. */
43
+ dispose(): void;
44
+ }
45
+ interface IHeightfieldRegionBounds {
46
+ /** First column (x index), inclusive. */
47
+ readonly column: number;
48
+ /** Number of columns covered. */
49
+ readonly columns: number;
50
+ /** First row (z index), inclusive. */
51
+ readonly row: number;
52
+ /** Number of rows covered. */
53
+ readonly rows: number;
54
+ }
55
+ /** A rectangular window plus the replacement samples written over it. */
56
+ interface IHeightfieldRegion extends IHeightfieldRegionBounds {
57
+ /** Row-major samples, `columns * rows` long and read with the region's own stride. */
58
+ readonly heights: Float32Array;
59
+ }
60
+ interface IHeightfieldWorldPassOptions {
61
+ /** Maximum TSL compute dispatches submitted by one rendered frame. */
62
+ readonly dispatchBudget: number;
63
+ /** Reserved GPU path; true is rejected until GPU readback owns the canonical field. */
64
+ readonly gpu?: boolean;
65
+ /** Every physical coefficient is game supplied; core owns no terrain preset. */
66
+ readonly erosion: IWorldErosionOptions;
67
+ }
68
+ interface IHeightfieldSamplerOptions extends Omit<IHeightfieldOptions, "heights"> {
69
+ /** Game-owned terrain function. It is evaluated once and never retained. */
70
+ readonly sampleHeight: (x: number, z: number) => number;
71
+ }
72
+ interface IStoredHeightfieldChannels {
73
+ readonly flow?: Float32Array;
74
+ readonly moisture?: Float32Array;
75
+ }
76
+ /**
77
+ * One height buffer shared by world queries, rendered geometry, and a physics heightfield.
78
+ *
79
+ * The game supplies every value, so changing the terrain's shape never requires a package edit.
80
+ * `fromSampler` evaluates that game function exactly once at each vertex and retains only the
81
+ * resulting numbers. Queries interpolate those same numbers instead of evaluating the function
82
+ * again.
83
+ *
84
+ * @situation build terrain geometry and collision from one game-authored height function
85
+ * @situation generate a terrain a player can walk across
86
+ * @situation query the same ground height or normal that a player sees and collides with
87
+ * @situation ask how high the ground is here
88
+ * @situation build islands and coastlines from terrain
89
+ * @situation keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)
90
+ * @constraint sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output
91
+ * @constraint rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
92
+ * @override rows, columns, width, depth, origin, and sampleHeight are explicit on every field
93
+ * @example const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
94
+ */
95
+ declare class Heightfield extends Group implements IComputeDriven {
96
+ #private;
97
+ readonly columns: number;
98
+ readonly depth: number;
99
+ readonly origin: IHeightfieldOrigin;
100
+ readonly rows: number;
101
+ readonly width: number;
102
+ readonly processCadence: "render";
103
+ readonly warmupNodes: readonly unknown[];
104
+ constructor(options: IHeightfieldOptions & IStoredHeightfieldChannels);
105
+ static fromSampler(options: IHeightfieldSamplerOptions): Heightfield;
106
+ sample(channel: string, x: number, z: number): number;
107
+ get released(): boolean;
108
+ get generationComplete(): boolean;
109
+ get gpuHeightSample(): IGPUReadbackSample | undefined;
110
+ attachRenderer(renderer: IRendererLike): void;
111
+ process(renderer?: IRendererLike | undefined): void;
112
+ debug(): Record<string, unknown>;
113
+ detach(): void;
114
+ /** A copy of the canonical row-major samples, safe for game-side analysis. */
115
+ get heights(): Float32Array;
116
+ /** A copy of the normalized routed-flow channel, when world passes were requested. */
117
+ get flow(): Float32Array | undefined;
118
+ /** Bytes retained by this field's CPU channels and its conservative GPU allowance. */
119
+ get memoryBytes(): number;
120
+ heightAt(x: number, z: number): number;
121
+ /**
122
+ * The drawn surface's height under `(x, z)`: the triangle plane `toGeometry` emits, not the
123
+ * bilinear `heightAt`.
124
+ *
125
+ * A heightfield renders as two triangles per cell and collides as the same two, so a prop or a
126
+ * player grounded on the bilinear height stands up to half a cell's relief off the surface the
127
+ * eye sees — worst on a saddle, where the two disagree by the cell's whole diagonal. This answers
128
+ * the plane the drawn triangle actually is, from the canonical samples, so a caller needs neither
129
+ * the geometry nor a matrix to ask.
130
+ * @situation ground a prop or a player on the same triangle the eye sees and the collider uses
131
+ * @constraint the point must be inside the field; a query outside it throws like `heightAt`
132
+ * @example const resting = field.surfaceAt(player.position.x, player.position.z);
133
+ */
134
+ surfaceAt(x: number, z: number): number;
135
+ normalAt(x: number, z: number, target?: Vector3): Vector3;
136
+ /**
137
+ * Monotonic sample version, incremented by every `updateHeights` call.
138
+ *
139
+ * A renderer or collider that caches derived data compares this against its own last-seen value
140
+ * instead of diffing the whole grid each frame.
141
+ */
142
+ get version(): number;
143
+ /**
144
+ * Overwrite one rectangular window of the canonical samples.
145
+ *
146
+ * Height is the one buffer queries, rendered geometry and collider export share, so a second
147
+ * terrain representation is never needed: a simulation writes its surface here and every
148
+ * consumer already reads it. The whole window is validated before any sample changes, so a
149
+ * malformed call leaves the field untouched rather than half-written.
150
+ * @situation deform terrain, snow or water in place and have queries and collision follow
151
+ * @constraint the region must lie inside the field; an out-of-bounds window throws and writes nothing
152
+ * @constraint heights is `columns * rows` long, row-major, and every sample must be finite
153
+ */
154
+ updateHeights(region: IHeightfieldRegion): void;
155
+ /**
156
+ * Follow which samples change, independently of every other follower.
157
+ *
158
+ * A consumer that mirrors the surface — a collider, a GPU copy, a cache — needs the window that
159
+ * changed since *it* last looked; comparing the whole field instead costs every sample on every
160
+ * change. Each tracker keeps its own union of the windows `updateHeights` wrote, so two
161
+ * consumers never take each other's changes.
162
+ *
163
+ * ```ts
164
+ * const changes = field.trackChanges();
165
+ * const changed = changes.take(); // undefined when nothing was written
166
+ * ```
167
+ */
168
+ trackChanges(): IHeightfieldChangeTracker;
169
+ /** The collider sample at `row`, `column`: what `toColliderHeights()` holds there, without a copy. */
170
+ colliderHeight(row: number, column: number): number;
171
+ /**
172
+ * Rewrite an existing `toGeometry()` result from the current canonical samples.
173
+ *
174
+ * Positions carry over unchanged because only the surface moves; y and normals are refreshed
175
+ * from the same sampler queries use, which is what keeps a rendered vertex and a height query
176
+ * from disagreeing. Pass a region to touch only the window a simulation just changed.
177
+ * @situation redraw a terrain, snow or water mesh after its samples changed
178
+ * @constraint geometry must come from `toGeometry()` with the same rows and columns
179
+ */
180
+ refreshGeometry(geometry: BufferGeometry, bounds?: IHeightfieldRegionBounds): void;
181
+ /** The same values transposed once into Rapier's column-major height-matrix order. */
182
+ toColliderHeights(): Float32Array;
183
+ /** Builds an ordinary Three.js geometry without choosing its surface. */
184
+ toGeometry(): BufferGeometry;
185
+ }
186
+
187
+ /**
188
+ * `HeightfieldCollar`: the far ring a heightfield grows past its playable square, and the band of it
189
+ * a collider follows.
190
+ *
191
+ * A landscape renders its square at full detail and its surroundings at a fraction of it, because
192
+ * the surroundings' triangles are (Unreal `ALandscapeMeshProxyActor`, HLOD). The mechanism is the
193
+ * same everywhere: one vertex per boundary sample, one ring per distance step, and a quad grid
194
+ * between them whose innermost ring is the square's own edge. What a ring is worth in metres, what
195
+ * it looks like and where the ground stops being walkable are the game's decisions, so they arrive
196
+ * as options: `ringDistance` is its framing curve and `height` is its own surface.
197
+ */
198
+
199
+ /** One ring vertex: where it stands and which ring and boundary sample it belongs to. */
200
+ interface IHeightfieldCollarSite {
201
+ /** Metres past the square's edge along the framing curve. */
202
+ readonly distance: number;
203
+ /** Ring number, 0 at the square's own edge. */
204
+ readonly ring: number;
205
+ /** Index along the perimeter walk, 0 at the ring's own (-x, -z) corner. */
206
+ readonly vertex: number;
207
+ readonly x: number;
208
+ readonly z: number;
209
+ }
210
+ /** The collar quad a world point falls in, in ring and perimeter indices. */
211
+ interface IHeightfieldCollarQuad {
212
+ /** Share from `from` to `to` along the perimeter, 0..1. */
213
+ readonly edgeShare: number;
214
+ /** Perimeter index at or before the point. */
215
+ readonly from: number;
216
+ /** The ring inside the point. */
217
+ readonly lower: number;
218
+ /** Share from `lower` to `upper` across the rings, 0..1. */
219
+ readonly ringShare: number;
220
+ /** Perimeter index after `from`. */
221
+ readonly to: number;
222
+ /** The ring outside the point. */
223
+ readonly upper: number;
224
+ }
225
+ interface IHeightfieldCollarOptions {
226
+ /** The height at one ring vertex. The game's look: surveyed relief, its smoothing and its seams. */
227
+ readonly height: (site: IHeightfieldCollarSite) => number;
228
+ /** Samples along one side of the square; a ring keeps one vertex per boundary sample. */
229
+ readonly resolution: number;
230
+ /** Metres past the square's edge of one ring. `ringDistance(0)` reads 0 and it never decreases. */
231
+ readonly ringDistance: (ring: number) => number;
232
+ /** Rings past the edge, outermost included. */
233
+ readonly rings: number;
234
+ /** The square's side in metres: the heightfield's own width. */
235
+ readonly size: number;
236
+ /** Metres past the edge that stay walkable: `walk` ends at the outermost ring inside it. */
237
+ readonly walkBand: number;
238
+ }
239
+ /** The walkable band of the collar, as the drawn triangles themselves. */
240
+ interface IHeightfieldCollarWalk {
241
+ /** Metres past the edge where the band ends. */
242
+ readonly extent: number;
243
+ /** A view of the collar's own position buffer and index slice, not a resample. */
244
+ readonly geometry: BufferGeometry;
245
+ }
246
+ /**
247
+ * A heightfield's far ring: `rings` square rings past its playable square, one vertex per boundary
248
+ * sample, and the index grid that draws them.
249
+ * @situation draw the terrain past the playable square without hand-building a ring grid
250
+ * @situation ground a character past the square, out to the walk band, on drawn triangles
251
+ * @constraint every ring vertex asks the game's `height` callback; core owns no terrain look
252
+ * @constraint the collar is a ring of triangles, not a field: `heightAt` answers on it and null off it
253
+ * @example const collar = new HeightfieldCollar({ resolution: 129, size: 512, rings: 384, ringDistance: (ring) => (ring / 384) ** 1.65 * 2100, walkBand: 200, height: ({ x, z }) => surveyed.heightAt(x, z) });
254
+ */
255
+ declare class HeightfieldCollar {
256
+ #private;
257
+ /** The drawn ring grid: positions, then the index triangles between the rings. */
258
+ readonly geometry: BufferGeometry;
259
+ /** Vertices around one ring. */
260
+ readonly perimeter: number;
261
+ /** Ring count, outermost included. */
262
+ readonly rings: number;
263
+ /** The band a collider follows, and the outermost ring it reaches. */
264
+ readonly walk: IHeightfieldCollarWalk;
265
+ /** Metres past the edge that stay walkable. */
266
+ readonly walkBand: number;
267
+ constructor(options: IHeightfieldCollarOptions);
268
+ /**
269
+ * The boundary sample one perimeter vertex stands over: a column and row of the heightfield's own
270
+ * grid, in the walk's order, so the square's edge heights, seams and colours are a lookup.
271
+ */
272
+ boundary(vertex: number): {
273
+ readonly column: number;
274
+ readonly row: number;
275
+ };
276
+ /** Metres past the square's edge of one ring. */
277
+ distance(ring: number): number;
278
+ /**
279
+ * The drawn collar's height under a world point: bilinear across the quad a scatter placement
280
+ * stands on, so a tree follows the ring grid it is planted on. Null where there is no collar.
281
+ */
282
+ heightAt(x: number, z: number): number | null;
283
+ /** Vertex index of one ring site, for writing an attribute over the drawn ring grid. */
284
+ index(ring: number, vertex: number): number;
285
+ /**
286
+ * The quad a world point falls in, or undefined inside the square and past the outermost ring.
287
+ * Its four corners are `index(lower|upper, from|to)`.
288
+ */
289
+ locate(x: number, z: number): IHeightfieldCollarQuad | undefined;
290
+ }
291
+
292
+ /**
293
+ * Metres a river's water reaches sideways per metre of its channel width.
294
+ *
295
+ * The water stands on its bed, not on the spline: the bake measures a channel's wet reach at 2.5
296
+ * widths either side of its centreline. The drawn ribbon and the query below read this one number,
297
+ * so a swimmer cannot leave the surface they see.
298
+ */
299
+ declare const WATER_RIBBON_REACH = 2.5;
300
+ /** One river as the bake records it: stations along its centreline, its width and its flow. */
301
+ interface IWaterRibbon {
302
+ /** Stations `[x, y, z]` in world metres; `y` is the surface height at the station. */
303
+ readonly points: readonly (readonly number[])[];
304
+ /** Metres of water across the channel. The surface reaches `2.5 * width` m either side. */
305
+ readonly width: number;
306
+ /** Downstream speed in m/s, the flow that carries a swimmer along the tangent. */
307
+ readonly flow: number;
308
+ }
309
+ /** One lake as the bake records it: where its flood fill was seeded, its level and its cap. */
310
+ interface IWaterLake {
311
+ /** Where the flood fill was seeded, `[x, z]` in world metres. */
312
+ readonly at: readonly number[];
313
+ /** The surface's height, in metres. */
314
+ readonly level: number;
315
+ /** The furthest the game lets this water reach, in metres, whatever its basin measures. */
316
+ readonly radius: number;
317
+ /** How far past the measured waterline the water reaches, so the shore stands inside it. */
318
+ readonly margin: number;
319
+ }
320
+ /** A sea: one level and the square of ground it floods. */
321
+ interface IWaterOcean {
322
+ /** The surface's height, in metres. */
323
+ readonly level: number;
324
+ /** Metres from the origin the surface covers, either side of it. */
325
+ readonly extent: number;
326
+ }
327
+ /** Which water stands at a point. */
328
+ type WaterBodyKind = "river" | "lake" | "ocean";
329
+ /** The water standing at one (x, z): which body it is and how high its surface is. */
330
+ interface IWaterFootprint {
331
+ readonly kind: WaterBodyKind;
332
+ /** Surface height there, in metres. */
333
+ readonly level: number;
334
+ }
335
+ /** A flow in m/s along x and z; the caller may pass one to reuse instead of allocating. */
336
+ interface IWaterCurrent {
337
+ x: number;
338
+ z: number;
339
+ }
340
+ /** The baked water of one world: the arrays a game's biome file names, and the ground they flood. */
341
+ interface IWaterBodiesOptions {
342
+ readonly ribbons?: readonly IWaterRibbon[];
343
+ readonly lakes?: readonly IWaterLake[];
344
+ readonly ocean?: IWaterOcean;
345
+ /** The canonical terrain. A lake's footprint is measured on it, so any lake needs it. */
346
+ readonly field?: Heightfield;
347
+ }
348
+ /**
349
+ * The furthest a lake's basin reaches on a bearing: where the drawn ground crosses its level.
350
+ *
351
+ * Twenty-four bearings step outwards and stop at the first bank, because binary-searching the whole
352
+ * ray can jump a dry ridge into another pond. Eighteen halvings land inside two centimetres at this
353
+ * scale, well under the ground's own sample spacing.
354
+ *
355
+ * @situation measure where a lake's water meets the ground it floods
356
+ * @situation size a lake's drawn surface or the footprint a swimmer may enter
357
+ * @constraint returns metres on the furthest bearing; the caller applies its own cap
358
+ * @example const reach = waterlineRadius(field, lake.at, lake.level) * 1.12;
359
+ */
360
+ declare function waterlineRadius(field: Heightfield, centre: readonly number[], level: number): number;
361
+ /**
362
+ * How far a lake's water reaches: the waterline its basin measures, `margin` times out, capped.
363
+ *
364
+ * The drawn surface and the swim footprint both size themselves here, so the shore a player sees is
365
+ * the shore they stop at.
366
+ *
367
+ * @situation size a lake's footprint from its basin and the cap its biome row names
368
+ * @constraint reads the heightfield at every bearing, once per lake, never per frame
369
+ * @example const reach = lakeReach(field, { ...lake, margin: 1.12 });
370
+ */
371
+ declare function lakeReach(field: Heightfield, lake: IWaterLake): number;
372
+ /**
373
+ * One world's water, queried: surface height, current and footprint from the baked arrays.
374
+ *
375
+ * Rendering and physics read the same store, as they do for `Heightfield`, so the surface a player
376
+ * sees and the surface a swimmer rests on cannot disagree. Every station, level, extent and speed
377
+ * comes from the game, and the shading stays in the game's own `src/render/`.
378
+ *
379
+ * A river's segments sit in a uniform grid, so a query tests the few that can reach its cell
380
+ * instead of every station of every river.
381
+ *
382
+ * @situation ask how high the water is where a player swims
383
+ * @situation ask which way a current carries a body
384
+ * @situation ask which water body covers a point, and how high its surface is
385
+ * @situation share one water store between rendering and physics
386
+ * @constraint every station, level, extent and speed comes from the game's own bake; a lake is measured on the field passed in
387
+ * @example const water = new WaterBodies({ ribbons, lakes, field }); const height = water.surfaceAt(x, z);
388
+ */
389
+ declare class WaterBodies {
390
+ #private;
391
+ constructor(options: IWaterBodiesOptions);
392
+ /** The height of the water at (x, z), or `undefined` where none is drawn. */
393
+ surfaceAt(x: number, z: number): number | undefined;
394
+ /**
395
+ * The flow that carries a body at (x, z), in m/s, or `undefined` where there is no water.
396
+ *
397
+ * A river carries a swimmer along its tangent at the ribbon's flow; a lake and the sea stand still
398
+ * and report a zero vector. The result is written into `out` when one is passed, so a caller in a
399
+ * hot loop owns no allocation.
400
+ */
401
+ currentAt(x: number, z: number, out?: IWaterCurrent): IWaterCurrent | undefined;
402
+ /** Which water body covers (x, z) and how high its surface is, or `undefined` where none is. */
403
+ footprintAt(x: number, z: number): IWaterFootprint | undefined;
404
+ }
405
+
406
+ /**
407
+ * The terrain geometry `TerrainTiles` builds and keeps: level meshes, skirts, edges, stitch strips and
408
+ merged blocks. Split out of `world-tiles.ts` verbatim (PRD-797).
409
+ */
410
+
17
411
  type MeshSurface = NonNullable<ConstructorParameters<typeof Mesh>[1]>;
412
+
18
413
  interface IWorldTileCollider {
19
414
  dispose(): void;
20
415
  }
@@ -91,6 +486,13 @@ interface IWorldTilesOptions {
91
486
  readonly residentByteBudget: number;
92
487
  readonly residentTileBudget: number;
93
488
  readonly sampleHeight: IHeightfieldSamplerOptions["sampleHeight"];
489
+ /** The ground's footprint in tile-local metres: a tile wholly outside it is never meshed (it only repeats the edge sample). */
490
+ readonly extent?: {
491
+ readonly maxX: number;
492
+ readonly maxZ: number;
493
+ readonly minX: number;
494
+ readonly minZ: number;
495
+ };
94
496
  /** How deep each edge skirt extends below its surface. Defaults to one tile width. */
95
497
  readonly skirtDepth?: number;
96
498
  /** Square tile neighborhood to consider around the followed point. Defaults to 1. */
@@ -243,6 +645,11 @@ declare class TerrainTiles extends Object3D implements IComputeDriven {
243
645
  required: number;
244
646
  loaded: number;
245
647
  };
648
+ /** Loaded selected tiles intersecting the camera; bounds include terrain heights before admission. */
649
+ readinessInView(camera: Camera, heightBounds: readonly [number, number]): {
650
+ required: number;
651
+ loaded: number;
652
+ };
246
653
  debug(): Record<string, unknown>;
247
654
  detach(): void;
248
655
  dispose(): void;
@@ -357,12 +764,19 @@ interface IWorldTerrain {
357
764
  interface IWorldAssetLod {
358
765
  readonly glb: string;
359
766
  readonly distance: number;
767
+ /**
768
+ * Scene to draw from `glb`. A cooked species stores every level of one model in one file with
769
+ * its textures, so its levels name the same `glb` and select a scene instead of a file.
770
+ */
771
+ readonly scene?: string;
360
772
  }
361
773
  interface IWorldAssetBounds {
362
774
  readonly min: readonly [number, number, number];
363
775
  readonly max: readonly [number, number, number];
364
776
  }
365
777
  interface IWorldAsset {
778
+ /** Caller-owned terminal impostor distance in world metres; requires WorldCells impostors opt-in. */
779
+ readonly impostorDistance?: number;
366
780
  readonly glb: string;
367
781
  readonly lods?: readonly IWorldAssetLod[];
368
782
  readonly bounds: IWorldAssetBounds;
@@ -401,6 +815,8 @@ interface IWorldPackage {
401
815
  readonly terrain: IWorldTerrain;
402
816
  readonly assets: Readonly<Record<string, IWorldAsset>>;
403
817
  readonly placements: string;
818
+ /** Optional package-relative JSON array of placement IDs in binary record order. */
819
+ readonly placementIds?: string;
404
820
  readonly cells: readonly IWorldCell[];
405
821
  }
406
822
  interface IWorldPackageValidationOptions {
@@ -666,6 +1082,14 @@ interface ITerrainSplatLayer {
666
1082
  readonly id: string;
667
1083
  readonly tile: number;
668
1084
  readonly tint: readonly [number, number, number];
1085
+ /** Package-relative image paths; omitted entries retain `<textures>/<id>_<kind>.jpg`.
1086
+ * Normal, ORM and height maps are still loaded only when their flags request them. */
1087
+ readonly maps?: {
1088
+ readonly diffuse?: string;
1089
+ readonly normal?: string;
1090
+ readonly orm?: string;
1091
+ readonly height?: string;
1092
+ };
669
1093
  readonly normal?: boolean;
670
1094
  /** `<id>_orm.jpg`: occlusion in r, roughness in g, metalness in b, read as linear data. */
671
1095
  readonly orm?: boolean;
@@ -739,13 +1163,45 @@ interface ITerrainSplatWeightContext {
739
1163
  /** The layer's index in `table.layers`. */
740
1164
  readonly index: number;
741
1165
  }
1166
+ /** Loaded images for one game-authored sample; index 0 is the base, then table.layers in order.
1167
+ * The loader owns these images until the returned material is disposed; do not dispose them. */
1168
+ interface ITerrainSplatSampleContext {
1169
+ readonly layer: ITerrainSplatLayer;
1170
+ readonly index: number;
1171
+ readonly diffuse: Texture;
1172
+ readonly normal: Texture | undefined;
1173
+ readonly orm: Texture | undefined;
1174
+ readonly height: Texture | undefined;
1175
+ }
1176
+ /** A game's projected layer. An absent normal leaves the accumulated normal unchanged.
1177
+ * Normals are encoded OpenGL for the default factory; a custom factory owns their encoding.
1178
+ * An absent ORM uses the layer's existing map or scalar response. */
1179
+ interface ITerrainSplatSample {
1180
+ readonly color: Node<"vec3">;
1181
+ readonly normal?: Node<"vec3">;
1182
+ readonly orm?: Node<"vec3">;
1183
+ }
1184
+ /** Engine-blended channels; color includes the table's macro variation. */
1185
+ interface ITerrainSplatMaterialContext {
1186
+ readonly color: Node<"vec3">;
1187
+ readonly normal: Node<"vec3">;
1188
+ readonly orm: Node<"vec3">;
1189
+ }
742
1190
  interface ILoadTerrainSplatOptions {
743
1191
  readonly assets: IAssetLoader;
1192
+ /** Game-authored appearance. The baked splat mask descriptor and texture folder remain in the package. */
1193
+ readonly table?: Pick<ITerrainSplatTable, "base" | "breakup" | "macro" | "layers">;
744
1194
  /**
745
1195
  * The live renderer. Uncompressed layers stack into one array texture per set through GPU copies,
746
1196
  * which need one; without it every layer keeps its own sampler and the marker says so.
747
1197
  */
748
1198
  readonly renderer?: IRendererLike;
1199
+ /** Precomputed for every layer before layerWeight runs; replaces the package's projection.
1200
+ * Custom sampling retains the loaded images and skips texture-array stacking. */
1201
+ readonly layerSample?: (context: ITerrainSplatSampleContext) => ITerrainSplatSample;
1202
+ /** Replaces final material assembly, retaining the engine's ordered channel blend.
1203
+ * Loader-owned textures are released with the returned material, including composition errors. */
1204
+ readonly materialFactory?: (context: ITerrainSplatMaterialContext) => Material;
749
1205
  /**
750
1206
  * Replaces each layer's blend weight, given the mask's own (remapped, 0..1) and the layer's
751
1207
  * height sample. The game owns the curve, for example a height blend; the package mixes colour,
@@ -772,52 +1228,83 @@ interface ILoadTerrainSplatOptions {
772
1228
  * @situation the game's terrain should match the DCC's terrain material without a second copy
773
1229
  * @constraint the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe
774
1230
  * @constraint WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
775
- * @override every value comes from the package's table; the returned material is the game's to adjust
1231
+ * @override `table` may replace `base`, `breakup`, `macro` and `layers` from game source; baked `splat` and `textures` stay package-owned
776
1232
  * @example
777
1233
  * const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
778
1234
  * const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
779
1235
  */
780
1236
  declare function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promise<Material>;
1237
+ /**
1238
+ * Apply a cooked GLB's package-authored layered surface to its marked terrain meshes.
1239
+ * `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch
1240
+ * path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.
1241
+ * @situation apply the authored layered terrain surface after loading a cooked world GLB
1242
+ * @constraint url names the loaded GLB; tnTerrainSurface extras name a relative world package JSON
1243
+ * @override `table` may replace `base`, `breakup`, `macro` and `layers`; baked `splat` and `textures` stay package-owned
1244
+ * @example
1245
+ * await applyTerrainSurface(world.scene, { assets: ctx.assets, renderer: ctx.renderer, url: "world/world.glb" });
1246
+ */
1247
+ declare function applyTerrainSurface(root: Object3D, options: ILoadTerrainSplatOptions): Promise<void>;
1248
+
1249
+ /**
1250
+ * three's MaterialX Perlin (`mx_noise_float` on a vec3) evaluated per pixel costs about 400 ALU
1251
+ * operations a call. The Strata forest's ground made 44 calls a pixel: 10 ms of a 27 ms frame on an
1252
+ * RTX 2080, the foliage 4 ms more. Unreal's advice for its own Noise expression is the same as this
1253
+ * file: bake it into a texture and read that (UE 5.8.3: Engine/Source/Runtime/Engine/Classes/
1254
+ * Materials/MaterialExpressionNoise.h:58, "can be expensive to compute").
1255
+ *
1256
+ * The volume holds that exact noise: the same Bob Jenkins hash, the same twelve gradients, the same
1257
+ * quintic fade and 0.982 scale, with the integer lattice wrapped every {@link NOISE_PERIOD} cells so
1258
+ * the volume tiles. Inside the first period the baked value at a texel centre is three's value; the
1259
+ * texture filter interpolates between centres {@link NOISE_TEXELS} to a lattice cell apart. Each
1260
+ * channel is an independent field (the lattice is hashed at a different z offset).
1261
+ */
1262
+ declare const NOISE_PERIOD = 8;
1263
+ /** Texels per lattice cell: a cell holds the fade's S-curve in eight linear steps. */
1264
+ declare const NOISE_TEXELS = 8;
1265
+ /**
1266
+ * The one volume every material shares: baked on first use, 1 MiB of RGBA8 (it stays in L2).
1267
+ *
1268
+ * @situation a material needs the raw baked noise texture to sample in its own TSL
1269
+ * @constraint baked once per page on the main thread (about 0.15 s); every channel is an independent field
1270
+ * @example const volume = noiseVolume();
1271
+ */
1272
+ declare function noiseVolume(): Data3DTexture;
1273
+ type Scalar = Node<"float"> | number;
1274
+ /**
1275
+ * Drop-in for `mx_noise_float(p, amplitude, pivot)` on a vec3 `p`: one filtered read of the baked
1276
+ * volume instead of the per-pixel Perlin. Only the 3D form: three's 2D Perlin is another function
1277
+ * (0.66 scale), so a vec2 caller keeps `mx_noise_float`. `channel` 1 to 3 are independent fields.
1278
+ *
1279
+ * @situation a terrain, foliage or water shader calls mx_noise_float per pixel and the frame is GPU bound
1280
+ * @situation open world ground material with procedural variation that must hold 60 FPS
1281
+ * @constraint the field tiles every NOISE_PERIOD units of p; at p = world metres x 2.6 that is a 3 m repeat
1282
+ * @constraint vec3 input only: three's 2D Perlin is another function
1283
+ * @override keep mx_noise_float where exact analytic noise matters more than the frame
1284
+ * @example const patch = smoothstep(-0.35, 0.35, bakedNoise(positionWorld.mul(0.025)));
1285
+ */
1286
+ declare function bakedNoise(p: Node<"vec3">, amplitude?: Scalar, pivot?: Scalar, channel?: 0 | 1 | 2 | 3): Node<"float">;
1287
+ /**
1288
+ * Drop-in for `mx_fractal_noise_float(p, octaves, lacunarity, diminish, amplitude)`: one read an octave.
1289
+ *
1290
+ * @situation fractal or fbm noise in a material costs too much GPU time per pixel
1291
+ * @constraint octaves is a build-time number; each octave is one filtered volume read
1292
+ * @example const macro = bakedFractalNoise(vec3(positionWorld.x, 0, positionWorld.z).mul(0.014), 3);
1293
+ */
1294
+ declare function bakedFractalNoise(p: Node<"vec3">, octaves?: number, lacunarity?: number, diminish?: number, amplitude?: Scalar): Node<"float">;
781
1295
 
782
1296
  /** What a launch asked the GPU-scene occlusion cull to do. `measure` counts; `off` runs no test. */
783
1297
  type OcclusionMode = "off" | "measure";
784
1298
 
1299
+ /** What one landed readback concluded, in the three words a log line can carry. */
1300
+ type GpuSceneVerdict = "ok" | "mismatch" | "error";
785
1301
  /**
786
- * One shadow map's own three numbers, which is the whole of what a level render knows that the main
787
- * camera does not.
1302
+ * The memory numbers a validation line can carry, all of them optional.
788
1303
  *
789
- * They are the level's, never the camera's: a map's frustum is the light's window, its gate is the
790
- * texel size it can resolve, and its base is the chain level the cluster path hands it — `#probe`
791
- * swaps a coarse level's geometry for the coarsest shape, so a coarse map draws that shape whatever a
792
- * placement's own distance would have selected. The distance itself is the main pass's, from the
793
- * eye: a placement's shape and its cast come from the key the main pass draws it in.
794
- */
795
- interface IShadowLevel {
796
- /** The six frustum planes of this map's own shadow camera. */
797
- readonly planes: Float32Array;
798
- /** This map's texel gate in world metres: a placement narrower than it casts nothing here. */
799
- readonly gate: number;
800
- /**
801
- * The chain level this map draws at, floored over the placement's own. 0 is the placement's own
802
- * LOD by distance — what the finest map draws — and the coarsest index is what every level past
803
- * the first draws. A base whose keys are not minted draws nothing, which is why a caller settling
804
- * the prewarm first is the contract rather than a fallback.
805
- *
806
- * {@link COARSEST_SHADOW_LEVEL} is past every chain, and means the coarsest shape an asset has: a
807
- * map that coarsens its casters does not know how long each asset's chain is, and the floor is
808
- * clamped per asset, so one number asks every chain for its own coarsest level.
809
- */
810
- readonly base: number;
811
- }
812
- /** What one landed readback concluded, in the three words a log line can carry. */
813
- type GpuSceneVerdict = "ok" | "mismatch" | "error";
814
- /**
815
- * The memory numbers a validation line can carry, all of them optional.
816
- *
817
- * The first seven are three's `info.memory` fields (`WebGPURenderer`, 0.185); a backend that tracks
818
- * none of them reports none, which is why every field is optional and only finite numbers are
819
- * printed — an absent reading is not a zero. `footprintBytes` is the sum of this scene's own storage
820
- * buffer `footprint()` bytes, the one number here Three did not write.
1304
+ * The first seven are three's `info.memory` fields (`WebGPURenderer`, 0.185); a backend that tracks
1305
+ * none of them reports none, which is why every field is optional and only finite numbers are
1306
+ * printed — an absent reading is not a zero. `footprintBytes` is the sum of this scene's own storage
1307
+ * buffer `footprint()` bytes, the one number here Three did not write.
821
1308
  */
822
1309
  type GpuSceneMemoryField = "storageAttributes" | "storageAttributesSize" | "indirectStorageAttributes" | "indirectStorageAttributesSize" | "readbackBuffers" | "readbackBuffersSize" | "total" | "footprintBytes";
823
1310
  /** One validation's memory reading; a field is absent when the backend did not offer a finite one. */
@@ -899,7 +1386,76 @@ interface IGpuSceneComparison {
899
1386
  /** The snapshot's own camera and nearest live placement, when both instance totals landed zero. */
900
1387
  readonly probe?: IValidationProbe;
901
1388
  }
902
- /** One completed manual frame check, identified by the caller's frame and this scene's dispatch. */
1389
+
1390
+ /**
1391
+ * One shadow map's own three numbers, which is the whole of what a level render knows that the main
1392
+ * camera does not.
1393
+ *
1394
+ * They are the level's, never the camera's: a map's frustum is the light's window, its gate is the
1395
+ * texel size it can resolve, and its base is the chain level the cluster path hands it — `#probe`
1396
+ * swaps a coarse level's geometry for the coarsest shape, so a coarse map draws that shape whatever a
1397
+ * placement's own distance would have selected. The distance itself is the main pass's, from the
1398
+ * eye: a placement's shape and its cast come from the key the main pass draws it in.
1399
+ */
1400
+ interface IShadowLevel {
1401
+ /** The six frustum planes of this map's own shadow camera. */
1402
+ readonly planes: Float32Array;
1403
+ /** This map's texel gate in world metres: a placement narrower than it casts nothing here. */
1404
+ readonly gate: number;
1405
+ /**
1406
+ * The chain level this map draws at, floored over the placement's own. 0 is the placement's own
1407
+ * LOD by distance — what the finest map draws — and the coarsest index is what every level past
1408
+ * the first draws. A base whose keys are not minted draws nothing, which is why a caller settling
1409
+ * the prewarm first is the contract rather than a fallback.
1410
+ *
1411
+ * {@link COARSEST_SHADOW_LEVEL} is past every chain, and means the coarsest shape an asset has: a
1412
+ * map that coarsens its casters does not know how long each asset's chain is, and the floor is
1413
+ * clamped per asset, so one number asks every chain for its own coarsest level.
1414
+ */
1415
+ readonly base: number;
1416
+ }
1417
+
1418
+ /**
1419
+ * What the measured occlusion pass found, when a launch asked it to measure.
1420
+ *
1421
+ * `reason` names why it measured nothing (`no scene depth`), and the counts and `gpuTriangles` come
1422
+ * from one landed dispatch, even if a later tally was skipped for occlusion.
1423
+ */
1424
+ interface IOcclusionReport {
1425
+ readonly mode: OcclusionMode;
1426
+ readonly reason: string;
1427
+ /** Pyramid levels and the dispatches that rebuild them each frame. */
1428
+ readonly levels: number;
1429
+ readonly buildDispatches: number;
1430
+ /** The last landed sample, and the mean over every sample that landed. */
1431
+ readonly instances: number;
1432
+ readonly triangles: number;
1433
+ readonly meanInstances: number;
1434
+ readonly meanTriangles: number;
1435
+ readonly samples: number;
1436
+ /** `triangles / gpuTriangles` of the same sample, which is what the go/no-go multiplies. */
1437
+ readonly share: number;
1438
+ readonly gpuTriangles: number;
1439
+ readonly ageFrames: number;
1440
+ }
1441
+
1442
+ /**
1443
+ * The GPU-driven main pass of a streamed world: one compute dispatch culls and LOD-selects every
1444
+ * resident placement, appends the survivors into a shared compacted matrix buffer, and each main
1445
+ * batch draws its own region of that buffer with the instance count living in a GPU-side
1446
+ * `DrawIndexedIndirect` record. The CPU keeps only the coarse per-key visibility.
1447
+ *
1448
+ * Everything the kernel needs is GPU data. The CPU writes the placement buffer when residency
1449
+ * changes and the indirect records when a key is minted, retired or regrown — a structural event —
1450
+ * and nothing at all per instance per frame.
1451
+ *
1452
+ * The per-instance logic exists twice on purpose: {@link cullAndSelect} is the reference, in plain
1453
+ * TypeScript, in `world-gpu-reference.ts`, and the TSL kernel below mirrors it line for line. The
1454
+ * tests run in node with no GPU, so the reference is what is proved against the CPU path; the
1455
+ * kernel is compiled in the browser. The types, layout constants and launch flags it shares with the
1456
+ * validation module live in `world-gpu-types.ts` and `world-gpu-flags.ts`, which is what keeps this
1457
+ * file and `world-gpu-validation.ts` from importing each other.
1458
+ */
903
1459
  interface IWorldGpuFrameValidation extends IGpuSceneComparison {
904
1460
  /** The caller's rendered-frame identity, never inferred from readback timing. */
905
1461
  readonly frame: number;
@@ -935,23 +1491,7 @@ interface IWorldGpuSceneReport {
935
1491
  * counts and `occlusion.gpuTriangles` come from one landed dispatch, even if a later tally
936
1492
  * was skipped for occlusion.
937
1493
  */
938
- readonly occlusion?: {
939
- readonly mode: OcclusionMode;
940
- readonly reason: string;
941
- /** Pyramid levels and the dispatches that rebuild them each frame. */
942
- readonly levels: number;
943
- readonly buildDispatches: number;
944
- /** The last landed sample, and the mean over every sample that landed. */
945
- readonly instances: number;
946
- readonly triangles: number;
947
- readonly meanInstances: number;
948
- readonly meanTriangles: number;
949
- readonly samples: number;
950
- /** `triangles / gpuTriangles` of the same sample, which is what the go/no-go multiplies. */
951
- readonly share: number;
952
- readonly gpuTriangles: number;
953
- readonly ageFrames: number;
954
- };
1494
+ readonly occlusion?: IOcclusionReport;
955
1495
  }
956
1496
 
957
1497
  /** The point a streamed world follows; an `Object3D` satisfies this shape. */
@@ -1016,6 +1556,8 @@ interface IWorldCellsLoadOptions {
1016
1556
  readonly createCollider?: IWorldTilesOptions["createCollider"];
1017
1557
  /** Read once per update; an `Object3D` works. */
1018
1558
  readonly follow: IWorldCellsFollow;
1559
+ /** Called when a nonempty cell batch becomes visible to the renderer. */
1560
+ readonly onPublication?: (bounds: Box3) => void;
1019
1561
  /** Chebyshev radius in cells to keep resident; a cell leaves only beyond `ring + 1`. */
1020
1562
  readonly ring: number;
1021
1563
  readonly budgets: IWorldCellsBudget;
@@ -1025,15 +1567,42 @@ interface IWorldCellsLoadOptions {
1025
1567
  * cells only, with strict measured triangle/draw savings and projected-error hysteresis.
1026
1568
  * Source collision and shadow representations stay resident; unsupported sources retain detail. */
1027
1569
  readonly hlod?: boolean;
1570
+ /**
1571
+ * Whether an asset whose authored `maxDistance` ends inside the near ring keeps a whole-map far
1572
+ * aggregate. `"ring"` (the default) skips it: the ring always draws those cells itself, and a
1573
+ * far record it does not own is further away than the asset's own cull, so the aggregate could
1574
+ * never draw a pixel while still costing an instance buffer, an atlas and a draw. `"always"` is
1575
+ * the named override, reported once per kept asset as `TN_WORLD_IMPOSTOR_FAR ...
1576
+ * override=impostorFar`.
1577
+ */
1578
+ readonly impostorFar?: "ring" | "always";
1028
1579
  /** Optional immutable per-record 3D draw reach in metres, indexed like placements.
1029
1580
  * Nonnegative finite values or Infinity (no extra limit); combined with asset maxDistance.
1030
1581
  * Filtered by the existing admission/refilter budget, never by a separate culler.
1031
1582
  */
1032
1583
  readonly placementReach?: Float32Array;
1033
- /** Inward return margin for authored CPU LODs, in [0, 1). Requires gpuScene:false and impostors:false; omission keeps source levels.
1584
+ /** Inward return margin for authored CPU LODs, in [0, 1). Requires gpuScene:false; when
1585
+ * combined with automatic impostors, also requires preserveAuthoredParts and authored distances.
1034
1586
  * Omitted, selection uses the existing direct gates. State survives cell eviction/revisit. */
1035
1587
  readonly lodHysteresis?: number;
1036
- /** Preserve supplied part/material identity and exact authored LOD membership, including shadow batches. Requires impostors:false; omission keeps source levels.
1588
+ /** How a `lodHysteresis` level change reaches the screen. `"band"` (default) cross-fades over a
1589
+ * distance band `lodHysteresis` wide with a per-pixel dither; a placement standing in the band
1590
+ * stays dithered, which crawls without temporal AA. `"temporal"` is UE 5.8.3's instanced foliage
1591
+ * (`foliage.DitheredLOD` 1, `lod.TemporalLag` 0.5 s): the gate is hard in space and the change
1592
+ * fades over half a second, so no placement stays mid-fade while the viewer stands still.
1593
+ * `"none"` pops whole at the gate. */
1594
+ readonly lodTransition?: "band" | "none" | "temporal";
1595
+ /** Where the CPU path measures a placement's level and `maxDistance` cull from. `"camera"` (the
1596
+ * default) is the render camera's world position, the eye the GPU dispatch already uses: UE 5.8.3
1597
+ * picks instance LODs per view from the view origin
1598
+ * (`Engine/Source/Runtime/Engine/Private/HierarchicalInstancedStaticMesh.cpp:1652`) and streams
1599
+ * around the view target (`Engine/Source/Runtime/Engine/Private/PlayerController.cpp:3705`), so a
1600
+ * camera far from the player no longer draws the player's full-detail trees. Residency and
1601
+ * `placementReach` stay on `follow`. Until a camera reaches `update`, the eye is `follow`.
1602
+ * `"follow"` is the named override, as are `TN_LOD_FROM_CAMERA=0` and `?tnLodFromCamera=0`;
1603
+ * `stats().lodFrom` and `TN_WORLD_MAIN_CULL lodFrom=` report which one ran. */
1604
+ readonly lodFrom?: "camera" | "follow";
1605
+ /** Preserve supplied part/material identity and exact authored LOD membership, including shadow batches. Automatic impostors require each asset to author `impostorDistance`.
1037
1606
  * Default content sharing and missing-alpha-part coverage remain enabled when omitted. */
1038
1607
  readonly preserveAuthoredParts?: boolean;
1039
1608
  /** Already decoded immutable world-v1 data; URL still supplies the base for model paths. */
@@ -1062,6 +1631,15 @@ interface IWorldCellsLoadOptions {
1062
1631
  readonly shadows?: {
1063
1632
  readonly cast?: boolean;
1064
1633
  readonly castLevels?: number;
1634
+ /**
1635
+ * The finest level a shadow draws, default 0. A placement drawn at a finer level casts in this
1636
+ * level's shape when every finer level has as many parts at the same local transforms, so the
1637
+ * shadow keeps one shape while the view swaps levels: a cached shadow page redraws at most once a
1638
+ * second and showed every swap since in one batch. UE 5.8.3 draws shadows a level coarser by
1639
+ * default (`r.Shadow.NaniteLODBias` 1, Renderer/Private/Shadows/ShadowSceneRenderer.cpp:48-52).
1640
+ * It applies to the caster clusters; a world whose shadow levels draw its GPU keys casts as before.
1641
+ */
1642
+ readonly minLevel?: number;
1065
1643
  readonly receive?: boolean;
1066
1644
  /**
1067
1645
  * @deprecated Accepted and ignored. Clusters replace it: what a shadow level submits is bounded
@@ -1306,12 +1884,12 @@ interface IWorldCellsLoadOptions {
1306
1884
  * Bake a whole-asset octahedral impostor for every alpha-cutout foliage asset and append it as the
1307
1885
  * asset's terminal, two-triangle LOD. Default false: omission keeps the authored/generated source
1308
1886
  * levels, and `?tnImpostors=1` or `TN_IMPOSTORS=1` opts a launch in. It is opt-in until the judged
1309
- * Machinefall capture passes (PRD-473 AC-3); `preserveAuthoredParts` and `lodHysteresis` still
1310
- * require it to be off.
1887
+ * Machinefall capture passes (PRD-473 AC-3). With `preserveAuthoredParts`, an asset must author
1888
+ * `impostorDistance` to receive a terminal impostor.
1311
1889
  *
1312
1890
  * Set true to bake them, or leave it off to keep the source levels for a visual comparison.
1313
1891
  *
1314
- * The bake runs inside the render cadence — one of its sixteen views per `process` — so it costs a
1892
+ * The bake runs inside the render cadence — one atlas view per `process` — so it costs a
1315
1893
  * slice of a frame rather than a hitch, and it starts only after the asset's own model has been
1316
1894
  * adopted. A seamless switch needs the impostor's atlas to cover the same cutout the source draws,
1317
1895
  * so an asset whose levels carry no alpha-cutout part is never baked. `false` drops only the atlas
@@ -1333,8 +1911,43 @@ interface IWorldCellsGpuTally {
1333
1911
  readonly triangles: number;
1334
1912
  readonly ageFrames: number;
1335
1913
  }
1914
+ /** Local render coverage, independent of shader prewarm and distant admission. */
1915
+ interface IWorldRegionReadiness {
1916
+ readonly requiredCells: number;
1917
+ readonly loadedCells: number;
1918
+ readonly requiredTerrainTiles: number;
1919
+ readonly loadedTerrainTiles: number;
1920
+ readonly failures: number;
1921
+ readonly cancelled: boolean;
1922
+ readonly ready: boolean;
1923
+ }
1924
+ /**
1925
+ * A plain `{ min, max }` region, the shape a shadow level's invalidation reads and the shape a game
1926
+ * can be handed without importing three. Plain numbers, so the object a caller records its bounds
1927
+ * in is the object that crosses the boundary.
1928
+ */
1929
+ interface IShadowRegion {
1930
+ /** Only added casters; their redraw can retain the existing depth. */
1931
+ admission?: boolean;
1932
+ min: {
1933
+ x: number;
1934
+ y: number;
1935
+ z: number;
1936
+ };
1937
+ max: {
1938
+ x: number;
1939
+ y: number;
1940
+ z: number;
1941
+ };
1942
+ }
1336
1943
  interface IWorldCellsStats {
1337
1944
  readonly residentCells: number;
1945
+ /**
1946
+ * Placement bytes the resident cells hold. Admission adds them. Eviction removes them.
1947
+ * Far-impostor and HLOD bytes sit outside this figure, in `impostor.far.bytes` and `hlod.bytes`.
1948
+ * `budgets.bytes` caps the sum of all three.
1949
+ */
1950
+ readonly residentBytes: number;
1338
1951
  /** Resident cells whose initial placement runs and chunks have completed admission. */
1339
1952
  readonly loadedCells: number;
1340
1953
  readonly residentKeys: readonly string[];
@@ -1347,6 +1960,10 @@ interface IWorldCellsStats {
1347
1960
  readonly loadsInFlight: number;
1348
1961
  /** Model loads waiting for a free lane; served nearest-cell first, in admission order. */
1349
1962
  readonly loadsQueued: number;
1963
+ /** Remaining placement slices and batch publications waiting for admission. */
1964
+ readonly admissionBacklog: number;
1965
+ /** Cumulative placement slices, mesh builds, and final run swaps completed by admission. */
1966
+ readonly admissionCompletedUnits: number;
1350
1967
  /**
1351
1968
  * Shared batches still to be minted, plus the ones minted and not yet drawn; `0` once
1352
1969
  * `prewarmed` has resolved.
@@ -1364,13 +1981,9 @@ interface IWorldCellsStats {
1364
1981
  * was worth anything. See `LEVEL_REFILTER_STEP_METRES`.
1365
1982
  */
1366
1983
  readonly refilters: number;
1367
- /**
1368
- * Cumulative replacement builds that entered CPU placement-level selection. Initial admission is
1369
- * excluded; GPU `maxDistance`/LOD movement is not a replacement because its complete resident
1370
- * source set stays available to dispatch selection. Explicit `placementReach` replacements are
1371
- * included because reach remains a CPU admission boundary.
1372
- */
1373
1984
  readonly levelRefilters: number;
1985
+ /** Where the CPU path's levels were measured from; see `IWorldCellsLoadOptions.lodFrom`. */
1986
+ readonly lodFrom: "camera" | "follow";
1374
1987
  /**
1375
1988
  * Cumulative stale cell-assets the refilter passes found, across every update. The pass walks every
1376
1989
  * resident cell and gates it as a whole before it looks at one batch, so a follow point that has
@@ -1403,13 +2016,10 @@ interface IWorldCellsStats {
1403
2016
  /**
1404
2017
  * What the GPU-driven main pass is doing, and why it is not: `on` is the answer, `reason` is the
1405
2018
  * one line `TN_WORLD_GPU_SCENE` printed, and `dispatches` is what the walk actually paid for its
1406
- * per-instance work. `mainCull.repacks` stays at `0` while it is on, and `levelRefilters` reports
1407
- * replacement builds that still execute CPU placement-level selection. GPU `maxDistance`/LOD
1408
- * movement is not a replacement because the source set stays resident for dispatch selection.
1409
- * The aggregate `refilters` counter can still rise for its retained scan, and explicit
1410
- * `placementReach` replacements remain visible. `dressed` over `meshes` is the marker line's own
1411
- * pair, and it is the one that says the scene has meshes to draw with: an `on` with `0` dressed is
1412
- * a ring the CPU path is still drawing.
2019
+ * per-instance work. `mainCull.repacks` and `refilters` stay at `0` while it is on — that is the
2020
+ * CPU work it replaced, counted by the same counters that report it when it is off. `dressed` over
2021
+ * `meshes` is the marker line's own pair, and it is the one that says the scene has meshes to draw
2022
+ * with: an `on` with `0` dressed is a ring the CPU path is still drawing.
1413
2023
  */
1414
2024
  readonly gpuScene: {
1415
2025
  readonly on: boolean;
@@ -1443,9 +2053,11 @@ interface IWorldCellsStats {
1443
2053
  * invalidations since load: membership, material or geometry changes and CPU window repacks
1444
2054
  * invalidate; GPU indirect count updates do not.
1445
2055
  *
1446
- * `eligibility` counts CPU material checks, snapshot validations, fresh structural walks and
1447
- * oversized or unsupported child output. Snapshots check own links and Three's child readers on
1448
- * every check, detecting deep edits without requiring `needsUpdate`; child discovery still allocates.
2056
+ * `eligibility` counts CPU material checks, snapshot validations, fresh structural walks,
2057
+ * oversized or unsupported child output, and `deferred` deep proofs. Snapshots check own links and
2058
+ * Three's child readers, detecting deep edits without requiring `needsUpdate`, once per
2059
+ * `staleFrames` period: 1 for a small world, the tested rows over a per-frame budget for a forest.
2060
+ * Child discovery still allocates.
1449
2061
  *
1450
2062
  * `reason` is who asked: `default` is a run that set nothing, `option` is a load that named
1451
2063
  * `bundles`, and `launch` is `?tnBundles` / `TN_BUNDLES` / `__tnBundles`. It is on the marker line
@@ -1462,6 +2074,8 @@ interface IWorldCellsStats {
1462
2074
  readonly refreshes: number;
1463
2075
  readonly validations: number;
1464
2076
  readonly uncached: number;
2077
+ readonly deferred: number;
2078
+ readonly staleFrames: number;
1465
2079
  };
1466
2080
  readonly reason: string;
1467
2081
  readonly records: number;
@@ -1476,6 +2090,7 @@ interface IWorldCellsStats {
1476
2090
  readonly impostor: {
1477
2091
  readonly assets: number;
1478
2092
  readonly pending: number;
2093
+ readonly drawn: number;
1479
2094
  readonly atlasBytes: number;
1480
2095
  readonly budgetBytes: number;
1481
2096
  readonly terminalTriangles: number;
@@ -1507,7 +2122,6 @@ interface IWorldCellsStats {
1507
2122
  readonly pending: number;
1508
2123
  readonly bytes: number;
1509
2124
  readonly refused: number;
1510
- /** Why the latest proxy was refused, or empty when none was; a count alone names no cause. */
1511
2125
  readonly reason: string;
1512
2126
  readonly failures: number;
1513
2127
  };
@@ -1531,35 +2145,20 @@ interface IWorldCellsStats {
1531
2145
  readonly backlog: number;
1532
2146
  };
1533
2147
  }
1534
- /** Local render coverage, independent of shader prewarm and distant admission. */
1535
- interface IWorldRegionReadiness {
1536
- readonly requiredCells: number;
1537
- readonly loadedCells: number;
1538
- readonly requiredTerrainTiles: number;
1539
- readonly loadedTerrainTiles: number;
1540
- readonly failures: number;
1541
- readonly cancelled: boolean;
1542
- readonly ready: boolean;
1543
- }
2148
+
1544
2149
  /**
1545
- * A plain `{ min, max }` region, the shape a shadow level's invalidation reads and the shape a game
1546
- * can be handed without importing three. Plain numbers, so the object a caller records its bounds
1547
- * in is the object that crosses the boundary.
2150
+ * A random in [0, 1) that stays with its instance, as UE 5.8.3's PerInstanceRandom: hashed from the
2151
+ * instance's world origin, never from its draw slot. WorldCells repacks instances on every refilter,
2152
+ * main-pass cull and LOD switch, so `instanceIndex` names another tree from one frame to the next; a
2153
+ * wind phase hashed from it re-rolled each crown about every 0.7 s of a walk and snapped its top by a
2154
+ * median 0.37 m. Parts of one placement share its translation, so its bark and needles read one value.
2155
+ *
2156
+ * @situation a per-instance random number that stays with each streamed placement as WorldCells repacks
2157
+ * @situation replace instanceIndex in a WorldCells part material, which WorldCells refuses
2158
+ * @example const phase = instanceRandom().mul(6.2831);
1548
2159
  */
1549
- interface IShadowRegion {
1550
- /** Only added casters; their redraw can retain the existing depth. */
1551
- admission?: boolean;
1552
- min: {
1553
- x: number;
1554
- y: number;
1555
- z: number;
1556
- };
1557
- max: {
1558
- x: number;
1559
- y: number;
1560
- z: number;
1561
- };
1562
- }
2160
+ declare function instanceRandom(): Node<"float">;
2161
+
1563
2162
  /**
1564
2163
  * Stream a Blender-authored world package by cell and keep it resident around a followed point.
1565
2164
  *
@@ -1583,13 +2182,15 @@ interface IShadowRegion {
1583
2182
  * @constraint surface is the game's; this class creates no material, colour or geometry
1584
2183
  * @constraint a cell's model loads at `soon` priority, so a file the running scene awaits through `ctx.assets` starts first
1585
2184
  * @constraint budgets are hard caps that report pressure instead of over-committing
2185
+ * @constraint `whenSpawnReady(position, radius, timeoutMs)` snapshots a fixed region and settles from existing updates or disposal; it does not drive streaming, and `prewarmed` remains the separate draw gate
1586
2186
  * @constraint model loads are bounded by `concurrency` (default 12) across every resident cell, not per cell
1587
2187
  * @constraint refilters are bounded by `rebuildsPerUpdate` (default 16) per update, nearest cell first
2188
+ * @constraint residency and `placementReach` follow `follow`; levels and `maxDistance` are graded from the render camera, as UE picks instance LODs per view; `lodFrom: "follow"`, `?tnLodFromCamera=0` or `TN_LOD_FROM_CAMERA=0` grade from `follow`, reported as `TN_WORLD_MAIN_CULL lodFrom=`
1588
2189
  * @constraint admission is bounded by `admissionBudgetMs` (default 2) per update across every path, plus at most one unit each for terrain and props; while props are queued terrain takes at most half, so neither starves the other, and a deferred cell keeps drawing what it has
1589
2190
  * @constraint SkinnedMesh parts are skipped; an instanced copy would draw one rest pose
1590
2191
  * @constraint a baked chain's switch distances are measured against `autoLod` (default 4 px of error over 60° and 1080 raster rows), because an instanced draw cannot select a level per instance; an asset with nonempty authored `lods` never consults it; explicit empty lists enroll only unchanged static geometry/material parts
1591
2192
  * @constraint eligible static sources can use cooked HLOD (chunk-only alongside GPU scatter, whole-cell on CPU) after compilation and an observed main-context backend submission; projected-error hysteresis requires actual source triangle reduction and no extra material draws, unsupported or shared source stays resident, and collision/shadow paths retain source representations; stats().hlod counts lifecycle and charged resources, not GPU timing or physical allocation
1592
- * @override `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance
2193
+ * @override `hlod: false` keeps source rendering; ring, budgets, terrain tile size/resolution, terrain stream and collider radius, `transparentScatter`, `clusterSize` and `shadows.invalidate`, load `concurrency`, `rebuildsPerUpdate`, `admissionBudgetMs` and the package's per-asset maxDistance; `impostorFar: "always"` keeps the far aggregate the near ring's guaranteed radius made unnecessary
1593
2194
  * @constraint `prewarmed` resolves once every prewarmed shared batch has been drawn; a game with a loading screen waits on it, and `stats().pendingPrewarm` is the same gate as a number
1594
2195
  * @constraint every `asset:level:part` is one InstancedMesh for the main pass, plus one caster InstancedMesh per world-grid square of `clusterSize` on the shadow caster layer, so the main pass draws one mesh per key and a shadow level submits only the squares it covers
1595
2196
  * @constraint two definitions the asset loader resolves to one model — the same cooked `glb`, the same `lods` at the same distances, the same `maxDistance` and bounds — are one asset under the lexicographically smallest id: one model load, one set of `asset:level:part` keys, one prewarm and one refcount, released when the last cell holding any member of the group leaves the ring; `TN_WORLD_ASSET_ALIAS` reports how many of the package's assets are really distinct
@@ -1629,8 +2230,10 @@ declare class WorldCells extends Group implements IComputeDriven {
1629
2230
  * The loading gate a game with a loading screen waits on, so the shader builds the prewarm exists
1630
2231
  * to move happen behind it instead of in the first seconds of play. It counts updates the world
1631
2232
  * was in a scene for, because a batch added while the world is not in a scene is projected by
1632
- * nothing and builds nothing. `dispose` settles it too: a world torn down mid-load must not leave
1633
- * a game awaiting it forever.
2233
+ * nothing and builds nothing. A world with nothing to prewarm — no resident cell and no model
2234
+ * load, so no update of its own can queue one — settles on those updates like a drained world,
2235
+ * which is what lets a game await it for every world it streams. `dispose` settles it too: a
2236
+ * world torn down mid-load must not leave a game awaiting it forever.
1634
2237
  */
1635
2238
  get prewarmed(): Promise<void>;
1636
2239
  /**
@@ -1682,160 +2285,23 @@ declare class WorldCells extends Group implements IComputeDriven {
1682
2285
  stats(): IWorldCellsStats;
1683
2286
  detach(): void;
1684
2287
  /** Completed content intersecting a square around a fixed spawn, in world metres. */
1685
- readinessAt(position: {
2288
+ readinessAt(position: Camera | {
1686
2289
  readonly x: number;
1687
2290
  readonly z: number;
1688
2291
  }, radius?: number): IWorldRegionReadiness;
2292
+ /** Terrain data needed by the current camera, including visible tiles not yet admitted. */
2293
+ terrainReadinessInView(camera: Camera): {
2294
+ required: number;
2295
+ loaded: number;
2296
+ };
2297
+ /** Visible CPU scatter batches still awaiting a nonempty main-camera backend submission. */
2298
+ pendingCpuDrawsInView(camera: Camera): number;
2299
+ /** Resolves when the content a fixed spawn needs has finished loading; see `CellReadiness`. */
2300
+ whenSpawnReady(position: {
2301
+ readonly x: number;
2302
+ readonly z: number;
2303
+ }, radius?: number, timeoutMs?: number): Promise<IWorldRegionReadiness>;
1689
2304
  dispose(): void;
1690
2305
  }
1691
2306
 
1692
- interface IHeightfieldOrigin {
1693
- readonly x: number;
1694
- readonly z: number;
1695
- }
1696
- interface IHeightfieldOptions {
1697
- readonly columns: number;
1698
- readonly depth: number;
1699
- readonly heights: Float32Array;
1700
- readonly origin: IHeightfieldOrigin;
1701
- readonly rows: number;
1702
- readonly width: number;
1703
- readonly worldPasses?: IHeightfieldWorldPassOptions;
1704
- }
1705
- /** A rectangular window of a heightfield's canonical samples, in grid indices. */
1706
- /** Hands out the union of every window `updateHeights` wrote since the last `take`. */
1707
- interface IHeightfieldChangeTracker {
1708
- /** The changed window since the previous take, or undefined when nothing changed. */
1709
- take(): IHeightfieldRegionBounds | undefined;
1710
- /** Stop tracking. Idempotent. */
1711
- dispose(): void;
1712
- }
1713
- interface IHeightfieldRegionBounds {
1714
- /** First column (x index), inclusive. */
1715
- readonly column: number;
1716
- /** Number of columns covered. */
1717
- readonly columns: number;
1718
- /** First row (z index), inclusive. */
1719
- readonly row: number;
1720
- /** Number of rows covered. */
1721
- readonly rows: number;
1722
- }
1723
- /** A rectangular window plus the replacement samples written over it. */
1724
- interface IHeightfieldRegion extends IHeightfieldRegionBounds {
1725
- /** Row-major samples, `columns * rows` long and read with the region's own stride. */
1726
- readonly heights: Float32Array;
1727
- }
1728
- interface IHeightfieldWorldPassOptions {
1729
- /** Maximum TSL compute dispatches submitted by one rendered frame. */
1730
- readonly dispatchBudget: number;
1731
- /** Reserved GPU path; true is rejected until GPU readback owns the canonical field. */
1732
- readonly gpu?: boolean;
1733
- /** Every physical coefficient is game supplied; core owns no terrain preset. */
1734
- readonly erosion: IWorldErosionOptions;
1735
- }
1736
- interface IHeightfieldSamplerOptions extends Omit<IHeightfieldOptions, "heights"> {
1737
- /** Game-owned terrain function. It is evaluated once and never retained. */
1738
- readonly sampleHeight: (x: number, z: number) => number;
1739
- }
1740
- interface IStoredHeightfieldChannels {
1741
- readonly flow?: Float32Array;
1742
- readonly moisture?: Float32Array;
1743
- }
1744
- /**
1745
- * One height buffer shared by world queries, rendered geometry, and a physics heightfield.
1746
- *
1747
- * The game supplies every value, so changing the terrain's shape never requires a package edit.
1748
- * `fromSampler` evaluates that game function exactly once at each vertex and retains only the
1749
- * resulting numbers. Queries interpolate those same numbers instead of evaluating the function
1750
- * again.
1751
- *
1752
- * @situation build terrain geometry and collision from one game-authored height function
1753
- * @situation generate a terrain a player can walk across
1754
- * @situation query the same ground height or normal that a player sees and collides with
1755
- * @situation ask how high the ground is here
1756
- * @situation build islands and coastlines from terrain
1757
- * @situation keep a collider or other copy of a deforming terrain in step without rescanning the whole field (`trackChanges`)
1758
- * @constraint sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output
1759
- * @constraint rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order
1760
- * @override rows, columns, width, depth, origin, and sampleHeight are explicit on every field
1761
- * @example const field = Heightfield.fromSampler({ rows: 65, columns: 65, width: 64, depth: 64, origin: { x: 0, z: 0 }, sampleHeight: terrainHeight });
1762
- */
1763
- declare class Heightfield extends Group implements IComputeDriven {
1764
- #private;
1765
- readonly columns: number;
1766
- readonly depth: number;
1767
- readonly origin: IHeightfieldOrigin;
1768
- readonly rows: number;
1769
- readonly width: number;
1770
- readonly processCadence: "render";
1771
- readonly warmupNodes: readonly unknown[];
1772
- constructor(options: IHeightfieldOptions & IStoredHeightfieldChannels);
1773
- static fromSampler(options: IHeightfieldSamplerOptions): Heightfield;
1774
- sample(channel: string, x: number, z: number): number;
1775
- get released(): boolean;
1776
- get generationComplete(): boolean;
1777
- get gpuHeightSample(): IGPUReadbackSample | undefined;
1778
- attachRenderer(renderer: IRendererLike): void;
1779
- process(renderer?: IRendererLike | undefined): void;
1780
- debug(): Record<string, unknown>;
1781
- detach(): void;
1782
- /** A copy of the canonical row-major samples, safe for game-side analysis. */
1783
- get heights(): Float32Array;
1784
- /** A copy of the normalized routed-flow channel, when world passes were requested. */
1785
- get flow(): Float32Array | undefined;
1786
- /** Bytes retained by this field's CPU channels and its conservative GPU allowance. */
1787
- get memoryBytes(): number;
1788
- heightAt(x: number, z: number): number;
1789
- normalAt(x: number, z: number, target?: Vector3): Vector3;
1790
- /**
1791
- * Monotonic sample version, incremented by every `updateHeights` call.
1792
- *
1793
- * A renderer or collider that caches derived data compares this against its own last-seen value
1794
- * instead of diffing the whole grid each frame.
1795
- */
1796
- get version(): number;
1797
- /**
1798
- * Overwrite one rectangular window of the canonical samples.
1799
- *
1800
- * Height is the one buffer queries, rendered geometry and collider export share, so a second
1801
- * terrain representation is never needed: a simulation writes its surface here and every
1802
- * consumer already reads it. The whole window is validated before any sample changes, so a
1803
- * malformed call leaves the field untouched rather than half-written.
1804
- * @situation deform terrain, snow or water in place and have queries and collision follow
1805
- * @constraint the region must lie inside the field; an out-of-bounds window throws and writes nothing
1806
- * @constraint heights is `columns * rows` long, row-major, and every sample must be finite
1807
- */
1808
- updateHeights(region: IHeightfieldRegion): void;
1809
- /**
1810
- * Follow which samples change, independently of every other follower.
1811
- *
1812
- * A consumer that mirrors the surface — a collider, a GPU copy, a cache — needs the window that
1813
- * changed since *it* last looked; comparing the whole field instead costs every sample on every
1814
- * change. Each tracker keeps its own union of the windows `updateHeights` wrote, so two
1815
- * consumers never take each other's changes.
1816
- *
1817
- * ```ts
1818
- * const changes = field.trackChanges();
1819
- * const changed = changes.take(); // undefined when nothing was written
1820
- * ```
1821
- */
1822
- trackChanges(): IHeightfieldChangeTracker;
1823
- /** The collider sample at `row`, `column`: what `toColliderHeights()` holds there, without a copy. */
1824
- colliderHeight(row: number, column: number): number;
1825
- /**
1826
- * Rewrite an existing `toGeometry()` result from the current canonical samples.
1827
- *
1828
- * Positions carry over unchanged because only the surface moves; y and normals are refreshed
1829
- * from the same sampler queries use, which is what keeps a rendered vertex and a height query
1830
- * from disagreeing. Pass a region to touch only the window a simulation just changed.
1831
- * @situation redraw a terrain, snow or water mesh after its samples changed
1832
- * @constraint geometry must come from `toGeometry()` with the same rows and columns
1833
- */
1834
- refreshGeometry(geometry: BufferGeometry, bounds?: IHeightfieldRegionBounds): void;
1835
- /** The same values transposed once into Rapier's column-major height-matrix order. */
1836
- toColliderHeights(): Float32Array;
1837
- /** Builds an ordinary Three.js geometry without choosing its surface. */
1838
- toGeometry(): BufferGeometry;
1839
- }
1840
-
1841
- export { Heightfield, type IAdmissionBudget, type IHeightfieldChangeTracker, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldRegion, type IHeightfieldRegionBounds, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type ILoadTerrainSplatOptions, type IShadowRegion, type ISnowContact, type ISnowFieldOptions, type ISnowFieldSample, type ISnowFootprint, type ISnowFootprintSample, type ITerrainSplatLayer, type ITerrainSplatMaskedLayer, type ITerrainSplatTable, type ITerrainSplatWeightContext, type IWorldAsset, type IWorldAssetBounds, type IWorldAssetLod, type IWorldCapabilities, type IWorldCell, type IWorldCellProxy, type IWorldCellsBudget, type IWorldCellsFollow, type IWorldCellsLoadOptions, type IWorldCellsStats, type IWorldCellsTerrainOptions, type IWorldExtent, type IWorldGpuFrameValidation, type IWorldPackage, type IWorldPackageError, type IWorldPackageValidationOptions, type IWorldRegionReadiness, type IWorldRun, type IWorldTerrain, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, SnowField, TERRAIN_VALIDATE_FLAG, TERRAIN_VALIDATE_MARKER, TerrainTiles, WorldCells, type WorldPackageErrorCode, cellPlacements, getWorldCapabilities, heightSamplerFromHeightmap, loadTerrainSplat, loadWorldHeightmap, snowDiscFootprint, terrainValidationRequested, validateWorldPackage };
2307
+ export { Heightfield, HeightfieldCollar, type IAdmissionBudget, type IHeightfieldChangeTracker, type IHeightfieldCollarOptions, type IHeightfieldCollarQuad, type IHeightfieldCollarSite, type IHeightfieldCollarWalk, type IHeightfieldOptions, type IHeightfieldOrigin, type IHeightfieldRegion, type IHeightfieldRegionBounds, type IHeightfieldSamplerOptions, type IHeightfieldWorldPassOptions, type ILoadTerrainSplatOptions, type IShadowRegion, type ISnowContact, type ISnowFieldOptions, type ISnowFieldSample, type ISnowFootprint, type ISnowFootprintSample, type ITerrainSplatLayer, type ITerrainSplatMaskedLayer, type ITerrainSplatMaterialContext, type ITerrainSplatSample, type ITerrainSplatSampleContext, type ITerrainSplatTable, type ITerrainSplatWeightContext, type IWaterBodiesOptions, type IWaterCurrent, type IWaterFootprint, type IWaterLake, type IWaterOcean, type IWaterRibbon, type IWorldAsset, type IWorldAssetBounds, type IWorldAssetLod, type IWorldCapabilities, type IWorldCell, type IWorldCellProxy, type IWorldCellsBudget, type IWorldCellsFollow, type IWorldCellsLoadOptions, type IWorldCellsStats, type IWorldCellsTerrainOptions, type IWorldExtent, type IWorldGpuFrameValidation, type IWorldPackage, type IWorldPackageError, type IWorldPackageValidationOptions, type IWorldRegionReadiness, type IWorldRun, type IWorldTerrain, type IWorldTileColliderInput, type IWorldTilesTopologyObservation, NOISE_PERIOD, NOISE_TEXELS, SnowField, TERRAIN_VALIDATE_FLAG, TERRAIN_VALIDATE_MARKER, TerrainTiles, WATER_RIBBON_REACH, WaterBodies, type WaterBodyKind, WorldCells, type WorldPackageErrorCode, applyTerrainSurface, bakedFractalNoise, bakedNoise, cellPlacements, getWorldCapabilities, heightSamplerFromHeightmap, instanceRandom, lakeReach, loadTerrainSplat, loadWorldHeightmap, noiseVolume, snowDiscFootprint, terrainValidationRequested, validateWorldPackage, waterlineRadius };