@threenative/core 0.3.11 → 0.3.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10566 -22552
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
@@ -0,0 +1,163 @@
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
+
10
+ /** The launch flag. */
11
+ export const GPU_SCENE_FLAG = "TN_GPU_SCENE";
12
+
13
+ /**
14
+ * Did this launch ask for `flag` to be **off**? The environment variable, the query string and the
15
+ * global a test sets are the three ways one is asked, and `0` and `false` are the only answers that
16
+ * count: an unset or empty variable is the same as no variable, and a saved URL that used to enable
17
+ * a switch still says "off".
18
+ */
19
+ function askedOff(flag: string, parameter: string, globalName: string): boolean {
20
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
21
+ string,
22
+ unknown
23
+ >;
24
+ const fromEnv = host.process?.env?.[flag];
25
+ if (fromEnv === "0" || fromEnv === "false") return true;
26
+ const query = globalThis.location?.search;
27
+ if (
28
+ typeof query === "string" &&
29
+ new RegExp(`[?&]${parameter}=(?:0|false)(?:&|$)`, "u").test(query)
30
+ )
31
+ return true;
32
+ const set = host[globalName];
33
+ return set === false || set === 0 || set === "0" || set === "false";
34
+ }
35
+
36
+ /**
37
+ * Did this launch ask for `flag` to be **on**? The mirror of {@link askedOff}, for the switches that
38
+ * are opt-in: the environment variable, the query string and the global a test sets, and only
39
+ * `1` and `true` count. An unset or empty variable is the same as no variable, so an old URL that
40
+ * never mentioned the switch stays off.
41
+ */
42
+ function askedOn(flag: string, parameter: string, globalName: string): boolean {
43
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
44
+ string,
45
+ unknown
46
+ >;
47
+ const fromEnv = host.process?.env?.[flag];
48
+ if (fromEnv === "1" || fromEnv === "true") return true;
49
+ const query = globalThis.location?.search;
50
+ if (
51
+ typeof query === "string" &&
52
+ new RegExp(`[?&]${parameter}=(?:1|true)(?:&|$)`, "u").test(query)
53
+ )
54
+ return true;
55
+ return host[globalName] === true || host[globalName] === 1 || host[globalName] === "1";
56
+ }
57
+
58
+ /**
59
+ * Whether the GPU-driven main pass should run on this launch, on by default where the backend can.
60
+ *
61
+ * @situation debug a walk whose main pass culls and LOD-selects on the GPU
62
+ * @constraint on unless a launch asks for the CPU path: `gpuScene: false`, `?tnGpuScene=0` or
63
+ * `TN_GPU_SCENE=0` turn it off, and a backend without compute, storage buffers and
64
+ * `drawIndexedIndirect` falls back on its own
65
+ * @example WorldCells.load({ ...options, gpuScene: gpuSceneRequested() });
66
+ *
67
+ * Read the way `renderListValidationRequested` and `terrainValidationRequested` read their own: a
68
+ * native launch sets the environment variable, a browser asks with the query string, and a test
69
+ * sets the global. Measured on machinefall at 863f83258, so it flipped from opt-in to default.
70
+ */
71
+ export function gpuSceneRequested(): boolean {
72
+ return askedOff(GPU_SCENE_FLAG, "tnGpuScene", "__tnGpuScene") === false;
73
+ }
74
+
75
+ /** Did this launch ask the CPU path to grade levels from `follow`, the before arm of `lodFrom`? */
76
+ export function lodFromFollowRequested(): boolean {
77
+ return askedOff("TN_LOD_FROM_CAMERA", "tnLodFromCamera", "__tnLodFromCamera");
78
+ }
79
+
80
+ /** The launch flag. */
81
+ export const BUNDLE_FLAG = "TN_BUNDLES";
82
+
83
+ /**
84
+ * What this launch asked for about world draw bundles: `on`, `off`, or `default` when it said
85
+ * nothing.
86
+ *
87
+ * @situation tell a run that set the option itself apart from one that took the default
88
+ * @example WorldCells.load({ ...options, bundles: bundlesAsked() !== "off" });
89
+ *
90
+ * Read the way {@link gpuSceneRequested} reads its own: a native launch sets the environment
91
+ * variable, a browser asks with the query string, and a test sets the global.
92
+ */
93
+ export function bundlesAsked(): "default" | "off" | "on" {
94
+ if (askedOn(BUNDLE_FLAG, "tnBundles", "__tnBundles")) return "on";
95
+ return askedOff(BUNDLE_FLAG, "tnBundles", "__tnBundles") ? "off" : "default";
96
+ }
97
+
98
+ /**
99
+ * Whether world draw bundles should be recorded and replayed. On by default, and off unless a launch
100
+ * asks for the CPU path.
101
+ *
102
+ * @situation debug a walk whose main batches are replayed from a recorded bundle
103
+ * @constraint on unless a launch asks otherwise: `bundles: false`, `?tnBundles=0` or `TN_BUNDLES=0`
104
+ * turn it off. The default followed a measurement, not a preference — PRD-494 AC-2 took the walking
105
+ * `draw` span from a 6.0 ms p50 median to 0.6 ms against develop over 3 interleaved runs, on a
106
+ * picture a blind world gate called equal, so the answer that used to be "off, it gave no CPU
107
+ * p50/p95 gain" is now "on, it is 5 ms of the walking p95". `bundles: true`, `?tnBundles=1` or
108
+ * `TN_BUNDLES=1` still say so explicitly. See PRD-473 phase 2 and PRD-494 phase 2.
109
+ * @example WorldCells.load({ ...options, bundles: bundlesRequested() });
110
+ */
111
+ export function bundlesRequested(): boolean {
112
+ return bundlesAsked() !== "off";
113
+ }
114
+
115
+ /** The validation flag. */
116
+ export const GPU_SCENE_VALIDATE_FLAG = "TN_GPU_SCENE_VALIDATE";
117
+
118
+ /**
119
+ * Whether the GPU scene should hold every dispatch's indirect args against the CPU reference.
120
+ *
121
+ * @situation find the keys a real WebGPU dispatch draws fewer instances of than `cullAndSelect` does
122
+ * @constraint off by default and never on a measured walk: a readback is a queue submission and a
123
+ * mapped buffer, so the mode exists to answer "which key" and not to be fast
124
+ * @example WorldCells.load({ ...options, gpuScene: true, gpuSceneValidate: gpuSceneValidationRequested() });
125
+ *
126
+ * Read the way `gpuSceneRequested` reads its own: a native launch sets the environment variable, a
127
+ * browser asks with `?tnGpuSceneValidate=1`, and a test sets the global.
128
+ */
129
+ export function gpuSceneValidationRequested(): boolean {
130
+ const host = globalThis as {
131
+ process?: { env?: Record<string, unknown> };
132
+ __tnGpuSceneValidate?: unknown;
133
+ };
134
+ const fromEnv = host.process?.env?.[GPU_SCENE_VALIDATE_FLAG];
135
+ if (typeof fromEnv === "string" && fromEnv !== "" && fromEnv !== "0" && fromEnv !== "false")
136
+ return true;
137
+ const query = globalThis.location?.search;
138
+ if (
139
+ typeof query === "string" &&
140
+ /[?&]tnGpuSceneValidate=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(query)
141
+ )
142
+ return true;
143
+ return host.__tnGpuSceneValidate === true || host.__tnGpuSceneValidate === "1";
144
+ }
145
+
146
+ /** The launch flag. */
147
+ export const SHADOW_GPU_KEYS_FLAG = "TN_SHADOW_GPU_KEYS";
148
+
149
+ /**
150
+ * Whether a shadow level may select its own set of GPU-scene keys. Opt-in, and off by default.
151
+ *
152
+ * @situation debug a walk whose shadow maps draw GPU-scene keys instead of cluster meshes
153
+ * @constraint off unless a launch asks for it: without a provider nothing is allocated and no
154
+ * dispatch is submitted, so the flag alone cannot change a frame — `shadowGpuKeys: true`,
155
+ * `?tnShadowGpuKeys=1` or `TN_SHADOW_GPU_KEYS=1` turns it on. See PRD-478 phase 2.
156
+ * @example world.gpuScene.shadowKeysFrom(() => keyNames);
157
+ *
158
+ * Read the way {@link bundlesRequested} reads its own: a native launch sets the environment
159
+ * variable, a browser asks with the query string, and a test sets the global.
160
+ */
161
+ export function shadowGpuKeysRequested(): boolean {
162
+ return askedOn(SHADOW_GPU_KEYS_FLAG, "tnShadowGpuKeys", "__tnShadowGpuKeys");
163
+ }