@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
@@ -0,0 +1,131 @@
1
+ /**
2
+ * What a launch asks of the GPU path, read from the environment variable, the query string and the
3
+ * global a test sets — the same three sources in the same order for every switch.
4
+ *
5
+ * These read the launch, so they belong with neither the renderer nor the kernel: a caller can ask
6
+ * what a run would use without building a scene, and a test can pin the order the sources are read
7
+ * in without a device.
8
+ */
9
+ import { readLaunchFlag, readLaunchValues } from "./debug.js";
10
+
11
+ /** The launch flag. */
12
+ export const GPU_SCENE_FLAG = "TN_GPU_SCENE";
13
+
14
+ /**
15
+ * Did this launch ask for `flag` to be **off**? The environment variable, the query string and the
16
+ * global a test sets are the three ways one is asked, and `debug.ts` owns the rule that reads them
17
+ * — see {@link readLaunchFlag}.
18
+ */
19
+ function askedOff(flag: string, parameter: string, globalName: string): boolean {
20
+ return readLaunchFlag({ environment: flag, global: globalName, query: parameter }, "off");
21
+ }
22
+
23
+ /**
24
+ * Did this launch ask for `flag` to be **on**? The mirror of {@link askedOff}, for the switches
25
+ * that are opt-in.
26
+ */
27
+ function askedOn(flag: string, parameter: string, globalName: string): boolean {
28
+ return readLaunchFlag({ environment: flag, global: globalName, query: parameter });
29
+ }
30
+
31
+ /**
32
+ * Whether the GPU-driven main pass should run on this launch, on by default where the backend can.
33
+ *
34
+ * @situation debug a walk whose main pass culls and LOD-selects on the GPU
35
+ * @constraint on unless a launch asks for the CPU path: `gpuScene: false`, `?tnGpuScene=0` or
36
+ * `TN_GPU_SCENE=0` turn it off, and a backend without compute, storage buffers and
37
+ * `drawIndexedIndirect` falls back on its own
38
+ * @example WorldCells.load({ ...options, gpuScene: gpuSceneRequested() });
39
+ *
40
+ * Read the way `renderListValidationRequested` and `terrainValidationRequested` read their own: a
41
+ * native launch sets the environment variable, a browser asks with the query string, and a test
42
+ * sets the global. Measured on machinefall at 863f83258, so it flipped from opt-in to default.
43
+ */
44
+ export function gpuSceneRequested(): boolean {
45
+ return askedOff(GPU_SCENE_FLAG, "tnGpuScene", "__tnGpuScene") === false;
46
+ }
47
+
48
+ /** Did this launch ask the CPU path to grade levels from `follow`, the before arm of `lodFrom`? */
49
+ export function lodFromFollowRequested(): boolean {
50
+ return askedOff("TN_LOD_FROM_CAMERA", "tnLodFromCamera", "__tnLodFromCamera");
51
+ }
52
+
53
+ /** The launch flag. */
54
+ export const BUNDLE_FLAG = "TN_BUNDLES";
55
+
56
+ /**
57
+ * What this launch asked for about world draw bundles: `on`, `off`, or `default` when it said
58
+ * nothing.
59
+ *
60
+ * @situation tell a run that set the option itself apart from one that took the default
61
+ * @example WorldCells.load({ ...options, bundles: bundlesAsked() !== "off" });
62
+ *
63
+ * Read the way {@link gpuSceneRequested} reads its own: a native launch sets the environment
64
+ * variable, a browser asks with the query string, and a test sets the global.
65
+ */
66
+ export function bundlesAsked(): "default" | "off" | "on" {
67
+ // Its own vocabulary over the one reader: a launch can answer yes, answer no, or say nothing, and
68
+ // "said nothing" is what a caller has to tell apart from a measurement's default. Every seam is
69
+ // heard, as it is for every other switch, so an explicit yes anywhere beats a no anywhere.
70
+ const values = readLaunchValues({
71
+ environment: BUNDLE_FLAG,
72
+ global: "__tnBundles",
73
+ query: "tnBundles",
74
+ });
75
+ if (values.some((value) => value === "1" || value === "true" || value === "")) return "on";
76
+ return values.some((value) => value === "0" || value === "false") ? "off" : "default";
77
+ }
78
+
79
+ /**
80
+ * Whether world draw bundles should be recorded and replayed. On by default, and off unless a launch
81
+ * asks for the CPU path.
82
+ *
83
+ * @situation debug a walk whose main batches are replayed from a recorded bundle
84
+ * @constraint on unless a launch asks otherwise: `bundles: false`, `?tnBundles=0` or `TN_BUNDLES=0`
85
+ * turn it off. The default followed a measurement, not a preference — PRD-494 AC-2 took the walking
86
+ * `draw` span from a 6.0 ms p50 median to 0.6 ms against develop over 3 interleaved runs, on a
87
+ * picture a blind world gate called equal, so the answer that used to be "off, it gave no CPU
88
+ * p50/p95 gain" is now "on, it is 5 ms of the walking p95". `bundles: true`, `?tnBundles=1` or
89
+ * `TN_BUNDLES=1` still say so explicitly. See PRD-473 phase 2 and PRD-494 phase 2.
90
+ * @example WorldCells.load({ ...options, bundles: bundlesRequested() });
91
+ */
92
+ export function bundlesRequested(): boolean {
93
+ return bundlesAsked() !== "off";
94
+ }
95
+
96
+ /** The validation flag. */
97
+ export const GPU_SCENE_VALIDATE_FLAG = "TN_GPU_SCENE_VALIDATE";
98
+
99
+ /**
100
+ * Whether the GPU scene should hold every dispatch's indirect args against the CPU reference.
101
+ *
102
+ * @situation find the keys a real WebGPU dispatch draws fewer instances of than `cullAndSelect` does
103
+ * @constraint off by default and never on a measured walk: a readback is a queue submission and a
104
+ * mapped buffer, so the mode exists to answer "which key" and not to be fast
105
+ * @example WorldCells.load({ ...options, gpuScene: true, gpuSceneValidate: gpuSceneValidationRequested() });
106
+ *
107
+ * Read the way `gpuSceneRequested` reads its own: a native launch sets the environment variable, a
108
+ * browser asks with `?tnGpuSceneValidate=1`, and a test sets the global.
109
+ */
110
+ export function gpuSceneValidationRequested(): boolean {
111
+ return askedOn(GPU_SCENE_VALIDATE_FLAG, "tnGpuSceneValidate", "__tnGpuSceneValidate");
112
+ }
113
+
114
+ /** The launch flag. */
115
+ export const SHADOW_GPU_KEYS_FLAG = "TN_SHADOW_GPU_KEYS";
116
+
117
+ /**
118
+ * Whether a shadow level may select its own set of GPU-scene keys. Opt-in, and off by default.
119
+ *
120
+ * @situation debug a walk whose shadow maps draw GPU-scene keys instead of cluster meshes
121
+ * @constraint off unless a launch asks for it: without a provider nothing is allocated and no
122
+ * dispatch is submitted, so the flag alone cannot change a frame — `shadowGpuKeys: true`,
123
+ * `?tnShadowGpuKeys=1` or `TN_SHADOW_GPU_KEYS=1` turns it on. See PRD-478 phase 2.
124
+ * @example world.gpuScene.shadowKeysFrom(() => keyNames);
125
+ *
126
+ * Read the way {@link bundlesRequested} reads its own: a native launch sets the environment
127
+ * variable, a browser asks with the query string, and a test sets the global.
128
+ */
129
+ export function shadowGpuKeysRequested(): boolean {
130
+ return askedOn(SHADOW_GPU_KEYS_FLAG, "tnShadowGpuKeys", "__tnShadowGpuKeys");
131
+ }