@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,469 @@
1
+ /**
2
+ * The terrain geometry `TerrainTiles` builds and keeps: level meshes, skirts, edges, stitch strips and
3
+ merged blocks. Split out of `world-tiles.ts` verbatim (PRD-797).
4
+ */
5
+
6
+ import { Box3, BufferAttribute, BufferGeometry, Mesh, Sphere, Vector3 } from "three";
7
+ import { edgeWorldPoint } from "./terrain-jobs.js";
8
+ import type {
9
+ ITerrainBridgeAttributes,
10
+ ITerrainEdgeJob,
11
+ ITerrainFineEdgeJob,
12
+ ITerrainMergeJob,
13
+ ITerrainMergeResult,
14
+ } from "./terrain-jobs.js";
15
+ import type { Heightfield, IHeightfieldOrigin } from "./world-heightfield.js";
16
+ import {
17
+ edgeVertexHeight,
18
+ edgeVertexIndex,
19
+ tileEdgeFrame,
20
+ validateBridgeTriangleTopology,
21
+ } from "./world-tile-observation.js";
22
+ export type MeshSurface = NonNullable<ConstructorParameters<typeof Mesh>[1]>;
23
+ import { CONSTRUCTION_CHUNK_SAMPLES, edgeSamplesFor, resolutionFor } from "./world-tile-budget.js";
24
+ import type { IEdgeSamples, ILevelGeometry, IResidentTile, IStitchBridge } from "./world-tiles.js";
25
+ export function appendQuad(
26
+ indices: number[],
27
+ topLeft: number,
28
+ bottomLeft: number,
29
+ topRight: number,
30
+ bottomRight: number,
31
+ ): void {
32
+ indices.push(topLeft, bottomLeft, topRight, topRight, bottomLeft, bottomRight);
33
+ }
34
+
35
+ /**
36
+ * The field's own sample heights, once, with a ring of clamped neighbours around them.
37
+ *
38
+ * `normalAt` reads the height at the point and at its four field-cell neighbours, so a level built
39
+ * vertex by vertex asked the field six times per vertex — 33,800 `heightAt` calls for a 65x65 tile
40
+ * and every coarser level with it (46 ms + 46 ms a streaming frame). This is the same set of samples
41
+ * read once, and the ring repeats the edge sample, which is exactly the clamp `normalAt` applies at
42
+ * the field's own border. One grid serves every level of the tile, because a level's vertices are
43
+ * every `lodFactor`-th of the field's.
44
+ */
45
+ export function* fieldHeightGrid(
46
+ field: Heightfield,
47
+ chunked: boolean,
48
+ ): Generator<void, Float32Array> {
49
+ const columns = field.columns + 2;
50
+ const cellWidth = field.width / (field.columns - 1);
51
+ const cellDepth = field.depth / (field.rows - 1);
52
+ const minimumX = field.origin.x - field.width / 2;
53
+ const minimumZ = field.origin.z - field.depth / 2;
54
+ const grid = new Float32Array(columns * (field.rows + 2));
55
+ for (let row = 0; row < field.rows + 2; row += 1) {
56
+ const z = minimumZ + Math.min(field.rows - 1, Math.max(0, row - 1)) * cellDepth;
57
+ for (let column = 0; column < columns; column += 1) {
58
+ const x = minimumX + Math.min(field.columns - 1, Math.max(0, column - 1)) * cellWidth;
59
+ grid[row * columns + column] = field.heightAt(x, z);
60
+ if (chunked && (row * columns + column + 1) % CONSTRUCTION_CHUNK_SAMPLES === 0) yield;
61
+ }
62
+ }
63
+ return grid;
64
+ }
65
+
66
+ /**
67
+ * How many field samples a level's vertices are apart. An integer by `resolutionFor`'s own check,
68
+ * and the reason one grid serves every level: vertex column `n` sits on field sample `n * step`.
69
+ */
70
+ export function fieldStep(field: Heightfield, resolution: number): number {
71
+ const step = (field.columns - 1) / (resolution - 1);
72
+ if (!Number.isInteger(step) || step < 1)
73
+ throw new Error("TerrainTiles level vertices must land on the field's own sample grid.");
74
+ return step;
75
+ }
76
+
77
+ /**
78
+ * Tags a mesh as terrain, so the frame budget counts its main-pass draw under `terrain` instead of
79
+ * under the `other` every mesh no world system claimed lands in. Every mesh this file creates goes
80
+ * through here — a tile level, a stitch bridge and a merged block — because a source that is tagged
81
+ * at three of the four places it exists is a split nobody can reconcile.
82
+ */
83
+ export function terrainMesh(mesh: Mesh): Mesh {
84
+ mesh.userData.tnDrawSource = "terrain";
85
+ // Visibility only swaps this mesh with a twin over the same ground (its merged block, or the
86
+ // neighbouring LOD level), so a cached shadow map need not redraw for it; see `casterFlag`.
87
+ mesh.userData.tnShadowSwap = true;
88
+ return mesh;
89
+ }
90
+
91
+ /** Three's box/sphere arithmetic, over the same float32 positions, in admission-sized scans. */
92
+ export function* levelBounds(
93
+ positions: Float32Array,
94
+ chunked: boolean,
95
+ ): Generator<void, { box: Box3; sphere: Sphere }> {
96
+ const box = new Box3();
97
+ const point = new Vector3();
98
+ for (let index = 0; index < positions.length; index += 3) {
99
+ point.fromArray(positions, index);
100
+ box.expandByPoint(point);
101
+ if (chunked && (index / 3 + 1) % CONSTRUCTION_CHUNK_SAMPLES === 0) yield;
102
+ }
103
+ const sphere = new Sphere();
104
+ box.getCenter(sphere.center);
105
+ let radiusSquared = 0;
106
+ for (let index = 0; index < positions.length; index += 3) {
107
+ point.fromArray(positions, index);
108
+ radiusSquared = Math.max(radiusSquared, sphere.center.distanceToSquared(point));
109
+ if (chunked && (index / 3 + 1) % CONSTRUCTION_CHUNK_SAMPLES === 0) yield;
110
+ }
111
+ sphere.radius = Math.sqrt(radiusSquared);
112
+ return { box, sphere };
113
+ }
114
+
115
+ export function* buildLevel(
116
+ field: Heightfield,
117
+ resolution: number,
118
+ skirtDepth: number,
119
+ surface: MeshSurface,
120
+ grid: Float32Array,
121
+ chunked: boolean,
122
+ ): Generator<void, ILevelGeometry> {
123
+ const positions: number[] = [];
124
+ const normals: number[] = [];
125
+ const heights: number[] = [];
126
+ const minimumX = field.origin.x - field.width / 2;
127
+ const minimumZ = field.origin.z - field.depth / 2;
128
+ const cellWidth = field.width / (resolution - 1);
129
+ const cellDepth = field.depth / (resolution - 1);
130
+ const fieldCellWidth = field.width / (field.columns - 1);
131
+ const fieldCellDepth = field.depth / (field.rows - 1);
132
+ const gridColumns = field.columns + 2;
133
+ const step = fieldStep(field, resolution);
134
+ const normal = new Vector3();
135
+ for (let row = 0; row < resolution; row += 1) {
136
+ const z = minimumZ + row * cellDepth;
137
+ const fieldRow = row * step;
138
+ const gridRow = fieldRow + 1;
139
+ for (let column = 0; column < resolution; column += 1) {
140
+ const x = minimumX + column * cellWidth;
141
+ const fieldColumn = column * step;
142
+ const at = gridRow * gridColumns + fieldColumn + 1;
143
+ const height = grid[at] as number;
144
+ heights.push(height);
145
+ positions.push(x - field.origin.x, height, z - field.origin.z);
146
+ // `normalAt`'s stencil, off the same grid: a field cell either side, clamped at the border,
147
+ // over the distance those two samples really are apart.
148
+ const column0 = Math.min(field.columns - 1, Math.max(0, fieldColumn - 1));
149
+ const column1 = Math.min(field.columns - 1, fieldColumn + 1);
150
+ const row0 = Math.min(field.rows - 1, Math.max(0, fieldRow - 1));
151
+ const row1 = Math.min(field.rows - 1, fieldRow + 1);
152
+ const slopeX =
153
+ ((grid[gridRow * gridColumns + column1 + 1] as number) -
154
+ (grid[gridRow * gridColumns + column0 + 1] as number)) /
155
+ ((column1 - column0) * fieldCellWidth);
156
+ const slopeZ =
157
+ ((grid[(row1 + 1) * gridColumns + fieldColumn + 1] as number) -
158
+ (grid[(row0 + 1) * gridColumns + fieldColumn + 1] as number)) /
159
+ ((row1 - row0) * fieldCellDepth);
160
+ normal.set(-slopeX, 1, -slopeZ).normalize();
161
+ normals.push(normal.x, normal.y, normal.z);
162
+ if (chunked && (row * resolution + column + 1) % CONSTRUCTION_CHUNK_SAMPLES === 0) yield;
163
+ }
164
+ }
165
+ const indices: number[] = [];
166
+ for (let row = 0; row < resolution - 1; row += 1) {
167
+ for (let column = 0; column < resolution - 1; column += 1) {
168
+ const topLeft = row * resolution + column;
169
+ appendQuad(indices, topLeft, topLeft + resolution, topLeft + 1, topLeft + resolution + 1);
170
+ if (chunked && (row * (resolution - 1) + column + 1) % CONSTRUCTION_CHUNK_SAMPLES === 0)
171
+ yield;
172
+ }
173
+ }
174
+
175
+ const edges = [
176
+ (index: number) => index,
177
+ (index: number) => (resolution - 1) * resolution + index,
178
+ (index: number) => index * resolution,
179
+ (index: number) => index * resolution + resolution - 1,
180
+ ];
181
+ for (const edge of edges) {
182
+ const bottom = positions.length / 3;
183
+ for (let index = 0; index < resolution; index += 1) {
184
+ const top = edge(index);
185
+ positions.push(
186
+ positions[top * 3] as number,
187
+ (positions[top * 3 + 1] as number) - skirtDepth,
188
+ positions[top * 3 + 2] as number,
189
+ );
190
+ normals.push(0, 1, 0);
191
+ }
192
+ for (let index = 0; index < resolution - 1; index += 1) {
193
+ const topLeft = edge(index);
194
+ const topRight = edge(index + 1);
195
+ appendQuad(indices, topLeft, bottom + index, topRight, bottom + index + 1);
196
+ }
197
+ }
198
+
199
+ const positionArray = Float32Array.from(positions);
200
+ const bounds = yield* levelBounds(positionArray, chunked);
201
+ const geometry = new BufferGeometry();
202
+ geometry.morphTargetsRelative = true;
203
+ geometry.setAttribute("position", new BufferAttribute(positionArray, 3));
204
+ geometry.setAttribute("normal", new BufferAttribute(Float32Array.from(normals), 3));
205
+ geometry.setIndex(new BufferAttribute(Uint32Array.from(indices), 1));
206
+ geometry.boundingBox = bounds.box;
207
+ geometry.boundingSphere = bounds.sphere;
208
+ const skirt = inspectSkirtGeometry(geometry, resolution, edges);
209
+ return {
210
+ surfaceError: 0,
211
+ edgeSamples: edgeSamplesFor(heights, resolution),
212
+ geometry,
213
+ mesh: terrainMesh(new Mesh(geometry, surface)),
214
+ resolution,
215
+ skirtDepth: skirt.depth,
216
+ skirtVertexCount: skirt.vertexCount,
217
+ };
218
+ }
219
+
220
+ /**
221
+ * A block's merged attributes, as the geometry the main thread swaps in. The concatenation itself
222
+ * is `mergeBlockAttributes`, which runs in a worker wherever a host has one; this is the part that
223
+ * cannot leave the main thread — a `BufferGeometry` and its bounds.
224
+ */
225
+ export function mergedBlockGeometry(result: ITerrainMergeResult): BufferGeometry {
226
+ const geometry = new BufferGeometry();
227
+ geometry.setAttribute("position", new BufferAttribute(result.positions, 3));
228
+ geometry.setAttribute("normal", new BufferAttribute(result.normals, 3));
229
+ geometry.setIndex(new BufferAttribute(result.indices, 1));
230
+ geometry.computeBoundingBox();
231
+ geometry.computeBoundingSphere();
232
+ return geometry;
233
+ }
234
+
235
+ /** One settled tile level's attributes, as the merge job reads them. */
236
+ export function mergeJob(
237
+ parts: readonly { readonly geometry: BufferGeometry; readonly origin: IHeightfieldOrigin }[],
238
+ blockOrigin: IHeightfieldOrigin,
239
+ ): ITerrainMergeJob {
240
+ return {
241
+ blockOrigin,
242
+ kind: "merge",
243
+ parts: parts.map(({ geometry, origin }) => {
244
+ const index = geometry.getIndex();
245
+ if (index === null)
246
+ throw new Error("TerrainTiles merged block geometry needs an index buffer.");
247
+ return {
248
+ indices: index.array as Uint32Array,
249
+ normals: (geometry.getAttribute("normal") as BufferAttribute).array as Float32Array,
250
+ origin,
251
+ positions: (geometry.getAttribute("position") as BufferAttribute).array as Float32Array,
252
+ };
253
+ }),
254
+ };
255
+ }
256
+
257
+ export function inspectSkirtGeometry(
258
+ geometry: BufferGeometry,
259
+ resolution: number,
260
+ edges: readonly ((index: number) => number)[],
261
+ ): { depth: number; vertexCount: number } {
262
+ const position = geometry.getAttribute("position");
263
+ const surfaceVertexCount = resolution * resolution;
264
+ const vertexCount = position.count - surfaceVertexCount;
265
+ if (vertexCount < 0 || vertexCount % edges.length !== 0)
266
+ throw new Error("TerrainTiles generated skirt geometry has an invalid vertex count.");
267
+ if (vertexCount === 0) return { depth: 0, vertexCount: 0 };
268
+ const edgeVertexCount = vertexCount / edges.length;
269
+ let depth = Number.POSITIVE_INFINITY;
270
+ for (const [edgeIndex, edge] of edges.entries()) {
271
+ for (let index = 0; index < edgeVertexCount; index += 1) {
272
+ const top = edge(index);
273
+ const bottom = surfaceVertexCount + edgeIndex * edgeVertexCount + index;
274
+ depth = Math.min(depth, position.getY(top) - position.getY(bottom));
275
+ }
276
+ }
277
+ if (!Number.isFinite(depth) || depth < 0)
278
+ throw new Error("TerrainTiles generated skirt geometry has an invalid depth.");
279
+ return { depth, vertexCount };
280
+ }
281
+
282
+ export function refreshEdgeSamples(level: ILevelGeometry): void {
283
+ for (const side of ["east", "north", "south", "west"] as const) {
284
+ const samples = level.edgeSamples[side];
285
+ for (let index = 0; index < level.resolution; index += 1)
286
+ samples[index] = edgeVertexHeight(level, side, index);
287
+ }
288
+ }
289
+
290
+ /**
291
+ * A level mid-blend already carries the union of both levels' bounds, widened once when the
292
+ * transition started, and the canonical edge this writes is inside it. So the blend's three frames
293
+ * restore the edge and leave the bounds alone: recomputing them walked the level's ~4,500
294
+ * positions per seam per frame, which is the `setFromBufferAttribute` + `computeBoundingSphere` +
295
+ * `computeBoundingBox` + `expandByPoint` the six-second walk spent inside a transition.
296
+ */
297
+ export function restoreLevelEdge(
298
+ tile: IResidentTile,
299
+ level: ILevelGeometry,
300
+ side: keyof IEdgeSamples,
301
+ ): boolean {
302
+ const field = tile.field;
303
+ const position = level.geometry.getAttribute("position");
304
+ const normalAttribute = level.geometry.getAttribute("normal");
305
+ const normal = new Vector3();
306
+ const frame = tileEdgeFrame(field, side);
307
+ let changed = false;
308
+ for (let index = 0; index < level.resolution; index += 1) {
309
+ const normalized = index / (level.resolution - 1);
310
+ const [x, , z] = edgeWorldPoint(frame, normalized, 0);
311
+ const vertex = edgeVertexIndex(level, side, index);
312
+ // Compared at float32, the precision the attributes store: a float64 sample never equals its
313
+ // stored copy, so an exact compare reported every edge changed on every call and recomputed
314
+ // the whole tile's bounds per seam per frame (~39 ms/frame on a 25-tile ring).
315
+ const height = Math.fround(field.heightAt(x, z));
316
+ field.normalAt(x, z, normal);
317
+ if (position.getY(vertex) !== height) {
318
+ position.setY(vertex, height);
319
+ changed = true;
320
+ }
321
+ if (
322
+ normalAttribute.getX(vertex) !== Math.fround(normal.x) ||
323
+ normalAttribute.getY(vertex) !== Math.fround(normal.y) ||
324
+ normalAttribute.getZ(vertex) !== Math.fround(normal.z)
325
+ ) {
326
+ normalAttribute.setXYZ(vertex, normal.x, normal.y, normal.z);
327
+ changed = true;
328
+ }
329
+ }
330
+ if (!changed) return false;
331
+ updateLevelSkirts(level);
332
+ refreshEdgeSamples(level);
333
+ position.needsUpdate = true;
334
+ normalAttribute.needsUpdate = true;
335
+ if (tile.lodTransition === undefined) {
336
+ level.geometry.computeBoundingBox();
337
+ level.geometry.computeBoundingSphere();
338
+ }
339
+ return true;
340
+ }
341
+
342
+ /** One level's edge as the bridge job reads it: the row's own heights, copied out of the level. */
343
+ export function edgeJob(
344
+ tile: IResidentTile,
345
+ level: ILevelGeometry,
346
+ side: keyof IEdgeSamples,
347
+ ): ITerrainEdgeJob {
348
+ return {
349
+ depth: tile.field.depth,
350
+ origin: tile.field.origin,
351
+ samples: level.edgeSamples[side].slice(),
352
+ side,
353
+ width: tile.field.width,
354
+ };
355
+ }
356
+
357
+ /** The same edge with the resolution the fine side of a bridge needs. */
358
+ export function fineEdgeJob(
359
+ tile: IResidentTile,
360
+ level: ILevelGeometry,
361
+ side: keyof IEdgeSamples,
362
+ ): ITerrainFineEdgeJob {
363
+ return { ...edgeJob(tile, level, side), resolution: level.resolution };
364
+ }
365
+
366
+ export function stitchGeometry(data: ITerrainBridgeAttributes): BufferGeometry {
367
+ const geometry = new BufferGeometry();
368
+ geometry.setAttribute("position", new BufferAttribute(data.positions, 3));
369
+ geometry.setAttribute("normal", new BufferAttribute(data.normals, 3));
370
+ geometry.setIndex(new BufferAttribute(data.indices, 1));
371
+ geometry.computeBoundingBox();
372
+ geometry.computeBoundingSphere();
373
+ return geometry;
374
+ }
375
+
376
+ export function geometryBytes(geometry: BufferGeometry): number {
377
+ const index = geometry.getIndex();
378
+ return (
379
+ geometry.getAttribute("position").array.byteLength +
380
+ geometry.getAttribute("normal").array.byteLength +
381
+ (index?.array.byteLength ?? 0)
382
+ );
383
+ }
384
+
385
+ export function updateStitchBridge(bridge: IStitchBridge, data: ITerrainBridgeAttributes): void {
386
+ const position = validateBridgeTriangleTopology(bridge.geometry, bridge.resolution * 2);
387
+ if (bridge.resolution !== data.positions.length / 6) {
388
+ const previous = bridge.geometry;
389
+ bridge.geometry = stitchGeometry(data);
390
+ bridge.mesh.geometry = bridge.geometry;
391
+ bridge.resolution = data.positions.length / 6;
392
+ bridge.bytes = geometryBytes(bridge.geometry);
393
+ previous.dispose();
394
+ } else {
395
+ const normal = bridge.geometry.getAttribute("normal");
396
+ const index = bridge.geometry.getIndex();
397
+ if (
398
+ normal === undefined ||
399
+ normal.itemSize !== 3 ||
400
+ normal.count !== position.count ||
401
+ index === null
402
+ )
403
+ throw new Error(
404
+ "TerrainTiles seam diagnostic bridge topology has invalid rendered triangle data.",
405
+ );
406
+ position.array.set(data.positions);
407
+ normal.array.set(data.normals);
408
+ index.array.set(data.indices);
409
+ position.needsUpdate = true;
410
+ normal.needsUpdate = true;
411
+ index.needsUpdate = true;
412
+ bridge.geometry.computeBoundingBox();
413
+ bridge.geometry.computeBoundingSphere();
414
+ }
415
+ bridge.coverageDepth = data.coverageDepth;
416
+ }
417
+
418
+ /**
419
+ * The position attribute is passed in rather than looked up per sample: these run four times a
420
+ * vertex for a blend and four times a sample for the pop measurement — 33,800 `getAttribute` map
421
+ * lookups a transition frame on a 65x65 tile, for a name that cannot change while the level is
422
+ * being written.
423
+ */
424
+
425
+ export function updateLevelSkirts(level: ILevelGeometry): void {
426
+ const position = level.geometry.getAttribute("position");
427
+ const normal = level.geometry.getAttribute("normal");
428
+ const surfaceVertexCount = level.resolution * level.resolution;
429
+ const edges = [
430
+ (index: number) => index,
431
+ (index: number) => (level.resolution - 1) * level.resolution + index,
432
+ (index: number) => index * level.resolution,
433
+ (index: number) => index * level.resolution + level.resolution - 1,
434
+ ];
435
+ for (const [edgeIndex, edge] of edges.entries()) {
436
+ for (let index = 0; index < level.resolution; index += 1) {
437
+ const top = edge(index);
438
+ const bottom = surfaceVertexCount + edgeIndex * level.resolution + index;
439
+ position.setY(bottom, position.getY(top) - level.skirtDepth);
440
+ normal.setXYZ(bottom, 0, 1, 0);
441
+ }
442
+ }
443
+ }
444
+
445
+ export function restoreLevelSurface(field: Heightfield, level: ILevelGeometry): void {
446
+ const position = level.geometry.getAttribute("position");
447
+ const normalAttribute = level.geometry.getAttribute("normal");
448
+ const minimumX = field.origin.x - field.width / 2;
449
+ const minimumZ = field.origin.z - field.depth / 2;
450
+ const cellWidth = field.width / (level.resolution - 1);
451
+ const cellDepth = field.depth / (level.resolution - 1);
452
+ const normal = new Vector3();
453
+ for (let row = 0; row < level.resolution; row += 1) {
454
+ const z = minimumZ + row * cellDepth;
455
+ for (let column = 0; column < level.resolution; column += 1) {
456
+ const x = minimumX + column * cellWidth;
457
+ const index = row * level.resolution + column;
458
+ position.setY(index, field.heightAt(x, z));
459
+ field.normalAt(x, z, normal);
460
+ normalAttribute.setXYZ(index, normal.x, normal.y, normal.z);
461
+ }
462
+ }
463
+ updateLevelSkirts(level);
464
+ refreshEdgeSamples(level);
465
+ position.needsUpdate = true;
466
+ normalAttribute.needsUpdate = true;
467
+ level.geometry.computeBoundingBox();
468
+ level.geometry.computeBoundingSphere();
469
+ }