@threenative/core 0.3.10 → 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 (158) 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 +10565 -22533
  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-camera-cull.ts +32 -1
  84. package/src/render-pass-budget.ts +34 -7
  85. package/src/renderProjection.ts +22 -0
  86. package/src/renderer.ts +92 -37
  87. package/src/snow-field.ts +1 -1
  88. package/src/spells/cast-pool.ts +361 -0
  89. package/src/spells/index.ts +177 -0
  90. package/src/spells/mechanisms.ts +295 -0
  91. package/src/spells/reaction-field.ts +415 -0
  92. package/src/spells/spell-lights.ts +139 -0
  93. package/src/spells/spell-world.ts +187 -0
  94. package/src/spells/spell.ts +397 -0
  95. package/src/spells/spells.ts +283 -0
  96. package/src/spells/ultra/engine/camera.ts +184 -0
  97. package/src/spells/ultra/engine/quality.ts +96 -0
  98. package/src/spells/ultra/index.ts +52 -0
  99. package/src/spells/ultra/main.ts +305 -0
  100. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  101. package/src/spells/ultra/spells/cast.ts +233 -0
  102. package/src/spells/ultra/spells/fire.ts +1267 -0
  103. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  104. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  105. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  106. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  107. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  108. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  109. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  110. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  111. package/src/spells/ultra/vfx/common.ts +1195 -0
  112. package/src/spells/ultra/vfx/noise.ts +441 -0
  113. package/src/startup-readiness.ts +128 -34
  114. package/src/version.ts +1 -1
  115. package/src/warmup.ts +56 -8
  116. package/src/water-surface.ts +9 -3
  117. package/src/world-bundle-safety.ts +401 -0
  118. package/src/world-cell-batches.ts +1216 -0
  119. package/src/world-cell-chunks.ts +1132 -0
  120. package/src/world-cell-data.ts +995 -0
  121. package/src/world-cell-impostors.ts +1449 -0
  122. package/src/world-cell-lod-bias.ts +151 -0
  123. package/src/world-cell-models.ts +1074 -0
  124. package/src/world-cell-options.ts +189 -0
  125. package/src/world-cell-placements.ts +694 -0
  126. package/src/world-cell-prewarm.ts +557 -0
  127. package/src/world-cell-readiness.ts +357 -0
  128. package/src/world-cell-render-bundles.ts +459 -0
  129. package/src/world-cell-render-gpu-dress.ts +714 -0
  130. package/src/world-cell-render-main-cull.ts +484 -0
  131. package/src/world-cell-render-shadow-claims.ts +198 -0
  132. package/src/world-cell-render-util.ts +246 -0
  133. package/src/world-cell-render.ts +1493 -0
  134. package/src/world-cell-residency.ts +745 -0
  135. package/src/world-cells.ts +1318 -10418
  136. package/src/world-chunk-shadow.ts +308 -0
  137. package/src/world-collar.ts +315 -0
  138. package/src/world-gpu-flags.ts +163 -0
  139. package/src/world-gpu-readback.ts +881 -0
  140. package/src/world-gpu-reference.ts +510 -0
  141. package/src/world-gpu-scene.ts +214 -2264
  142. package/src/world-gpu-shadow.ts +190 -0
  143. package/src/world-gpu-types.ts +381 -0
  144. package/src/world-gpu-validation.ts +518 -0
  145. package/src/world-heightfield.ts +802 -0
  146. package/src/world-load-limiter.ts +106 -0
  147. package/src/world-noise.ts +241 -0
  148. package/src/world-package.ts +42 -0
  149. package/src/world-region.ts +1 -1
  150. package/src/world-terrain-splat.ts +365 -149
  151. package/src/world-tile-budget.ts +256 -0
  152. package/src/world-tile-geometry.ts +469 -0
  153. package/src/world-tile-lod.ts +408 -0
  154. package/src/world-tile-observation.ts +566 -0
  155. package/src/world-tile-stitch.ts +166 -0
  156. package/src/world-tiles.ts +170 -1745
  157. package/src/world-water-bodies.ts +359 -0
  158. package/src/world.ts +35 -741
@@ -0,0 +1,256 @@
1
+ /**
2
+ * TerrainTiles' constants, admission byte estimates and the input guards they share. Split out of
3
+ `world-tiles.ts` verbatim (PRD-797), so the estimator can be read and tested without the class.
4
+ */
5
+
6
+ import { type SpanId, addSpan, spanNow, spanRecorder } from "./profiling/Spans.js";
7
+ import type { IHeightfieldWorldPassOptions } from "./world-heightfield.js";
8
+ import type {
9
+ IEdgeSamples,
10
+ IWorldTileCollider,
11
+ IWorldTilesTopologyObservation,
12
+ } from "./world-tiles.js";
13
+ export const MAX_RAW_TOPOLOGY_SAMPLES = 10_000;
14
+ export const LOD_POP_THRESHOLD = 16;
15
+ export const LOD_TRANSITION_FRAMES = 3;
16
+ /** Maximum sampled vertices or quads in one terrain-construction admission unit. */
17
+ export const CONSTRUCTION_CHUNK_SAMPLES = 256;
18
+ /** Tiles per side in a merged super-tile block. Small, because a block is culled as one object. */
19
+ export const TERRAIN_MERGE_BLOCK = 4;
20
+ export const TERRAIN_MERGE_FLAG = "TN_TERRAIN_MERGE";
21
+ export const TERRAIN_TILE_MARKER_MS = 5_000;
22
+
23
+ /**
24
+ * Whether this launch asked for terrain tile merging to be turned off.
25
+ *
26
+ * The merge is on by default, so this only has to hear the three ways every other launch switch is
27
+ * read: a native launch sets the environment variable, a browser asks with the query string, and a
28
+ * test or harness sets the global. Only `0` and `false` count, so a URL that never mentioned the
29
+ * switch — or one that still carries the `=1` that used to ask for the merge — stays on.
30
+ */
31
+ export function terrainMergeOptedOut(): boolean {
32
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
33
+ string,
34
+ unknown
35
+ >;
36
+ const fromEnv = host.process?.env?.[TERRAIN_MERGE_FLAG];
37
+ if (fromEnv === "0" || fromEnv === "false") return true;
38
+ const query = globalThis.location?.search;
39
+ if (typeof query === "string" && /[?&]tnTerrainMerge=(?:0|false)(?:&|$)/u.test(query))
40
+ return true;
41
+ return (
42
+ host.__tnTerrainMerge === false || host.__tnTerrainMerge === 0 || host.__tnTerrainMerge === "0"
43
+ );
44
+ }
45
+
46
+ /** A block's key: its LOD tier and which K×K cell of the tile grid it covers. */
47
+ export function blockKeyFor(lod: number, tileX: number, tileZ: number): string {
48
+ return `${String(lod)}:${String(Math.floor(tileX / TERRAIN_MERGE_BLOCK))},${String(
49
+ Math.floor(tileZ / TERRAIN_MERGE_BLOCK),
50
+ )}`;
51
+ }
52
+
53
+ export function blockCoordinates(key: string): { lod: number; blockX: number; blockZ: number } {
54
+ const separator = key.indexOf(":");
55
+ const comma = key.indexOf(",", separator + 1);
56
+ return {
57
+ lod: Number(key.slice(0, separator)),
58
+ blockX: Number(key.slice(separator + 1, comma)),
59
+ blockZ: Number(key.slice(comma + 1)),
60
+ };
61
+ }
62
+
63
+ export class EmptyCollider implements IWorldTileCollider {
64
+ #disposed = false;
65
+
66
+ get disposed(): boolean {
67
+ return this.#disposed;
68
+ }
69
+
70
+ dispose(): void {
71
+ this.#disposed = true;
72
+ }
73
+ }
74
+
75
+ /**
76
+ * The one throw a hard cap produces, so a caller composing `TerrainTiles` can tell "a tile no longer
77
+ * fits" from a defect in game-owned input by `instanceof` rather than by a name any error can borrow.
78
+ * Not re-exported from `world.ts`: the cap's condition is the caller's to absorb, not to handle.
79
+ */
80
+ export class TerrainTileBudgetError extends Error {
81
+ constructor(message: string) {
82
+ super(message);
83
+ this.name = "TerrainTileBudgetError";
84
+ }
85
+ }
86
+
87
+ export function finite(value: number, name: string): number {
88
+ if (!Number.isFinite(value)) throw new Error(`TerrainTiles ${name} must be finite.`);
89
+ return value;
90
+ }
91
+
92
+ export function positive(value: number, name: string): number {
93
+ finite(value, name);
94
+ if (value <= 0) throw new Error(`TerrainTiles ${name} must be greater than zero.`);
95
+ return value;
96
+ }
97
+
98
+ export function integerAtLeast(value: number, minimum: number, name: string): number {
99
+ if (!Number.isInteger(value) || value < minimum)
100
+ throw new Error(`TerrainTiles ${name} must be an integer of at least ${minimum}.`);
101
+ return value;
102
+ }
103
+
104
+ export function keyFor(tileX: number, tileZ: number): string {
105
+ return `${String(tileX)}:${String(tileZ)}`;
106
+ }
107
+
108
+ export function lodLevelForDistance(distance: number, thresholds: readonly number[]): number {
109
+ let level = 0;
110
+ for (const threshold of thresholds) {
111
+ if (distance < threshold) break;
112
+ level += 1;
113
+ }
114
+ return level;
115
+ }
116
+
117
+ export function resolutionFor(tileResolution: number, factor: number): number {
118
+ const cells = (tileResolution - 1) / factor;
119
+ if (!Number.isInteger(cells))
120
+ throw new Error("TerrainTiles tileResolution minus one must divide every lod factor.");
121
+ return cells + 1;
122
+ }
123
+
124
+ export function morphBytes(resolution: number, targets: number): number {
125
+ const vertices = resolution * resolution + resolution * 4;
126
+ // Stock Three packs both vec3 deltas into RGBA32F: retain its CPU texture and GPU copy too.
127
+ const texels = vertices * 2;
128
+ // Any row width pads to < 2 * texels; admission precedes renderer-limit discovery.
129
+ const packedTexels = texels * 2;
130
+ return targets * (vertices * 3 * 4 * 2 + packedTexels * 4 * 4 * 2);
131
+ }
132
+
133
+ export function estimatedLevelBytes(resolution: number, targets = 0): number {
134
+ const vertices = resolution * resolution + resolution * 4;
135
+ const triangles = (resolution - 1) * (resolution - 1) + (resolution - 1) * 4;
136
+ const edgeSampleBytes = resolution * 4 * Float32Array.BYTES_PER_ELEMENT;
137
+ return (
138
+ vertices * 3 * Float32Array.BYTES_PER_ELEMENT * 2 +
139
+ triangles * 6 * Uint32Array.BYTES_PER_ELEMENT +
140
+ edgeSampleBytes +
141
+ morphBytes(resolution, targets)
142
+ );
143
+ }
144
+
145
+ export function estimatedFieldBytes(
146
+ tileResolution: number,
147
+ worldPasses: IHeightfieldWorldPassOptions | undefined,
148
+ ): number {
149
+ const sampleBytes = tileResolution * tileResolution * Float32Array.BYTES_PER_ELEMENT;
150
+ if (worldPasses === undefined) return sampleBytes * 2;
151
+ // The GPU path retains the canonical/collider values plus several ping-pong storage buffers.
152
+ // Admission is deliberately conservative so backend allocation overhead cannot break the cap.
153
+ return sampleBytes * (worldPasses.gpu === false ? 4 : 24);
154
+ }
155
+
156
+ export function estimatedTileBytes(
157
+ tileResolution: number,
158
+ factors: readonly number[],
159
+ worldPasses: IHeightfieldWorldPassOptions | undefined,
160
+ validate: boolean,
161
+ ): number {
162
+ return factors.reduce(
163
+ (total, factor) =>
164
+ total +
165
+ estimatedLevelBytes(
166
+ resolutionFor(tileResolution, factor),
167
+ validate ? 0 : factors.filter((candidate) => candidate >= factor).length - 1,
168
+ ),
169
+ estimatedFieldBytes(tileResolution, worldPasses),
170
+ );
171
+ }
172
+
173
+ export function tiledObservationResolution(
174
+ extent: number,
175
+ tileSize: number,
176
+ tileResolution: number,
177
+ axis: string,
178
+ ): number {
179
+ const tileCount = extent / tileSize;
180
+ if (!Number.isInteger(tileCount) || tileCount < 1)
181
+ throw new Error(
182
+ `TerrainTiles topologyObservation ${axis} must cover a positive whole number of rendered tiles.`,
183
+ );
184
+ return tileCount * (tileResolution - 1) + 1;
185
+ }
186
+
187
+ export function validateTopologyObservation(
188
+ observation: IWorldTilesTopologyObservation,
189
+ tileSize: number,
190
+ tileResolution: number,
191
+ ): void {
192
+ const expectedColumns = tiledObservationResolution(
193
+ observation.width,
194
+ tileSize,
195
+ tileResolution,
196
+ "width",
197
+ );
198
+ const expectedRows = tiledObservationResolution(
199
+ observation.depth,
200
+ tileSize,
201
+ tileResolution,
202
+ "depth",
203
+ );
204
+ if (observation.columns !== expectedColumns)
205
+ throw new Error(
206
+ `TerrainTiles topologyObservation columns must match the rendered tile grid (expected ${String(expectedColumns)}, received ${String(observation.columns)}).`,
207
+ );
208
+ if (observation.rows !== expectedRows)
209
+ throw new Error(
210
+ `TerrainTiles topologyObservation rows must match the rendered tile grid (expected ${String(expectedRows)}, received ${String(observation.rows)}).`,
211
+ );
212
+ }
213
+
214
+ export function edgeSamplesFor(values: readonly number[], resolution: number): IEdgeSamples {
215
+ const north = new Float32Array(resolution);
216
+ const south = new Float32Array(resolution);
217
+ const west = new Float32Array(resolution);
218
+ const east = new Float32Array(resolution);
219
+ for (let index = 0; index < resolution; index += 1) {
220
+ north[index] = values[index] as number;
221
+ south[index] = values[(resolution - 1) * resolution + index] as number;
222
+ west[index] = values[index * resolution] as number;
223
+ east[index] = values[index * resolution + resolution - 1] as number;
224
+ }
225
+ return { east, north, south, west };
226
+ }
227
+
228
+ /**
229
+ * Apply a job's result, whenever it arrives. An inline host resolves inside the call, so the caller
230
+ * keeps the synchronous shape it always had; a worker host applies in its reply. A reply that throws
231
+ * rejects the promise instead of returning, so a budget overflow off this thread is a loud failure
232
+ * rather than a swallowed one.
233
+ */
234
+ export function settleJob<T>(result: T | Promise<T>, apply: (value: T) => void): void {
235
+ if (result instanceof Promise) result.then(apply);
236
+ else apply(result);
237
+ }
238
+
239
+ /**
240
+ * Runs one unit of main-thread terrain work and charges it to a frame span.
241
+ *
242
+ * Added, not bracketed: a worker host's block swap arrives in a job reply and an inline host's runs
243
+ * inside the same `follow`, so `begin`/`end` at both call sites would nest and count one unit twice.
244
+ * `addSpan` accumulates whatever runs on this thread with no nesting to get wrong, and costs one
245
+ * guarded return when spans are off — no clock read, no allocation. The frame-span table's
246
+ * `TN_FRAME_SPANS` report is where the number surfaces; nothing here decides anything.
247
+ */
248
+ export function timedSpan<T>(id: SpanId, run: () => T): T {
249
+ if (spanRecorder() === undefined) return run();
250
+ const start = spanNow();
251
+ try {
252
+ return run();
253
+ } finally {
254
+ addSpan(id, spanNow() - start);
255
+ }
256
+ }