@threenative/core 0.3.11 → 0.3.13

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 (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -5,7 +5,9 @@ import {
5
5
  LinearFilter,
6
6
  LinearMipmapLinearFilter,
7
7
  type Material,
8
+ Mesh,
8
9
  NoColorSpace,
10
+ type Object3D,
9
11
  RGBAFormat,
10
12
  RepeatWrapping,
11
13
  type Texture,
@@ -31,7 +33,7 @@ import {
31
33
  } from "three/tsl";
32
34
  import type { Node } from "three/webgpu";
33
35
  import { MeshStandardNodeMaterial } from "three/webgpu";
34
- import type { IAssetLoader } from "./assets.js";
36
+ import { type IAssetLoader, fetchAsset } from "./assets.js";
35
37
  import type { IRendererLike } from "./renderer.js";
36
38
  import type { IWorldExtent } from "./world-package.js";
37
39
 
@@ -46,6 +48,14 @@ export interface ITerrainSplatLayer {
46
48
  readonly id: string;
47
49
  readonly tile: number;
48
50
  readonly tint: readonly [number, number, number];
51
+ /** Package-relative image paths; omitted entries retain `<textures>/<id>_<kind>.jpg`.
52
+ * Normal, ORM and height maps are still loaded only when their flags request them. */
53
+ readonly maps?: {
54
+ readonly diffuse?: string;
55
+ readonly normal?: string;
56
+ readonly orm?: string;
57
+ readonly height?: string;
58
+ };
49
59
  readonly normal?: boolean;
50
60
  /** `<id>_orm.jpg`: occlusion in r, roughness in g, metalness in b, read as linear data. */
51
61
  readonly orm?: boolean;
@@ -116,13 +126,48 @@ export interface ITerrainSplatWeightContext {
116
126
  readonly index: number;
117
127
  }
118
128
 
129
+ /** Loaded images for one game-authored sample; index 0 is the base, then table.layers in order.
130
+ * The loader owns these images until the returned material is disposed; do not dispose them. */
131
+ export interface ITerrainSplatSampleContext {
132
+ readonly layer: ITerrainSplatLayer;
133
+ readonly index: number;
134
+ readonly diffuse: Texture;
135
+ readonly normal: Texture | undefined;
136
+ readonly orm: Texture | undefined;
137
+ readonly height: Texture | undefined;
138
+ }
139
+
140
+ /** A game's projected layer. An absent normal leaves the accumulated normal unchanged.
141
+ * Normals are encoded OpenGL for the default factory; a custom factory owns their encoding.
142
+ * An absent ORM uses the layer's existing map or scalar response. */
143
+ export interface ITerrainSplatSample {
144
+ readonly color: Node<"vec3">;
145
+ readonly normal?: Node<"vec3">;
146
+ readonly orm?: Node<"vec3">;
147
+ }
148
+
149
+ /** Engine-blended channels; color includes the table's macro variation. */
150
+ export interface ITerrainSplatMaterialContext {
151
+ readonly color: Node<"vec3">;
152
+ readonly normal: Node<"vec3">;
153
+ readonly orm: Node<"vec3">;
154
+ }
155
+
119
156
  export interface ILoadTerrainSplatOptions {
120
157
  readonly assets: IAssetLoader;
158
+ /** Game-authored appearance. The baked splat mask descriptor and texture folder remain in the package. */
159
+ readonly table?: Pick<ITerrainSplatTable, "base" | "breakup" | "macro" | "layers">;
121
160
  /**
122
161
  * The live renderer. Uncompressed layers stack into one array texture per set through GPU copies,
123
162
  * which need one; without it every layer keeps its own sampler and the marker says so.
124
163
  */
125
164
  readonly renderer?: IRendererLike;
165
+ /** Precomputed for every layer before layerWeight runs; replaces the package's projection.
166
+ * Custom sampling retains the loaded images and skips texture-array stacking. */
167
+ readonly layerSample?: (context: ITerrainSplatSampleContext) => ITerrainSplatSample;
168
+ /** Replaces final material assembly, retaining the engine's ordered channel blend.
169
+ * Loader-owned textures are released with the returned material, including composition errors. */
170
+ readonly materialFactory?: (context: ITerrainSplatMaterialContext) => Material;
126
171
  /**
127
172
  * Replaces each layer's blend weight, given the mask's own (remapped, 0..1) and the layer's
128
173
  * height sample. The game owns the curve, for example a height blend; the package mixes colour,
@@ -165,12 +210,35 @@ function packageDir(url: string): string {
165
210
  return slash === -1 ? "" : url.slice(0, slash + 1);
166
211
  }
167
212
 
213
+ function packageAssetPath(directory: string, path: string): string {
214
+ const joined = `${directory}${path}`;
215
+ // The host may be empty: a `file:///` package keeps its triple slash.
216
+ const prefix = /^(?:(?:[a-z][a-z\d+.-]*:)?\/\/[^/]*\/|\/)?/iu.exec(joined)?.[0] ?? "";
217
+ const segments: string[] = [];
218
+ for (const segment of joined.slice(prefix.length).split("/")) {
219
+ if (segment === "" || segment === ".") continue;
220
+ if (segment === "..") {
221
+ if (segments.length === 0)
222
+ throw new Error(`loadTerrainSplat: map path '${path}' escapes the package asset root.`);
223
+ segments.pop();
224
+ } else {
225
+ segments.push(segment);
226
+ }
227
+ }
228
+ return `${prefix}${segments.join("/")}`;
229
+ }
230
+
168
231
  async function fetchResolved(assets: IAssetLoader, path: string): Promise<Response> {
169
- for (const candidate of await assets.resolve(path)) {
170
- const response = await fetch(candidate);
171
- if (response.ok) return response;
232
+ try {
233
+ return await fetchAsset(assets, path);
234
+ } catch (error) {
235
+ // The native fetch error, when every candidate rejected, stays the cause a caller reads.
236
+ const cause = error instanceof Error ? error.cause : undefined;
237
+ throw new Error(
238
+ `loadTerrainSplat: '${path}' is not served.`,
239
+ cause === undefined ? undefined : { cause },
240
+ );
172
241
  }
173
- throw new Error(`loadTerrainSplat: '${path}' is not served.`);
174
242
  }
175
243
 
176
244
  /** Every splat plane in one array texture: one sampler, whatever the plane count. */
@@ -225,13 +293,22 @@ function stackUncompressed(
225
293
  return undefined;
226
294
  const size = gpuSize(maps[0] as Texture);
227
295
  if (size === undefined) return undefined;
296
+ const first = maps[0] as Texture;
297
+ // A copy needs copy-compatible formats: a layer a dev server already cooked to a compressed
298
+ // codec cannot land in an uncompressed array, and WebGPU rejects the whole command buffer.
228
299
  const sameSize = maps.every((map) => {
229
300
  const other = gpuSize(map);
230
- return other !== undefined && other.width === size.width && other.height === size.height;
301
+ return (
302
+ other !== undefined &&
303
+ other.width === size.width &&
304
+ other.height === size.height &&
305
+ (map as CompressedTexture).isCompressedTexture !== true &&
306
+ map.format === first.format &&
307
+ map.type === first.type
308
+ );
231
309
  });
232
310
  if (!sameSize) return undefined;
233
311
 
234
- const first = maps[0] as Texture;
235
312
  const array = new DataArrayTexture(
236
313
  new Uint8Array(size.width * size.height * 4 * maps.length),
237
314
  size.width,
@@ -349,7 +426,7 @@ export function stackLayers(
349
426
  * @situation the game's terrain should match the DCC's terrain material without a second copy
350
427
  * @constraint the package's world.json must carry `terrain.layers.table` and `terrain.layers.splat`, written by `export_terrain_layers` in the `export_world.py` recipe
351
428
  * @constraint WebGPU allows 16 sampled textures per stage: same-size layers stack into one array texture per set, and `TN_TERRAIN_SPLAT samplers=<n>` reports what is left
352
- * @override every value comes from the package's table; the returned material is the game's to adjust
429
+ * @override `table` may replace `base`, `breakup`, `macro` and `layers` from game source; baked `splat` and `textures` stay package-owned
353
430
  * @example
354
431
  * const surface = await loadTerrainSplat({ assets: ctx.assets, renderer: ctx.renderer, url: "world/world.json" });
355
432
  * const world = await WorldCells.load({ assets: ctx.assets, url: "world/world.json", surface, follow, ring: 2 });
@@ -363,9 +440,13 @@ export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promi
363
440
  "loadTerrainSplat: world.json has no terrain.layers.table/splat; export them with the export_world.py recipe.",
364
441
  );
365
442
  const dir = packageDir(url);
366
- const table = (await (
443
+ const bakedTable = (await (
367
444
  await fetchResolved(assets, dir + layerPaths.table)
368
445
  ).json()) as ITerrainSplatTable;
446
+ const table: ITerrainSplatTable =
447
+ options.table === undefined
448
+ ? bakedTable
449
+ : { ...options.table, splat: bakedTable.splat, textures: bakedTable.textures };
369
450
  const bytes = new Uint8Array(
370
451
  await (await fetchResolved(assets, dir + layerPaths.splat)).arrayBuffer(),
371
452
  );
@@ -400,165 +481,292 @@ export async function loadTerrainSplat(options: ILoadTerrainSplatOptions): Promi
400
481
  `TN_TERRAIN_SPLAT: ${unstated.join(", ")} states no orm map and no roughness/metalness, so they answer light as roughness ${String(DEFAULT_ROUGHNESS)} and metalness 0; re-export the package to author them.`,
401
482
  );
402
483
 
484
+ const owned =
485
+ options.layerSample !== undefined || options.materialFactory !== undefined
486
+ ? new Set<Texture>([splat])
487
+ : undefined;
488
+ let released = false;
489
+ const release = () => {
490
+ if (released) return;
491
+ released = true;
492
+ for (const map of owned ?? []) map.dispose();
493
+ };
494
+
403
495
  const load = async (
404
496
  layer: ITerrainSplatLayer,
405
497
  kind: "diff" | "nrm" | "orm" | "h",
406
498
  ): Promise<Texture> => {
407
- const map = await assets.texture(`${dir}${table.textures}/${layer.id}_${kind}.jpg`, {
408
- data: kind !== "diff",
409
- });
499
+ if (
500
+ layer.maps !== undefined &&
501
+ (layer.maps === null || typeof layer.maps !== "object" || Array.isArray(layer.maps))
502
+ )
503
+ throw new Error(`loadTerrainSplat: layer '${layer.id}' maps needs a path object.`);
504
+ const paths = {
505
+ diff: layer.maps?.diffuse,
506
+ nrm: layer.maps?.normal,
507
+ orm: layer.maps?.orm,
508
+ h: layer.maps?.height,
509
+ };
510
+ const explicitPath = paths[kind];
511
+ if (
512
+ explicitPath !== undefined &&
513
+ (typeof explicitPath !== "string" ||
514
+ explicitPath.trim() === "" ||
515
+ /^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(explicitPath))
516
+ )
517
+ throw new Error(
518
+ `loadTerrainSplat: layer '${layer.id}' ${kind} map needs a package-relative path.`,
519
+ );
520
+ const path =
521
+ explicitPath === undefined ? `${table.textures}/${layer.id}_${kind}.jpg` : explicitPath;
522
+ const map = await assets.texture(packageAssetPath(dir, path), { data: kind !== "diff" });
410
523
  map.wrapS = RepeatWrapping;
411
524
  map.wrapT = RepeatWrapping;
412
525
  map.anisotropy = 8;
413
526
  map.needsUpdate = true;
527
+ if (released && owned?.has(map) === false) map.dispose();
528
+ owned?.add(map);
414
529
  return map;
415
530
  };
416
- const withNormals = all.filter((layer) => layer.normal === true);
417
- const withOrm = all.filter((layer) => layer.orm === true);
418
- const diffuseMaps = await Promise.all(all.map((layer) => load(layer, "diff")));
419
- const normalMaps = await Promise.all(withNormals.map((layer) => load(layer, "nrm")));
420
- const ormMaps = await Promise.all(withOrm.map((layer) => load(layer, "orm")));
421
- const withHeight = table.layers.filter((layer) => layer.height === true);
422
- const heightMaps = await Promise.all(withHeight.map((layer) => load(layer, "h")));
423
-
424
- // One sampler per set when the layers stack; separate textures (and a warning) when they do not.
425
- let samplers = 1;
426
- let stackedSets = 0;
427
- const sampler = (
428
- maps: readonly Texture[],
429
- what: string,
430
- ): ((layer: number, uv: Node<"vec2">) => Node<"vec3">) => {
431
- const stacked = stackLayers(maps, options.renderer);
432
- if (stacked !== undefined) {
433
- samplers += 1;
434
- stackedSets += 1;
435
- return (layer, uv) => texture(stacked, uv).depth(int(layer)).rgb;
436
- }
437
- samplers += maps.length;
438
- if (maps.length > 1)
439
- console.warn(
440
- `TN_TERRAIN_SPLAT: ${what} layers could not stack into one array (mixed format or size, or no renderer to copy them with); they bind ${String(maps.length)} samplers, and WebGPU guarantees 16 a stage.`,
441
- );
442
- return (layer, uv) => texture(maps[layer] as Texture, uv).rgb;
443
- };
444
- const diffuseAt = sampler(diffuseMaps, "albedo");
445
- const normalAt = withNormals.length === 0 ? undefined : sampler(normalMaps, "normal");
446
- const ormAt = withOrm.length === 0 ? undefined : sampler(ormMaps, "ORM");
447
- const heightAt = withHeight.length === 0 ? undefined : sampler(heightMaps, "height");
448
-
449
- const ground = vec2(positionWorld.x, positionWorld.z.negate());
450
- const maskOf = (layer: ITerrainSplatMaskedLayer): Node<"float"> => {
451
- const where = table.splat.masks[layer.mask];
452
- if (where === undefined) throw new Error(`loadTerrainSplat: unknown mask '${layer.mask}'.`);
453
- const source = planes[where[0]];
454
- if (source === undefined)
455
- throw new Error(`loadTerrainSplat: mask '${layer.mask}' names a missing plane.`);
456
- return source[where[1] === "rgb" ? layer.channel : where[1]];
457
- };
458
- const breakup = mx_noise_float(vec3(ground.mul(table.breakup.scale), 0))
459
- .mul(0.5)
460
- .add(0.5);
461
- const push = breakup.mul(2 * table.breakup.push).sub(table.breakup.push);
462
-
463
- // Box projection for cliffs: three axis-aligned samples blended by the surface normal.
464
- const triplanar = (at: (uv: Node<"vec2">) => Node<"vec3">, tile: number): Node<"vec3"> => {
465
- const weights = normalWorld.abs();
466
- const w = weights.div(weights.x.add(weights.y).add(weights.z));
467
- const p = positionWorld.div(tile);
468
- return at(p.zy).mul(w.x).add(at(p.xz).mul(w.y)).add(at(p.xy).mul(w.z));
469
- };
531
+ try {
532
+ const withNormals = all.filter((layer) => layer.normal === true);
533
+ const withOrm = all.filter((layer) => layer.orm === true);
534
+ const diffuseMaps = await Promise.all(all.map((layer) => load(layer, "diff")));
535
+ const normalMaps = await Promise.all(withNormals.map((layer) => load(layer, "nrm")));
536
+ const ormMaps = await Promise.all(withOrm.map((layer) => load(layer, "orm")));
537
+ const withHeight = table.layers.filter((layer) => layer.height === true);
538
+ const heightMaps = await Promise.all(withHeight.map((layer) => load(layer, "h")));
539
+
540
+ // One sampler per set when the layers stack; separate textures (and a warning) when they do not.
541
+ let samplers = 1;
542
+ let stackedSets = 0;
543
+ const sampler = (
544
+ maps: readonly Texture[],
545
+ what: string,
546
+ ): ((layer: number, uv: Node<"vec2">) => Node<"vec3">) => {
547
+ if (options.layerSample !== undefined) {
548
+ samplers += maps.length;
549
+ return (layer, uv) => texture(maps[layer] as Texture, uv).rgb;
550
+ }
551
+ const stacked = stackLayers(maps, options.renderer);
552
+ if (stacked !== undefined) {
553
+ samplers += 1;
554
+ stackedSets += 1;
555
+ for (const map of maps) owned?.delete(map);
556
+ owned?.add(stacked);
557
+ return (layer, uv) => texture(stacked, uv).depth(int(layer)).rgb;
558
+ }
559
+ samplers += maps.length;
560
+ if (maps.length > 1)
561
+ console.warn(
562
+ `TN_TERRAIN_SPLAT: ${what} layers could not stack into one array (mixed format or size, or no renderer to copy them with); they bind ${String(maps.length)} samplers, and WebGPU guarantees 16 a stage.`,
563
+ );
564
+ return (layer, uv) => texture(maps[layer] as Texture, uv).rgb;
565
+ };
566
+ const diffuseAt = sampler(diffuseMaps, "albedo");
567
+ const normalAt = withNormals.length === 0 ? undefined : sampler(normalMaps, "normal");
568
+ const ormAt = withOrm.length === 0 ? undefined : sampler(ormMaps, "ORM");
569
+ const heightAt = withHeight.length === 0 ? undefined : sampler(heightMaps, "height");
470
570
 
471
- const albedo = (layer: ITerrainSplatLayer, index: number): Node<"vec3"> => {
472
- let sample: Node<"vec3"> =
473
- layer.triplanar === true
474
- ? triplanar((uv) => diffuseAt(index, uv), layer.tile)
475
- : diffuseAt(index, ground.div(layer.tile));
476
- const far = layer.far;
477
- if (far !== undefined && layer.triplanar !== true) {
478
- if (!(far.tile > 0 && far.from < far.to && far.amount >= 0 && far.amount <= 1))
571
+ const ground = vec2(positionWorld.x, positionWorld.z.negate());
572
+ const maskOf = (layer: ITerrainSplatMaskedLayer): Node<"float"> => {
573
+ const where = table.splat.masks[layer.mask];
574
+ if (where === undefined)
479
575
  throw new Error(
480
- `loadTerrainSplat: layer '${layer.id}' far needs tile > 0, from < to and amount in 0..1.`,
576
+ `loadTerrainSplat: layer '${layer.id}' names missing mask '${layer.mask}'.`,
481
577
  );
482
- const reach = smoothstep(far.from, far.to, positionWorld.distance(cameraPosition));
483
- sample = mix(sample, diffuseAt(index, ground.div(far.tile)), reach.mul(far.amount));
484
- }
485
- if (layer.saturation !== undefined) {
486
- const luma = dot(sample, vec3(0.2126, 0.7152, 0.0722));
487
- sample = mix(vec3(luma), sample, layer.saturation);
488
- }
489
- return sample.mul(vec3(...layer.tint));
490
- };
491
- const normalOf = (layer: ITerrainSplatLayer): Node<"vec3"> | undefined => {
492
- const slot = withNormals.indexOf(layer);
493
- return slot === -1 || normalAt === undefined
494
- ? undefined
495
- : normalAt(slot, ground.div(layer.tile));
496
- };
497
- /**
498
- * A layer's answer to light, as occlusion in r, roughness in g and metalness in b: its ORM map
499
- * where it ships one, else the two numbers the table states (and no occlusion to apply).
500
- */
501
- const ormOf = (layer: ITerrainSplatLayer): Node<"vec3"> => {
502
- const slot = withOrm.indexOf(layer);
503
- if (slot !== -1 && ormAt !== undefined) return ormAt(slot, ground.div(layer.tile));
504
- return vec3(1, layer.roughness ?? DEFAULT_ROUGHNESS, layer.metalness ?? 0);
505
- };
578
+ const source = planes[where[0]];
579
+ if (source === undefined)
580
+ throw new Error(`loadTerrainSplat: mask '${layer.mask}' names a missing plane.`);
581
+ return source[where[1] === "rgb" ? layer.channel : where[1]];
582
+ };
583
+ const breakup = mx_noise_float(vec3(ground.mul(table.breakup.scale), 0))
584
+ .mul(0.5)
585
+ .add(0.5);
586
+ const push = breakup.mul(2 * table.breakup.push).sub(table.breakup.push);
506
587
 
507
- /** A height-carrying layer's own height, on the projection its albedo uses. */
508
- const heightOf = (layer: ITerrainSplatMaskedLayer): Node<"float"> | undefined => {
509
- const slot = withHeight.indexOf(layer);
510
- if (slot === -1 || heightAt === undefined) return undefined;
511
- const at = (uv: Node<"vec2">): Node<"vec3"> => heightAt(slot, uv);
512
- return (layer.triplanar === true ? triplanar(at, layer.tile) : at(ground.div(layer.tile))).r;
513
- };
588
+ // Box projection for cliffs: three axis-aligned samples blended by the surface normal.
589
+ const triplanar = (at: (uv: Node<"vec2">) => Node<"vec3">, tile: number): Node<"vec3"> => {
590
+ const weights = normalWorld.abs();
591
+ const w = weights.div(weights.x.add(weights.y).add(weights.z));
592
+ const p = positionWorld.div(tile);
593
+ return at(p.zy).mul(w.x).add(at(p.xz).mul(w.y)).add(at(p.xy).mul(w.z));
594
+ };
595
+
596
+ const albedo = (layer: ITerrainSplatLayer, index: number): Node<"vec3"> => {
597
+ let sample: Node<"vec3"> =
598
+ layer.triplanar === true
599
+ ? triplanar((uv) => diffuseAt(index, uv), layer.tile)
600
+ : diffuseAt(index, ground.div(layer.tile));
601
+ const far = layer.far;
602
+ if (far !== undefined && layer.triplanar !== true) {
603
+ if (!(far.tile > 0 && far.from < far.to && far.amount >= 0 && far.amount <= 1))
604
+ throw new Error(
605
+ `loadTerrainSplat: layer '${layer.id}' far needs tile > 0, from < to and amount in 0..1.`,
606
+ );
607
+ const reach = smoothstep(far.from, far.to, positionWorld.distance(cameraPosition));
608
+ sample = mix(sample, diffuseAt(index, ground.div(far.tile)), reach.mul(far.amount));
609
+ }
610
+ if (layer.saturation !== undefined) {
611
+ const luma = dot(sample, vec3(0.2126, 0.7152, 0.0722));
612
+ sample = mix(vec3(luma), sample, layer.saturation);
613
+ }
614
+ return sample.mul(vec3(...layer.tint));
615
+ };
616
+ const normalOf = (layer: ITerrainSplatLayer): Node<"vec3"> | undefined => {
617
+ const slot = withNormals.indexOf(layer);
618
+ return slot === -1 || normalAt === undefined
619
+ ? undefined
620
+ : normalAt(slot, ground.div(layer.tile));
621
+ };
622
+ /**
623
+ * A layer's answer to light, as occlusion in r, roughness in g and metalness in b: its ORM map
624
+ * where it ships one, else the two numbers the table states (and no occlusion to apply).
625
+ */
626
+ const ormOf = (layer: ITerrainSplatLayer): Node<"vec3"> => {
627
+ const slot = withOrm.indexOf(layer);
628
+ if (slot !== -1 && ormAt !== undefined) return ormAt(slot, ground.div(layer.tile));
629
+ return vec3(1, layer.roughness ?? DEFAULT_ROUGHNESS, layer.metalness ?? 0);
630
+ };
514
631
 
515
- let color = albedo(table.base, 0);
516
- let normalSample: Node<"vec3"> = normalOf(table.base) ?? vec3(0.5, 0.5, 1);
517
- let ormSample: Node<"vec3"> = ormOf(table.base);
518
- table.layers.forEach((layer, offset) => {
519
- const masked = clamp(
520
- maskOf(layer)
521
- .add(push)
522
- .sub(layer.lo)
523
- .div(layer.hi - layer.lo),
524
- 0,
525
- 1,
632
+ /** A height-carrying layer's own height, on the projection its albedo uses. */
633
+ const heightOf = (layer: ITerrainSplatMaskedLayer): Node<"float"> | undefined => {
634
+ const slot = withHeight.indexOf(layer);
635
+ if (slot === -1 || heightAt === undefined) return undefined;
636
+ const at = (uv: Node<"vec2">): Node<"vec3"> => heightAt(slot, uv);
637
+ return (layer.triplanar === true ? triplanar(at, layer.tile) : at(ground.div(layer.tile))).r;
638
+ };
639
+
640
+ const samples = all.map(
641
+ (layer, index): ITerrainSplatSample =>
642
+ options.layerSample === undefined
643
+ ? { color: albedo(layer, index), normal: normalOf(layer), orm: ormOf(layer) }
644
+ : options.layerSample({
645
+ layer,
646
+ index,
647
+ diffuse: diffuseMaps[index] as Texture,
648
+ normal: normalMaps[withNormals.indexOf(layer)],
649
+ orm: ormMaps[withOrm.indexOf(layer)],
650
+ height: heightMaps[withHeight.indexOf(layer as ITerrainSplatMaskedLayer)],
651
+ }),
526
652
  );
527
- const weight =
528
- options.layerWeight === undefined
529
- ? masked
530
- : options.layerWeight(masked, { height: heightOf(layer), index: offset, layer });
531
- color = mix(color, albedo(layer, offset + 1), weight);
532
- const nrm = normalOf(layer);
533
- if (nrm !== undefined) normalSample = mix(normalSample, nrm, weight);
534
- ormSample = mix(ormSample, ormOf(layer), weight);
653
+ let color = (samples[0] as ITerrainSplatSample).color;
654
+ let normalSample: Node<"vec3"> = samples[0]?.normal ?? vec3(0.5, 0.5, 1);
655
+ let ormSample: Node<"vec3"> = samples[0]?.orm ?? ormOf(table.base);
656
+ table.layers.forEach((layer, offset) => {
657
+ const masked = clamp(
658
+ maskOf(layer)
659
+ .add(push)
660
+ .sub(layer.lo)
661
+ .div(layer.hi - layer.lo),
662
+ 0,
663
+ 1,
664
+ );
665
+ const weight =
666
+ options.layerWeight === undefined
667
+ ? masked
668
+ : options.layerWeight(masked, { height: heightOf(layer), index: offset, layer });
669
+ const sample = samples[offset + 1] as ITerrainSplatSample;
670
+ color = mix(color, sample.color, weight);
671
+ const nrm = sample.normal;
672
+ if (nrm !== undefined) normalSample = mix(normalSample, nrm, weight);
673
+ ormSample = mix(ormSample, sample.orm ?? ormOf(layer), weight);
674
+ });
675
+ const macro = mx_noise_float(vec3(ground.mul(table.macro.scale), 0))
676
+ .mul(0.5)
677
+ .add(0.5)
678
+ .mul(table.macro.max - table.macro.min)
679
+ .add(table.macro.min);
680
+
681
+ // Every layer's own light response, blended by the same weights as its colour: the material
682
+ // holds no scalar of its own, and `DEFAULT_ROUGHNESS` only answers for a layer that states
683
+ // nothing at all.
684
+ let material: Material;
685
+ if (options.materialFactory === undefined) {
686
+ const standard = new MeshStandardNodeMaterial();
687
+ standard.name = "terrain-splat";
688
+ standard.colorNode = color.mul(macro);
689
+ // A top-down projection's tangent frame: +x along u, ground +y (three -z) along v, OpenGL green
690
+ // up v, re-orthogonalised against the tile's own normal.
691
+ const n = normalWorld;
692
+ const tangent = vec3(1, 0, 0).sub(n.mul(n.x)).normalize();
693
+ const bitangent = n.cross(tangent).normalize();
694
+ const t = normalSample.mul(2).sub(1);
695
+ const perturbed = tangent.mul(t.x).add(bitangent.mul(t.y)).add(n.mul(t.z)).normalize();
696
+ standard.normalNode = cameraViewMatrix.mul(vec4(perturbed, 0)).xyz.normalize();
697
+ standard.aoNode = ormSample.r;
698
+ standard.roughnessNode = ormSample.g;
699
+ standard.metalnessNode = ormSample.b;
700
+ material = standard;
701
+ } else {
702
+ material = options.materialFactory({
703
+ color: color.mul(macro),
704
+ normal: normalSample,
705
+ orm: ormSample,
706
+ });
707
+ }
708
+ if (owned !== undefined) material.addEventListener("dispose", release);
709
+ // One line, printed and kept on the material: what this surface costs, readable by a game that
710
+ // wants to assert it rather than scrape a console.
711
+ material.userData.TN_TERRAIN_SPLAT =
712
+ options.layerSample === undefined
713
+ ? `layers=${String(all.length)} samplers=${String(samplers)} stacked=${String(stackedSets)}`
714
+ : `layers=${String(all.length)} loadedSamplerUpperBound=${String(samplers)} stacked=0 sampling=custom`;
715
+ console.info(`TN_TERRAIN_SPLAT ${material.userData.TN_TERRAIN_SPLAT as string}`);
716
+ return material;
717
+ } catch (error) {
718
+ if (owned !== undefined) release();
719
+ throw error;
720
+ }
721
+ }
722
+
723
+ /**
724
+ * Apply a cooked GLB's package-authored layered surface to its marked terrain meshes.
725
+ * `url` is the loaded GLB URL; extras pointers are relative to it. Uses the same asset/fetch
726
+ * path as loadTerrainSplat on web and native. The caller owns the assigned materials' lifetime.
727
+ * @situation apply the authored layered terrain surface after loading a cooked world GLB
728
+ * @constraint url names the loaded GLB; tnTerrainSurface extras name a relative world package JSON
729
+ * @override `table` may replace `base`, `breakup`, `macro` and `layers`; baked `splat` and `textures` stay package-owned
730
+ * @example
731
+ * await applyTerrainSurface(world.scene, { assets: ctx.assets, renderer: ctx.renderer, url: "world/world.glb" });
732
+ */
733
+ export async function applyTerrainSurface(
734
+ root: Object3D,
735
+ options: ILoadTerrainSplatOptions,
736
+ ): Promise<void> {
737
+ const targets = new Map<Mesh, string>();
738
+ const retained = new Set<Material>();
739
+ root.traverse((object) => {
740
+ if (!(object instanceof Mesh)) return;
741
+ let owner: Object3D | null = object;
742
+ while (owner !== null && owner.userData.tnTerrainSurface === undefined && owner !== root)
743
+ owner = owner.parent;
744
+ const pointer: unknown = owner?.userData.tnTerrainSurface;
745
+ if (pointer === undefined) {
746
+ for (const material of Array.isArray(object.material) ? object.material : [object.material])
747
+ retained.add(material);
748
+ return;
749
+ }
750
+ if (
751
+ typeof pointer !== "string" ||
752
+ !/^(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9_.-]+\.json$/u.test(pointer)
753
+ )
754
+ throw new Error(`applyTerrainSurface: invalid terrain surface pointer '${String(pointer)}'.`);
755
+ targets.set(object, packageDir(options.url) + pointer);
535
756
  });
536
- const macro = mx_noise_float(vec3(ground.mul(table.macro.scale), 0))
537
- .mul(0.5)
538
- .add(0.5)
539
- .mul(table.macro.max - table.macro.min)
540
- .add(table.macro.min);
541
-
542
- // Every layer's own light response, blended by the same weights as its colour: the material
543
- // holds no scalar of its own, and `DEFAULT_ROUGHNESS` only answers for a layer that states
544
- // nothing at all.
545
- const material = new MeshStandardNodeMaterial();
546
- material.name = "terrain-splat";
547
- material.colorNode = color.mul(macro);
548
- // A top-down projection's tangent frame: +x along u, ground +y (three -z) along v, OpenGL green
549
- // up v, re-orthogonalised against the tile's own normal.
550
- const n = normalWorld;
551
- const tangent = vec3(1, 0, 0).sub(n.mul(n.x)).normalize();
552
- const bitangent = n.cross(tangent).normalize();
553
- const t = normalSample.mul(2).sub(1);
554
- const perturbed = tangent.mul(t.x).add(bitangent.mul(t.y)).add(n.mul(t.z)).normalize();
555
- material.normalNode = cameraViewMatrix.mul(vec4(perturbed, 0)).xyz.normalize();
556
- material.aoNode = ormSample.r;
557
- material.roughnessNode = ormSample.g;
558
- material.metalnessNode = ormSample.b;
559
- // One line, printed and kept on the material: what this surface costs, readable by a game that
560
- // wants to assert it rather than scrape a console.
561
- material.userData.TN_TERRAIN_SPLAT = `layers=${String(all.length)} samplers=${String(samplers)} stacked=${String(stackedSets)}`;
562
- console.info(`TN_TERRAIN_SPLAT ${material.userData.TN_TERRAIN_SPLAT as string}`);
563
- return material;
757
+ const surfaces = new Map<string, Material>();
758
+ try {
759
+ for (const url of new Set(targets.values()))
760
+ surfaces.set(url, await loadTerrainSplat({ ...options, url }));
761
+ } catch (error) {
762
+ for (const surface of surfaces.values()) surface.dispose();
763
+ throw error;
764
+ }
765
+ const replaced = new Set<Material>();
766
+ for (const [mesh, url] of targets) {
767
+ for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material])
768
+ replaced.add(material);
769
+ mesh.material = surfaces.get(url) as Material;
770
+ }
771
+ for (const material of replaced) if (!retained.has(material)) material.dispose();
564
772
  }