@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,308 @@
1
+ import {
2
+ BufferAttribute,
3
+ BufferGeometry,
4
+ type Camera,
5
+ Frustum,
6
+ InstancedMesh,
7
+ type Material,
8
+ Matrix4,
9
+ Mesh,
10
+ type Object3D,
11
+ Sphere,
12
+ Vector3,
13
+ } from "three";
14
+ import type { ICasterMesh } from "./render/virtual-shadow-casters.js";
15
+ import { markStatic } from "./static-transform.js";
16
+
17
+ export const CHUNK_NAME = "world-chunk";
18
+
19
+ /**
20
+ * The cascade's caster layers, re-exported: the chunk proxy stands in for merged geometry on the
21
+ * same bits the node and `WorldCells` use, so a drift here would put the world's casters on a layer
22
+ * no level camera reads.
23
+ */
24
+ import {
25
+ VIRTUAL_SHADOW_CASTER_LAYER,
26
+ VIRTUAL_SHADOW_WIDE_CASTER_LAYER,
27
+ } from "./render/virtual-shadow-layers.js";
28
+
29
+ export { VIRTUAL_SHADOW_CASTER_LAYER, VIRTUAL_SHADOW_WIDE_CASTER_LAYER };
30
+
31
+ /**
32
+ * The one surface each `side` of a chunk shadow proxy draws with, world-wide.
33
+ *
34
+ * A depth pass cannot tell one material from another: it reads `side`, `alphaTest` and position,
35
+ * and a proxy covers only opaque, non-alphaTest meshes, so every covered material with the same
36
+ * `side` produces the same shadow pipeline. Borrowing one per covered group built a new one for
37
+ * every chunk that loaded — 23 shadow draws over 125 ms and a 18 ms worst case on the walk this
38
+ * measured, each one compiling a pipeline the one before it had already proven was identical. The
39
+ * first covered material seen for a side is the world's, and every later proxy of that side borrows
40
+ * it, so a world pays at most one shadow pipeline per side over its whole life.
41
+ *
42
+ * The materials are the world's own, so `disposeModel` must not release them with the chunk that
43
+ * happened to contribute them.
44
+ */
45
+ export const worldOwned = new WeakSet<Material>();
46
+
47
+ /**
48
+ * A depth pass cannot tell one material from another, so a chunk's shadow bill is its material
49
+ * count, not its triangle count: ~100 shadow draws a level render on the map, each a per-material
50
+ * mesh walked through the light's frustum. Positions are all it needs, and a position-only geometry
51
+ * grouped by `side` — the one thing a depth material does read — collapses that bill to one draw per
52
+ * side.
53
+ *
54
+ * Every proxy sits on both caster halves: covered originals no longer cast, so choosing
55
+ * key-wide scatter must retain the buildings, towers and fences represented by the proxy.
56
+ * Either way it is counted by the same `#probe` window test as the scatter caster
57
+ * clusters, so a level whose window does not reach the chunk drops it for free. Nothing here decides
58
+ * how anything looks: the covered meshes keep the game's own materials and keep drawing the main pass
59
+ * with them, and the proxy carries the world's material for its `side` by reference — the group it
60
+ * was grouped *by* is the material's own `side`, so the depth pass reads exactly what the covered
61
+ * mesh's own depth material would have read, and this file still constructs no material.
62
+ *
63
+ * Alpha-tested and transparent meshes keep casting themselves. Retained static instances use
64
+ * separate per-side proxies, so their per-part gates do not change the existing merged proxies.
65
+ */
66
+ export function buildChunkShadowProxies(
67
+ chunk: Object3D,
68
+ merged: readonly Mesh[],
69
+ label: string,
70
+ proxyMaterials: Map<number, Material>,
71
+ selectParts = false,
72
+ ): { readonly covered: Mesh[]; readonly proxies: Mesh[] } {
73
+ const sides = new Map<number, { material: Material; meshes: Mesh[] }>();
74
+ for (const mesh of merged) {
75
+ const material = mesh.material;
76
+ if (Array.isArray(material) || material.transparent === true || material.alphaTest > 0)
77
+ continue;
78
+ const side = material.side;
79
+ const group = sides.get(side);
80
+ if (group === undefined) sides.set(side, { material, meshes: [mesh] });
81
+ else group.meshes.push(mesh);
82
+ }
83
+ const covered: Mesh[] = [];
84
+ const proxies: Mesh[] = [];
85
+ for (const [side, group] of sides) {
86
+ // Three's sides occupy 0..2; retained sources have their own compatible material pool.
87
+ const key = side + (selectParts ? 3 : 0);
88
+ const held = proxyMaterials.get(key);
89
+ const material = held ?? group.material;
90
+ if (held === undefined) {
91
+ proxyMaterials.set(key, material);
92
+ worldOwned.add(material);
93
+ }
94
+ const proxy = new Mesh(shadowProxyGeometry(group.meshes, label, chunk), material);
95
+ if (selectParts) selectChunkShadowParts(proxy, group.meshes);
96
+ proxy.name = `${CHUNK_NAME}-shadow`;
97
+ // The origin a draw of this mesh is counted under (`RenderPassBudget`). A proxy on the caster
98
+ // layers never reaches the main pass, so this only says anything where the world's own cull
99
+ // left one on layer 0 — and it is written here rather than inferred, so the tag cannot rot.
100
+ proxy.userData.tnDrawSource = "proxies";
101
+ proxy.layers.set(VIRTUAL_SHADOW_CASTER_LAYER);
102
+ proxy.layers.enable(VIRTUAL_SHADOW_WIDE_CASTER_LAYER);
103
+ proxy.castShadow = true;
104
+ proxy.receiveShadow = false;
105
+ chunk.add(proxy);
106
+ markStatic(proxy);
107
+ proxies.push(proxy);
108
+ for (const mesh of group.meshes) {
109
+ mesh.castShadow = false;
110
+ covered.push(mesh);
111
+ }
112
+ }
113
+ return { covered, proxies };
114
+ }
115
+
116
+ /**
117
+ * One position-only geometry holding every covered mesh's vertices, indices preserved.
118
+ *
119
+ * Read through the attribute's own accessors, because a cooked model's positions can be quantized
120
+ * and interleaved (`KHR_mesh_quantization`) and the raw array behind them is not what three would
121
+ * have drawn. One pass at load time; the result is a depth buffer's whole input.
122
+ */
123
+ /**
124
+ * One mesh's vertices, placed into `positions` from `vertexAt`.
125
+ *
126
+ * A merged mesh's positions came out of `mergeByMaterial` as one plain float array, so that is three
127
+ * reads, three multiplies and three writes per vertex. The arithmetic is three's, term for term and
128
+ * including `applyMatrix4`'s homogeneous divide, so a proxy holds the vertices it held before. A
129
+ * retained source can still be quantized and interleaved (`KHR_mesh_quantization`), and it takes the
130
+ * accessor loop, which is what that arithmetic resolves to.
131
+ */
132
+ function placeVertices(
133
+ position: BufferAttribute,
134
+ matrix: Matrix4,
135
+ positions: Float32Array,
136
+ vertexAt: number,
137
+ ): void {
138
+ if (
139
+ position.array instanceof Float32Array &&
140
+ !position.normalized &&
141
+ !("isInterleavedBufferAttribute" in position)
142
+ ) {
143
+ const values = position.array as Float32Array;
144
+ const e = matrix.elements;
145
+ for (let index = 0; index < position.count; index += 1) {
146
+ const x = values[index * 3] as number;
147
+ const y = values[index * 3 + 1] as number;
148
+ const z = values[index * 3 + 2] as number;
149
+ const w = 1 / (e[3] * x + e[7] * y + e[11] * z + e[15]);
150
+ const out = (vertexAt + index) * 3;
151
+ positions[out] = (e[0] * x + e[4] * y + e[8] * z + e[12]) * w;
152
+ positions[out + 1] = (e[1] * x + e[5] * y + e[9] * z + e[13]) * w;
153
+ positions[out + 2] = (e[2] * x + e[6] * y + e[10] * z + e[14]) * w;
154
+ }
155
+ return;
156
+ }
157
+ const vertex = new Vector3();
158
+ for (let index = 0; index < position.count; index += 1) {
159
+ vertex.fromBufferAttribute(position, index).applyMatrix4(matrix);
160
+ vertex.toArray(positions, (vertexAt + index) * 3);
161
+ }
162
+ }
163
+
164
+ function shadowProxyGeometry(
165
+ meshes: readonly Mesh[],
166
+ label: string,
167
+ chunk: Object3D,
168
+ ): BufferGeometry {
169
+ chunk.updateMatrixWorld(true);
170
+ const toRoot = chunk.matrixWorld.clone().invert();
171
+ const place = new Matrix4();
172
+ const instance = new Matrix4();
173
+ const matrix = new Matrix4();
174
+ let vertices = 0;
175
+ let drawn = 0;
176
+ for (const mesh of meshes) {
177
+ const position = mesh.geometry.getAttribute("position");
178
+ if (position === undefined)
179
+ throw new Error(`Chunk shadow proxy (${label}): a merged mesh carries no position.`);
180
+ const copies = mesh instanceof InstancedMesh ? mesh.count : 1;
181
+ const total = mesh.geometry.getIndex()?.count ?? position.count;
182
+ const start = Math.min(total, Math.max(0, mesh.geometry.drawRange.start));
183
+ vertices += position.count * copies;
184
+ drawn += Math.max(0, Math.min(total, start + mesh.geometry.drawRange.count) - start) * copies;
185
+ }
186
+ const positions = new Float32Array(vertices * 3);
187
+ const indices = new Uint32Array(drawn);
188
+ let vertexAt = 0;
189
+ let indexAt = 0;
190
+ const geometry = new BufferGeometry();
191
+ for (const mesh of meshes) {
192
+ const position = mesh.geometry.getAttribute("position");
193
+ if (position === undefined)
194
+ throw new Error(`Chunk shadow proxy (${label}): a merged mesh carries no position.`);
195
+ const source = mesh.geometry.getIndex();
196
+ const total = source?.count ?? position.count;
197
+ const start = Math.min(total, Math.max(0, mesh.geometry.drawRange.start));
198
+ const end = Math.min(total, start + mesh.geometry.drawRange.count);
199
+ const groupAt = indexAt;
200
+ place.multiplyMatrices(toRoot, mesh.matrixWorld);
201
+ for (let copy = 0; copy < (mesh instanceof InstancedMesh ? mesh.count : 1); copy += 1) {
202
+ if (mesh instanceof InstancedMesh) mesh.getMatrixAt(copy, instance);
203
+ else instance.identity();
204
+ matrix.multiplyMatrices(place, instance);
205
+ placeVertices(position as BufferAttribute, matrix, positions, vertexAt);
206
+ for (let index = start; index < end; index += 1)
207
+ indices[indexAt++] = (source?.getX(index) ?? index) + vertexAt;
208
+ vertexAt += position.count;
209
+ }
210
+ geometry.addGroup(groupAt, indexAt - groupAt);
211
+ }
212
+ geometry.setAttribute("position", new BufferAttribute(positions, 3));
213
+ geometry.setIndex(new BufferAttribute(indices, 1));
214
+ geometry.computeBoundingSphere();
215
+ return geometry;
216
+ }
217
+
218
+ /** Per-level buffers a proxy keeps when the shadow probe publishes no `casterLevelSlots`. */
219
+ const LEVEL_SLOTS_FALLBACK = 3;
220
+
221
+ /** Keep retained sources' visibility, frustum and texel decisions on each level's single draw. */
222
+ function selectChunkShadowParts(proxy: Mesh, sources: readonly Mesh[]): void {
223
+ const caster = proxy as ICasterMesh;
224
+ caster.chunkShadowProxy = true;
225
+ // The source frustums below decide the exact inputs; the union must not veto that decision.
226
+ proxy.frustumCulled = false;
227
+ const geometry = proxy.geometry;
228
+ const complete = ((geometry.getIndex() as BufferAttribute).array as Uint32Array).slice();
229
+ const levels = new Map<Camera, { geometry: BufferGeometry; selected: Uint8Array }>();
230
+ const disposeLevels = (event: { target: unknown }) => {
231
+ const geometries = new Set([geometry]);
232
+ for (const level of levels.values()) geometries.add(level.geometry);
233
+ for (const held of geometries) held.removeEventListener("dispose", disposeLevels);
234
+ for (const held of geometries) if (held !== event.target) held.dispose();
235
+ levels.clear();
236
+ };
237
+ geometry.addEventListener("dispose", disposeLevels);
238
+ const frustum = new Frustum();
239
+ const projection = new Matrix4();
240
+ const sphere = new Sphere();
241
+ proxy.onBeforeRender = function (_renderer, _scene, camera) {
242
+ let level = levels.get(camera);
243
+ if (level === undefined) {
244
+ // One index buffer per level the ladder renders, which the level probe publishes beside the
245
+ // gate it sets on the same pass: the ≤2x level expansion puts five levels behind the default
246
+ // three extents, so a fixed three had the fourth and fifth rewrite a whole index every render.
247
+ if (levels.size === (caster.casterLevelSlots ?? LEVEL_SLOTS_FALLBACK)) {
248
+ // ponytail: one resident buffer per level; a camera past that reuses the oldest slot.
249
+ const oldest = levels.keys().next().value as Camera;
250
+ level = levels.get(oldest) as { geometry: BufferGeometry; selected: Uint8Array };
251
+ levels.delete(oldest);
252
+ level.selected.fill(255);
253
+ } else {
254
+ const perLevel = levels.size === 0 ? geometry : new BufferGeometry();
255
+ if (perLevel !== geometry) {
256
+ perLevel.setAttribute("position", geometry.getAttribute("position"));
257
+ perLevel.setIndex(new BufferAttribute(new Uint32Array(complete.length), 1));
258
+ perLevel.boundingSphere = geometry.boundingSphere;
259
+ perLevel.addEventListener("dispose", disposeLevels);
260
+ }
261
+ level = { geometry: perLevel, selected: new Uint8Array(sources.length).fill(255) };
262
+ }
263
+ levels.set(camera, level);
264
+ }
265
+ // Three fetches the render object after this hook and detects geometry identity changes,
266
+ // even when different cameras share a render object. Exact projection stand-ins use `this`.
267
+ this.geometry = level.geometry;
268
+ const index = level.geometry.getIndex() as BufferAttribute;
269
+ const selected = level.selected;
270
+ frustum.setFromProjectionMatrix(
271
+ projection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse),
272
+ camera.coordinateSystem,
273
+ camera.reversedDepth,
274
+ );
275
+ let changed = false;
276
+ let count = 0;
277
+ for (let part = 0; part < sources.length; part += 1) {
278
+ const source = sources[part] as InstancedMesh;
279
+ if (source.boundingSphere === null) source.computeBoundingSphere();
280
+ sphere.copy(source.boundingSphere as Sphere).applyMatrix4(source.matrixWorld);
281
+ let visible = true;
282
+ for (let node: Object3D | null = source; node !== null; node = node.parent)
283
+ if (!node.visible) visible = false;
284
+ const draws =
285
+ visible &&
286
+ sphere.radius * 2 >= (caster.casterMinDiameter ?? 0) &&
287
+ (!source.frustumCulled || frustum.intersectsObject(source));
288
+ const next = draws ? 1 : 0;
289
+ if (selected[part] !== next) changed = true;
290
+ selected[part] = next;
291
+ if (draws) count += geometry.groups[part]?.count ?? 0;
292
+ }
293
+ if (changed) {
294
+ let at = 0;
295
+ for (let part = 0; part < sources.length; part += 1) {
296
+ const range = geometry.groups[part];
297
+ if (selected[part] !== 1 || range === undefined) continue;
298
+ (index.array as Uint32Array).set(
299
+ complete.subarray(range.start, range.start + range.count),
300
+ at,
301
+ );
302
+ at += range.count;
303
+ }
304
+ index.needsUpdate = true;
305
+ }
306
+ level.geometry.setDrawRange(0, count);
307
+ };
308
+ }
@@ -0,0 +1,315 @@
1
+ /**
2
+ * `HeightfieldCollar`: the far ring a heightfield grows past its playable square, and the band of it
3
+ * a collider follows.
4
+ *
5
+ * A landscape renders its square at full detail and its surroundings at a fraction of it, because
6
+ * the surroundings' triangles are (Unreal `ALandscapeMeshProxyActor`, HLOD). The mechanism is the
7
+ * same everywhere: one vertex per boundary sample, one ring per distance step, and a quad grid
8
+ * between them whose innermost ring is the square's own edge. What a ring is worth in metres, what
9
+ * it looks like and where the ground stops being walkable are the game's decisions, so they arrive
10
+ * as options: `ringDistance` is its framing curve and `height` is its own surface.
11
+ */
12
+ import { BufferAttribute, BufferGeometry } from "three";
13
+
14
+ /** One ring vertex: where it stands and which ring and boundary sample it belongs to. */
15
+ export interface IHeightfieldCollarSite {
16
+ /** Metres past the square's edge along the framing curve. */
17
+ readonly distance: number;
18
+ /** Ring number, 0 at the square's own edge. */
19
+ readonly ring: number;
20
+ /** Index along the perimeter walk, 0 at the ring's own (-x, -z) corner. */
21
+ readonly vertex: number;
22
+ readonly x: number;
23
+ readonly z: number;
24
+ }
25
+
26
+ /** The collar quad a world point falls in, in ring and perimeter indices. */
27
+ export interface IHeightfieldCollarQuad {
28
+ /** Share from `from` to `to` along the perimeter, 0..1. */
29
+ readonly edgeShare: number;
30
+ /** Perimeter index at or before the point. */
31
+ readonly from: number;
32
+ /** The ring inside the point. */
33
+ readonly lower: number;
34
+ /** Share from `lower` to `upper` across the rings, 0..1. */
35
+ readonly ringShare: number;
36
+ /** Perimeter index after `from`. */
37
+ readonly to: number;
38
+ /** The ring outside the point. */
39
+ readonly upper: number;
40
+ }
41
+
42
+ export interface IHeightfieldCollarOptions {
43
+ /** The height at one ring vertex. The game's look: surveyed relief, its smoothing and its seams. */
44
+ readonly height: (site: IHeightfieldCollarSite) => number;
45
+ /** Samples along one side of the square; a ring keeps one vertex per boundary sample. */
46
+ readonly resolution: number;
47
+ /** Metres past the square's edge of one ring. `ringDistance(0)` reads 0 and it never decreases. */
48
+ readonly ringDistance: (ring: number) => number;
49
+ /** Rings past the edge, outermost included. */
50
+ readonly rings: number;
51
+ /** The square's side in metres: the heightfield's own width. */
52
+ readonly size: number;
53
+ /** Metres past the edge that stay walkable: `walk` ends at the outermost ring inside it. */
54
+ readonly walkBand: number;
55
+ }
56
+
57
+ /** The walkable band of the collar, as the drawn triangles themselves. */
58
+ export interface IHeightfieldCollarWalk {
59
+ /** Metres past the edge where the band ends. */
60
+ readonly extent: number;
61
+ /** A view of the collar's own position buffer and index slice, not a resample. */
62
+ readonly geometry: BufferGeometry;
63
+ }
64
+
65
+ function requireFinite(value: number, name: string): void {
66
+ if (!Number.isFinite(value)) throw new Error(`HeightfieldCollar ${name} must be finite.`);
67
+ }
68
+
69
+ function requireShape(options: IHeightfieldCollarOptions): void {
70
+ if (!Number.isInteger(options.resolution) || options.resolution < 2)
71
+ throw new Error("HeightfieldCollar needs at least 2 samples per side.");
72
+ if (!Number.isInteger(options.rings) || options.rings < 1)
73
+ throw new Error("HeightfieldCollar needs at least 1 ring.");
74
+ requireFinite(options.size, "size");
75
+ if (options.size <= 0) throw new Error("HeightfieldCollar size must be positive.");
76
+ requireFinite(options.walkBand, "walkBand");
77
+ if (options.walkBand < 0) throw new Error("HeightfieldCollar walkBand must not be negative.");
78
+ }
79
+
80
+ /** The distance of every ring, checked once: a framing curve that folds cannot locate a point. */
81
+ function ringDistances(options: IHeightfieldCollarOptions): Float64Array {
82
+ const distances = new Float64Array(options.rings + 1);
83
+ for (let ring = 0; ring <= options.rings; ring += 1) {
84
+ const distance = options.ringDistance(ring);
85
+ requireFinite(distance, `ring ${ring} distance`);
86
+ if (ring > 0 && distance < (distances[ring - 1] as number))
87
+ throw new Error(`HeightfieldCollar ring ${ring} distance is closer than the ring inside it.`);
88
+ distances[ring] = distance;
89
+ }
90
+ if (distances[0] !== 0)
91
+ throw new Error("HeightfieldCollar ring 0 stands on the square's own edge and reads 0.");
92
+ return distances;
93
+ }
94
+
95
+ /**
96
+ * The perimeter walk: one boundary sample per step, starting at the square's (-x, -z) corner and
97
+ * following its four sides, so a ring's vertex stands over the edge it grows from.
98
+ */
99
+ function boundaryWalk(segments: number): { columns: Int32Array; rows: Int32Array } {
100
+ const perimeter = segments * 4;
101
+ const starts = [
102
+ [0, 0],
103
+ [segments, 0],
104
+ [segments, segments],
105
+ [0, segments],
106
+ ] as const;
107
+ const steps = [
108
+ [1, 0],
109
+ [0, 1],
110
+ [-1, 0],
111
+ [0, -1],
112
+ ] as const;
113
+ const columns = new Int32Array(perimeter);
114
+ const rows = new Int32Array(perimeter);
115
+ for (let vertex = 0; vertex < perimeter; vertex += 1) {
116
+ const side = Math.floor(vertex / segments);
117
+ const along = vertex % segments;
118
+ const start = starts[side] as readonly [number, number];
119
+ const step = steps[side] as readonly [number, number];
120
+ columns[vertex] = start[0] + along * step[0];
121
+ rows[vertex] = start[1] + along * step[1];
122
+ }
123
+ return { columns, rows };
124
+ }
125
+
126
+ /**
127
+ * A heightfield's far ring: `rings` square rings past its playable square, one vertex per boundary
128
+ * sample, and the index grid that draws them.
129
+ * @situation draw the terrain past the playable square without hand-building a ring grid
130
+ * @situation ground a character past the square, out to the walk band, on drawn triangles
131
+ * @constraint every ring vertex asks the game's `height` callback; core owns no terrain look
132
+ * @constraint the collar is a ring of triangles, not a field: `heightAt` answers on it and null off it
133
+ * @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) });
134
+ */
135
+ export class HeightfieldCollar {
136
+ readonly #columns: Int32Array;
137
+ readonly #half: number;
138
+ readonly #positions: Float32Array;
139
+ readonly #rows: Int32Array;
140
+ /** The radius scale of each ring: 1 at the square's own edge. */
141
+ readonly #scales: Float64Array;
142
+ readonly #segments: number;
143
+
144
+ /** The drawn ring grid: positions, then the index triangles between the rings. */
145
+ readonly geometry: BufferGeometry;
146
+ /** Vertices around one ring. */
147
+ readonly perimeter: number;
148
+ /** Ring count, outermost included. */
149
+ readonly rings: number;
150
+ /** The band a collider follows, and the outermost ring it reaches. */
151
+ readonly walk: IHeightfieldCollarWalk;
152
+ /** Metres past the edge that stay walkable. */
153
+ readonly walkBand: number;
154
+
155
+ constructor(options: IHeightfieldCollarOptions) {
156
+ requireShape(options);
157
+ const { height, rings, size } = options;
158
+ const distances = ringDistances(options);
159
+ this.rings = rings;
160
+ this.walkBand = options.walkBand;
161
+ this.#segments = options.resolution - 1;
162
+ this.perimeter = this.#segments * 4;
163
+ this.#half = size / 2;
164
+ this.#scales = new Float64Array(rings + 1);
165
+ for (let ring = 0; ring <= rings; ring += 1)
166
+ this.#scales[ring] = 1 + (distances[ring] as number) / this.#half;
167
+ const { columns, rows } = boundaryWalk(this.#segments);
168
+ this.#columns = columns;
169
+ this.#rows = rows;
170
+ let walked = 0;
171
+ while (walked < rings && (distances[walked + 1] as number) <= this.walkBand) walked += 1;
172
+ const { positions, indices } = this.#build(distances, height);
173
+ this.#positions = positions;
174
+ const geometry = new BufferGeometry();
175
+ geometry.setAttribute("position", new BufferAttribute(positions, 3));
176
+ geometry.setIndex(new BufferAttribute(indices, 1));
177
+ this.geometry = geometry;
178
+ const band = new BufferGeometry();
179
+ band.setAttribute(
180
+ "position",
181
+ new BufferAttribute(positions.subarray(0, (walked + 1) * this.perimeter * 3), 3),
182
+ );
183
+ band.setIndex(new BufferAttribute(indices.subarray(0, walked * this.perimeter * 6), 1));
184
+ this.walk = { extent: distances[walked] as number, geometry: band };
185
+ }
186
+
187
+ /** The ring grid's positions and triangles, ring by ring. */
188
+ #build(
189
+ distances: Float64Array,
190
+ height: (site: IHeightfieldCollarSite) => number,
191
+ ): { indices: Uint32Array; positions: Float32Array } {
192
+ const { perimeter, rings } = this;
193
+ const size = this.#half * 2;
194
+ const positions = new Float32Array((rings + 1) * perimeter * 3);
195
+ const indices = new Uint32Array(rings * perimeter * 6);
196
+ let offset = 0;
197
+ let index = 0;
198
+ for (let ring = 0; ring <= rings; ring += 1) {
199
+ const scale = this.#scales[ring] as number;
200
+ const distance = distances[ring] as number;
201
+ for (let vertex = 0; vertex < perimeter; vertex += 1) {
202
+ const x = ((this.#columns[vertex] as number) / this.#segments - 0.5) * size * scale;
203
+ const z = ((this.#rows[vertex] as number) / this.#segments - 0.5) * size * scale;
204
+ positions[offset] = x;
205
+ positions[offset + 1] = height({ distance, ring, vertex, x, z });
206
+ positions[offset + 2] = z;
207
+ offset += 3;
208
+ if (ring === rings) continue;
209
+ const a = ring * perimeter + vertex;
210
+ const b = ring * perimeter + ((vertex + 1) % perimeter);
211
+ const c = a + perimeter;
212
+ const d = b + perimeter;
213
+ indices[index] = a;
214
+ indices[index + 1] = b;
215
+ indices[index + 2] = c;
216
+ indices[index + 3] = b;
217
+ indices[index + 4] = d;
218
+ indices[index + 5] = c;
219
+ index += 6;
220
+ }
221
+ }
222
+ return { indices, positions };
223
+ }
224
+
225
+ /**
226
+ * The boundary sample one perimeter vertex stands over: a column and row of the heightfield's own
227
+ * grid, in the walk's order, so the square's edge heights, seams and colours are a lookup.
228
+ */
229
+ boundary(vertex: number): { readonly column: number; readonly row: number } {
230
+ this.#requireVertex(vertex);
231
+ return { column: this.#columns[vertex] as number, row: this.#rows[vertex] as number };
232
+ }
233
+
234
+ /** Metres past the square's edge of one ring. */
235
+ distance(ring: number): number {
236
+ if (!Number.isInteger(ring) || ring < 0 || ring > this.rings)
237
+ throw new Error(`HeightfieldCollar ring ${ring} is outside the collar.`);
238
+ return ((this.#scales[ring] as number) - 1) * this.#half;
239
+ }
240
+
241
+ /**
242
+ * The drawn collar's height under a world point: bilinear across the quad a scatter placement
243
+ * stands on, so a tree follows the ring grid it is planted on. Null where there is no collar.
244
+ */
245
+ heightAt(x: number, z: number): number | null {
246
+ const quad = this.locate(x, z);
247
+ if (quad === undefined) return null;
248
+ const height = (ring: number, vertex: number): number =>
249
+ this.#positions[(ring * this.perimeter + vertex) * 3 + 1] as number;
250
+ const inside =
251
+ height(quad.lower, quad.from) * (1 - quad.edgeShare) +
252
+ height(quad.lower, quad.to) * quad.edgeShare;
253
+ const outside =
254
+ height(quad.upper, quad.from) * (1 - quad.edgeShare) +
255
+ height(quad.upper, quad.to) * quad.edgeShare;
256
+ return inside * (1 - quad.ringShare) + outside * quad.ringShare;
257
+ }
258
+
259
+ /** Vertex index of one ring site, for writing an attribute over the drawn ring grid. */
260
+ index(ring: number, vertex: number): number {
261
+ if (!Number.isInteger(ring) || ring < 0 || ring > this.rings)
262
+ throw new Error(`HeightfieldCollar ring ${ring} is outside the collar.`);
263
+ this.#requireVertex(vertex);
264
+ return ring * this.perimeter + vertex;
265
+ }
266
+
267
+ /**
268
+ * The quad a world point falls in, or undefined inside the square and past the outermost ring.
269
+ * Its four corners are `index(lower|upper, from|to)`.
270
+ */
271
+ locate(x: number, z: number): IHeightfieldCollarQuad | undefined {
272
+ requireFinite(x, "query x");
273
+ requireFinite(z, "query z");
274
+ const scale = Math.max(Math.abs(x), Math.abs(z)) / this.#half;
275
+ if (scale < 1 || scale >= (this.#scales[this.rings] as number)) return undefined;
276
+ let lower = 0;
277
+ let upper = this.rings;
278
+ while (upper - lower > 1) {
279
+ const middle = (lower + upper) >> 1;
280
+ if ((this.#scales[middle] as number) <= scale) lower = middle;
281
+ else upper = middle;
282
+ }
283
+ const ringShare =
284
+ (scale - (this.#scales[lower] as number)) /
285
+ ((this.#scales[upper] as number) - (this.#scales[lower] as number));
286
+ // The point pulled back onto the square's edge, then its index along the perimeter walk.
287
+ const half = this.#half;
288
+ const segments = this.#segments;
289
+ const cell = (half * 2) / segments;
290
+ const edgeX = x / scale;
291
+ const edgeZ = z / scale;
292
+ const along =
293
+ Math.abs(z) >= Math.abs(x)
294
+ ? z < 0
295
+ ? (edgeX + half) / cell
296
+ : 2 * segments + (half - edgeX) / cell
297
+ : x > 0
298
+ ? segments + (edgeZ + half) / cell
299
+ : 3 * segments + (half - edgeZ) / cell;
300
+ const from = Math.min(this.perimeter - 1, Math.max(0, Math.floor(along)));
301
+ return {
302
+ edgeShare: along - from,
303
+ from,
304
+ lower,
305
+ ringShare,
306
+ to: (from + 1) % this.perimeter,
307
+ upper,
308
+ };
309
+ }
310
+
311
+ #requireVertex(vertex: number): void {
312
+ if (!Number.isInteger(vertex) || vertex < 0 || vertex >= this.perimeter)
313
+ throw new Error(`HeightfieldCollar vertex ${vertex} is outside the ring.`);
314
+ }
315
+ }