@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -0,0 +1,370 @@
1
+ export interface IWorldTopologySummaryField {
2
+ readonly columns: number;
3
+ readonly depth: number;
4
+ readonly flow: ArrayLike<number>;
5
+ readonly heights: ArrayLike<number>;
6
+ readonly rows: number;
7
+ readonly width: number;
8
+ }
9
+
10
+ export interface IWorldTopologySummary {
11
+ readonly directionalAnisotropy: number;
12
+ readonly effectiveVertexDensityPerKm2: number;
13
+ readonly maxHortonStrahlerOrder: number;
14
+ readonly median64mRelief: number;
15
+ readonly powerSpectrumSlope: number;
16
+ readonly profileCurvatureExcessKurtosis: number;
17
+ readonly reliefFieldEdge: number;
18
+ readonly slopeTailAbove30Degrees: number;
19
+ }
20
+
21
+ function height(field: IWorldTopologySummaryField, row: number, column: number): number {
22
+ const clampedRow = Math.max(0, Math.min(field.rows - 1, row));
23
+ const clampedColumn = Math.max(0, Math.min(field.columns - 1, column));
24
+ const value = field.heights[clampedRow * field.columns + clampedColumn];
25
+ if (value === undefined || !Number.isFinite(value))
26
+ throw new Error("World topology height sample is missing or not finite.");
27
+ return value;
28
+ }
29
+
30
+ function gradient(
31
+ field: IWorldTopologySummaryField,
32
+ row: number,
33
+ column: number,
34
+ ): [number, number] {
35
+ const dx = field.width / (field.columns - 1);
36
+ const dz = field.depth / (field.rows - 1);
37
+ return [
38
+ (height(field, row, column + 1) - height(field, row, column - 1)) / (2 * dx),
39
+ (height(field, row + 1, column) - height(field, row - 1, column)) / (2 * dz),
40
+ ];
41
+ }
42
+
43
+ function variance(values: readonly number[]): number {
44
+ if (values.length === 0) return 0;
45
+ const mean = values.reduce((total, value) => total + value, 0) / values.length;
46
+ return values.reduce((total, value) => total + (value - mean) ** 2, 0) / values.length;
47
+ }
48
+
49
+ function directionalAnisotropy(field: IWorldTopologySummaryField): number {
50
+ const x: number[] = [];
51
+ const z: number[] = [];
52
+ for (let row = 0; row < field.rows; row += 1) {
53
+ for (let column = 0; column < field.columns; column += 1) {
54
+ const [gradientX, gradientZ] = gradient(field, row, column);
55
+ x.push(gradientX);
56
+ z.push(gradientZ);
57
+ }
58
+ }
59
+ const xVariance = variance(x);
60
+ const zVariance = variance(z);
61
+ if (xVariance === 0 || zVariance === 0) return Number.POSITIVE_INFINITY;
62
+ return Math.abs(Math.log(xVariance / zVariance));
63
+ }
64
+
65
+ function powerSpectrumSlope(field: IWorldTopologySummaryField): number {
66
+ const average: number[] = [];
67
+ for (let column = 0; column < field.columns; column += 1) {
68
+ let total = 0;
69
+ for (let row = 0; row < field.rows; row += 1) total += height(field, row, column);
70
+ average.push(total / field.rows);
71
+ }
72
+ const wavelengths: number[] = [];
73
+ const powers: number[] = [];
74
+ for (let frequency = 1; frequency <= Math.floor(field.columns / 2); frequency += 1) {
75
+ const wavelength = field.width / frequency;
76
+ if (wavelength < 8 || wavelength > 256) continue;
77
+ let real = 0;
78
+ let imaginary = 0;
79
+ for (let index = 0; index < field.columns; index += 1) {
80
+ const angle = (2 * Math.PI * frequency * index) / field.columns;
81
+ real += (average[index] as number) * Math.cos(angle);
82
+ imaginary -= (average[index] as number) * Math.sin(angle);
83
+ }
84
+ const power = real * real + imaginary * imaginary;
85
+ if (power > 0) {
86
+ wavelengths.push(Math.log(wavelength));
87
+ powers.push(Math.log(power));
88
+ }
89
+ }
90
+ if (wavelengths.length < 2) return Number.POSITIVE_INFINITY;
91
+ const meanWavelength =
92
+ wavelengths.reduce((total, value) => total + value, 0) / wavelengths.length;
93
+ const meanPower = powers.reduce((total, value) => total + value, 0) / powers.length;
94
+ let numerator = 0;
95
+ let denominator = 0;
96
+ for (let index = 0; index < wavelengths.length; index += 1) {
97
+ numerator +=
98
+ ((wavelengths[index] as number) - meanWavelength) * ((powers[index] as number) - meanPower);
99
+ denominator += ((wavelengths[index] as number) - meanWavelength) ** 2;
100
+ }
101
+ return denominator === 0 ? Number.POSITIVE_INFINITY : numerator / denominator;
102
+ }
103
+
104
+ function reliefFieldEdge(field: IWorldTopologySummaryField): number {
105
+ let minimum = Number.POSITIVE_INFINITY;
106
+ let maximum = Number.NEGATIVE_INFINITY;
107
+ let edgeTotal = 0;
108
+ let edgeCount = 0;
109
+ for (let row = 0; row < field.rows; row += 1) {
110
+ for (let column = 0; column < field.columns; column += 1) {
111
+ const value = height(field, row, column);
112
+ minimum = Math.min(minimum, value);
113
+ maximum = Math.max(maximum, value);
114
+ if (row === 0 || column === 0 || row === field.rows - 1 || column === field.columns - 1) {
115
+ edgeTotal += value;
116
+ edgeCount += 1;
117
+ }
118
+ }
119
+ }
120
+ const relief = maximum - minimum;
121
+ if (relief === 0) return 0;
122
+ const edgeMean = edgeTotal / edgeCount;
123
+ const center = height(field, Math.floor(field.rows / 2), Math.floor(field.columns / 2));
124
+ return Math.abs(center - edgeMean) / relief;
125
+ }
126
+
127
+ function slidingExtrema(
128
+ read: (index: number) => number,
129
+ length: number,
130
+ radius: number,
131
+ write: (index: number, minimum: number, maximum: number) => void,
132
+ ): void {
133
+ const minimumDeque: number[] = [];
134
+ const maximumDeque: number[] = [];
135
+ let minimumHead = 0;
136
+ let maximumHead = 0;
137
+ let right = -1;
138
+ for (let index = 0; index < length; index += 1) {
139
+ const desiredRight = Math.min(length - 1, index + radius);
140
+ while (right < desiredRight) {
141
+ right += 1;
142
+ const value = read(right);
143
+ while (
144
+ minimumDeque.length > minimumHead &&
145
+ read(minimumDeque[minimumDeque.length - 1] as number) >= value
146
+ )
147
+ minimumDeque.pop();
148
+ minimumDeque.push(right);
149
+ while (
150
+ maximumDeque.length > maximumHead &&
151
+ read(maximumDeque[maximumDeque.length - 1] as number) <= value
152
+ )
153
+ maximumDeque.pop();
154
+ maximumDeque.push(right);
155
+ }
156
+ const left = Math.max(0, index - radius);
157
+ while (minimumHead < minimumDeque.length && (minimumDeque[minimumHead] as number) < left)
158
+ minimumHead += 1;
159
+ while (maximumHead < maximumDeque.length && (maximumDeque[maximumHead] as number) < left)
160
+ maximumHead += 1;
161
+ const minimumIndex = minimumDeque[minimumHead];
162
+ const maximumIndex = maximumDeque[maximumHead];
163
+ if (minimumIndex === undefined || maximumIndex === undefined)
164
+ throw new Error("World topology sliding window is empty.");
165
+ write(index, read(minimumIndex), read(maximumIndex));
166
+ if (minimumHead > 64 && minimumHead * 2 > minimumDeque.length) {
167
+ minimumDeque.splice(0, minimumHead);
168
+ minimumHead = 0;
169
+ }
170
+ if (maximumHead > 64 && maximumHead * 2 > maximumDeque.length) {
171
+ maximumDeque.splice(0, maximumHead);
172
+ maximumHead = 0;
173
+ }
174
+ }
175
+ }
176
+
177
+ function median64mRelief(field: IWorldTopologySummaryField): number {
178
+ let minimum = Number.POSITIVE_INFINITY;
179
+ let maximum = Number.NEGATIVE_INFINITY;
180
+ for (let index = 0; index < field.heights.length; index += 1) {
181
+ const value = field.heights[index];
182
+ if (value === undefined || !Number.isFinite(value))
183
+ throw new Error("World topology height sample is missing or not finite.");
184
+ minimum = Math.min(minimum, value);
185
+ maximum = Math.max(maximum, value);
186
+ }
187
+ const globalRelief = maximum - minimum;
188
+ if (globalRelief === 0) return 0;
189
+ const radiusX = Math.max(1, Math.round(64 / (field.width / (field.columns - 1))));
190
+ const radiusZ = Math.max(1, Math.round(64 / (field.depth / (field.rows - 1))));
191
+ const local: number[] = [];
192
+ const horizontalMinimum = new Float64Array(field.rows * field.columns);
193
+ const horizontalMaximum = new Float64Array(field.rows * field.columns);
194
+ for (let row = 0; row < field.rows; row += 1)
195
+ slidingExtrema(
196
+ (column) => height(field, row, column),
197
+ field.columns,
198
+ radiusX,
199
+ (column, lineMinimum, lineMaximum) => {
200
+ horizontalMinimum[row * field.columns + column] = lineMinimum;
201
+ horizontalMaximum[row * field.columns + column] = lineMaximum;
202
+ },
203
+ );
204
+ for (let column = 0; column < field.columns; column += 1) {
205
+ const localMinimum = new Float64Array(field.rows);
206
+ const localMaximum = new Float64Array(field.rows);
207
+ slidingExtrema(
208
+ (row) => horizontalMinimum[row * field.columns + column] as number,
209
+ field.rows,
210
+ radiusZ,
211
+ (row, lineMinimum) => {
212
+ localMinimum[row] = lineMinimum;
213
+ },
214
+ );
215
+ slidingExtrema(
216
+ (row) => horizontalMaximum[row * field.columns + column] as number,
217
+ field.rows,
218
+ radiusZ,
219
+ (row, _lineMinimum, lineMaximum) => {
220
+ localMaximum[row] = lineMaximum;
221
+ },
222
+ );
223
+ for (let row = 0; row < field.rows; row += 1)
224
+ local.push(((localMaximum[row] as number) - (localMinimum[row] as number)) / globalRelief);
225
+ }
226
+ local.sort((a, b) => a - b);
227
+ return local[Math.floor(local.length / 2)] as number;
228
+ }
229
+
230
+ function downhill(field: IWorldTopologySummaryField, index: number): number {
231
+ const row = Math.floor(index / field.columns);
232
+ const column = index % field.columns;
233
+ const current = height(field, row, column);
234
+ let destination = index;
235
+ let lowest = current;
236
+ for (const [rowOffset, columnOffset] of [
237
+ [-1, 0],
238
+ [1, 0],
239
+ [0, -1],
240
+ [0, 1],
241
+ ] as const) {
242
+ const nextRow = row + rowOffset;
243
+ const nextColumn = column + columnOffset;
244
+ if (nextRow < 0 || nextRow >= field.rows || nextColumn < 0 || nextColumn >= field.columns)
245
+ continue;
246
+ const candidate = height(field, nextRow, nextColumn);
247
+ if (candidate < lowest) {
248
+ lowest = candidate;
249
+ destination = nextRow * field.columns + nextColumn;
250
+ }
251
+ }
252
+ return destination;
253
+ }
254
+
255
+ function streamOrder(field: IWorldTopologySummaryField): number {
256
+ const count = field.rows * field.columns;
257
+ const targets = new Int32Array(count);
258
+ targets.fill(-1);
259
+ const order = Array.from({ length: count }, (_, index) => index).sort(
260
+ (a, b) =>
261
+ height(field, Math.floor(b / field.columns), b % field.columns) -
262
+ height(field, Math.floor(a / field.columns), a % field.columns) || a - b,
263
+ );
264
+ for (let source = 0; source < count; source += 1) {
265
+ const destination = downhill(field, source);
266
+ targets[source] = destination === source ? -1 : destination;
267
+ }
268
+ const accumulation = new Float64Array(count);
269
+ for (const source of order) {
270
+ accumulation[source] = (accumulation[source] as number) + 1;
271
+ const destination = targets[source];
272
+ if (destination !== undefined && destination >= 0)
273
+ accumulation[destination] =
274
+ (accumulation[destination] as number) + (accumulation[source] as number);
275
+ }
276
+ const cellArea = (field.width / (field.columns - 1)) * (field.depth / (field.rows - 1));
277
+ const minimumFlow = Math.log1p(2_048 / cellArea) / Math.log1p(count);
278
+ const orders = new Int32Array(count);
279
+ let maximum = 0;
280
+ for (const index of order) {
281
+ if ((field.flow[index] as number) < minimumFlow) continue;
282
+ const row = Math.floor(index / field.columns);
283
+ const column = index % field.columns;
284
+ const upstream: number[] = [];
285
+ for (const [rowOffset, columnOffset] of [
286
+ [-1, 0],
287
+ [1, 0],
288
+ [0, -1],
289
+ [0, 1],
290
+ ] as const) {
291
+ const upstreamRow = row + rowOffset;
292
+ const upstreamColumn = column + columnOffset;
293
+ if (
294
+ upstreamRow < 0 ||
295
+ upstreamRow >= field.rows ||
296
+ upstreamColumn < 0 ||
297
+ upstreamColumn >= field.columns
298
+ )
299
+ continue;
300
+ const candidate = upstreamRow * field.columns + upstreamColumn;
301
+ if (targets[candidate] === index && (field.flow[candidate] as number) >= minimumFlow)
302
+ upstream.push(orders[candidate] as number);
303
+ }
304
+ const highest = Math.max(1, ...upstream);
305
+ const ties = upstream.filter((value) => value === highest).length;
306
+ orders[index] = ties > 1 ? highest + 1 : highest;
307
+ maximum = Math.max(maximum, orders[index] as number);
308
+ }
309
+ return maximum;
310
+ }
311
+
312
+ function curvatureExcessKurtosis(field: IWorldTopologySummaryField): number {
313
+ const values: number[] = [];
314
+ for (let row = 0; row < field.rows; row += 1) {
315
+ for (let column = 0; column < field.columns; column += 1) {
316
+ const center = height(field, row, column);
317
+ values.push(
318
+ height(field, row, column - 1) +
319
+ height(field, row, column + 1) +
320
+ height(field, row - 1, column) +
321
+ height(field, row + 1, column) -
322
+ 4 * center,
323
+ );
324
+ }
325
+ }
326
+ const mean = values.reduce((total, value) => total + value, 0) / values.length;
327
+ const second = values.reduce((total, value) => total + (value - mean) ** 2, 0) / values.length;
328
+ if (second === 0) return Number.NEGATIVE_INFINITY;
329
+ const fourth = values.reduce((total, value) => total + (value - mean) ** 4, 0) / values.length;
330
+ return fourth / (second * second) - 3;
331
+ }
332
+
333
+ function slopeTail(field: IWorldTopologySummaryField): number {
334
+ let steep = 0;
335
+ for (let row = 0; row < field.rows; row += 1) {
336
+ for (let column = 0; column < field.columns; column += 1) {
337
+ const [x, z] = gradient(field, row, column);
338
+ if (Math.atan(Math.hypot(x, z)) > Math.PI / 6) steep += 1;
339
+ }
340
+ }
341
+ return steep / (field.rows * field.columns);
342
+ }
343
+
344
+ /** Summarize an exact game-owned field before sending the result over a bounded bridge. */
345
+ export function summarizeWorldTopology(field: IWorldTopologySummaryField): IWorldTopologySummary {
346
+ if (!Number.isInteger(field.rows) || field.rows < 2)
347
+ throw new Error("World topology rows must be integers of at least 2.");
348
+ if (!Number.isInteger(field.columns) || field.columns < 2)
349
+ throw new Error("World topology columns must be integers of at least 2.");
350
+ if (field.heights.length !== field.rows * field.columns)
351
+ throw new Error("World topology heights must contain rows times columns samples.");
352
+ if (field.flow.length !== field.rows * field.columns)
353
+ throw new Error("World topology flow must contain rows times columns samples.");
354
+ for (let index = 0; index < field.flow.length; index += 1) {
355
+ const value = field.flow[index];
356
+ if (value === undefined || !Number.isFinite(value) || value < 0 || value > 1)
357
+ throw new Error("World topology flow samples must be finite values from 0 through 1.");
358
+ }
359
+ return {
360
+ directionalAnisotropy: directionalAnisotropy(field),
361
+ effectiveVertexDensityPerKm2:
362
+ (field.rows * field.columns * 1_000_000) / (field.width * field.depth),
363
+ maxHortonStrahlerOrder: streamOrder(field),
364
+ median64mRelief: median64mRelief(field),
365
+ powerSpectrumSlope: powerSpectrumSlope(field),
366
+ profileCurvatureExcessKurtosis: curvatureExcessKurtosis(field),
367
+ reliefFieldEdge: reliefFieldEdge(field),
368
+ slopeTailAbove30Degrees: slopeTail(field),
369
+ };
370
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The oracle for terrain geometry that is otherwise trusted every frame.
3
+ *
4
+ * `TerrainTiles` re-derives what it already knows — every rendered vertex checked for finiteness,
5
+ * every resident seam re-measured, every LOD blend's visible displacement sampled — and that is a
6
+ * measurement, not a mechanism: on a 289-tile ring a six-second walk paid ~270 ms in three loops
7
+ * that only throw when something is already broken. So it is off by default and the shipped frame
8
+ * trusts the cheap change detector instead, which compares buffer versions and the residency and
9
+ * LOD state the class writes itself.
10
+ *
11
+ * `TN_TERRAIN_VALIDATE=1`, `?tnTerrainValidate=1`, or `validate: true` on the constructor puts the
12
+ * loops back and every assertion with them. It is a validation mode, not a proof: it proves the
13
+ * frames it ran on.
14
+ */
15
+
16
+ /** Marker printed when terrain validation is on, so a log says which mode produced it. */
17
+ export const TERRAIN_VALIDATE_MARKER = "TN_TERRAIN_VALIDATE";
18
+
19
+ /** The launch flag. */
20
+ export const TERRAIN_VALIDATE_FLAG = "TN_TERRAIN_VALIDATE";
21
+
22
+ /**
23
+ * Whether `TN_TERRAIN_VALIDATE` asks for terrain validation on this launch.
24
+ *
25
+ * @situation turn terrain's per-frame seam, LOD pop and vertex checks on for one run
26
+ * @situation assert the terrain geometry a game streams before it ships
27
+ * @constraint off by default: it is the work it checks, every frame
28
+ * @example // Reads its own the way `renderListValidationRequested` does: a native launch sets the
29
+ * // environment variable, a browser asks with the query string, a test or harness sets the
30
+ * // global. `0` and `false` are off, so a saved URL that enabled it still says "off".
31
+ * const tiles = new TerrainTiles({ ...options, validate: terrainValidationRequested() });
32
+ */
33
+ export function terrainValidationRequested(): boolean {
34
+ const host = globalThis as {
35
+ process?: { env?: Record<string, unknown> };
36
+ __tnTerrainValidate?: unknown;
37
+ };
38
+ const fromEnv = host.process?.env?.[TERRAIN_VALIDATE_FLAG];
39
+ if (typeof fromEnv === "string" && fromEnv !== "" && fromEnv !== "0" && fromEnv !== "false")
40
+ return true;
41
+ const query = globalThis.location?.search;
42
+ if (
43
+ typeof query === "string" &&
44
+ /[?&]tnTerrainValidate=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(query)
45
+ )
46
+ return true;
47
+ return host.__tnTerrainValidate === true || host.__tnTerrainValidate === "1";
48
+ }