@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,151 @@
1
+ import type { IRendererLike } from "./renderer.js";
2
+ import { DEFAULT_TARGET_FPS } from "./target-fps.js";
3
+
4
+ /**
5
+ * The adaptive LOD bias: one multiplier both selection paths read, moved by the main pass's own GPU
6
+ * time.
7
+ *
8
+ * The loop had no home before this module and lived in `world-cells.ts` between `process` and the
9
+ * prefetch lookahead; it moves here as it was — same constants, same order of tests, same marker
10
+ * line — with its four inputs behind a host so a world can answer them and a test can drive it. The
11
+ * bias itself is written out through the host: the shared multiplier in `model-lod.ts` and the GPU
12
+ * uniform the dispatch carries are one number, and this class owns none of them.
13
+ */
14
+
15
+ /** The adaptive LOD bias floor. A bias is only ever allowed to coarsen selection, never refine it. */
16
+ const LOD_BIAS_MIN = 1;
17
+ /** The adaptive LOD bias ceiling, so a runaway maps to a coarser but still bounded world. */
18
+ const LOD_BIAS_MAX = 2.5;
19
+ /** How much the bias rises per over-budget step. */
20
+ const LOD_BIAS_RISE = 1.08;
21
+ /** How much the bias decays per comfortably-under-budget step. */
22
+ const LOD_BIAS_DECAY = 0.95;
23
+ /** Seconds between rise or decay steps; a change is never larger than one step. */
24
+ const LOD_BIAS_STEP_SECONDS = 0.5;
25
+ /** Below this share of the affordable budget the bias decays; between it and the budget it holds. */
26
+ const LOD_BIAS_DECAY_SHARE = 0.6;
27
+ /** Seconds between two `TN_LOD_BIAS` lines. */
28
+ const LOD_BIAS_MARKER_SECONDS = 1;
29
+ /** The line the adaptive loop prints when it moves the bias. */
30
+ export const LOD_BIAS_MARKER = "TN_LOD_BIAS";
31
+
32
+ /** What the loop asks its world for: the clock, the sample, the two gates and the one write. */
33
+ export interface ICellLodBiasHost {
34
+ readonly now: () => number;
35
+ /** The renderer whose main pass is being measured; `update`'s argument, else the last one seen. */
36
+ readonly renderer: () => IRendererLike | undefined;
37
+ /** The prewarm gate: what the loading screen waits on, as the three counters it reports. */
38
+ readonly prewarm: () => {
39
+ readonly queued: number;
40
+ readonly owed: number;
41
+ readonly drawn: number;
42
+ };
43
+ /** The GPU-selected main-pass triangles of the last landed tally, absent before one lands. */
44
+ readonly gpuTriangles: () => number | undefined;
45
+ /** Writes the multiplier to both selection paths: the shared one and the GPU uniform. */
46
+ readonly apply: (bias: number) => void;
47
+ }
48
+
49
+ export class CellLodBias {
50
+ readonly #enabled: boolean;
51
+ readonly #mainGpuShare: number;
52
+ readonly #host: ICellLodBiasHost;
53
+ /** The distance multiplier both selection paths are using right now. */
54
+ #bias = LOD_BIAS_MIN;
55
+ /** The clock the step cadence and the first marker line are measured from. */
56
+ readonly #startedAt: number;
57
+ /** The last time a rise or decay step ran. */
58
+ #stepAt: number;
59
+ /** The last time the `TN_LOD_BIAS` line printed. */
60
+ #toldAt: number;
61
+
62
+ constructor(enabled: boolean, mainGpuShare: number, host: ICellLodBiasHost) {
63
+ this.#enabled = enabled;
64
+ this.#mainGpuShare = mainGpuShare;
65
+ this.#host = host;
66
+ // The marker is periodic, and a world's first five seconds are its own: the clock starts at the
67
+ // world, not before it, so loading does not print a line.
68
+ this.#startedAt = host.now();
69
+ this.#stepAt = this.#startedAt;
70
+ this.#toldAt = this.#startedAt - LOD_BIAS_MARKER_SECONDS * 1000;
71
+ }
72
+
73
+ /**
74
+ * The adaptive LOD bias control loop. Reads the main pass's smoothed GPU time from the renderer
75
+ * and, once per `LOD_BIAS_STEP_SECONDS`, raises the shared bias while that pass is over its share
76
+ * of the frame and decays it back toward 1 while it is comfortably under; between the two it
77
+ * holds, which is the band that keeps a level sitting on the budget from oscillating. A window with
78
+ * no fresh sample is a hold, never a rise on a stale number, and a rise needs the world itself to be
79
+ * the thing being drawn — see {@link #overBudget}, which is also what replaced the warmup
80
+ * seconds. The decay is never gated: a world that can afford its main pass gives the bias back.
81
+ */
82
+ step(renderer: IRendererLike | undefined): void {
83
+ if (this.#enabled === false) {
84
+ // Byte-identical to the pre-bias selection: the multiplier is pinned at 1 every frame.
85
+ this.#apply(LOD_BIAS_MIN);
86
+ return;
87
+ }
88
+ const now = this.#host.now();
89
+ if (now - this.#stepAt < LOD_BIAS_STEP_SECONDS * 1000) return;
90
+ const source = renderer ?? this.#host.renderer();
91
+ // The frame the budget is a share of: the game's resolved target, 60 fps until one is known.
92
+ // Never the frame just measured — an expensive pass makes its own frame long and would pass its
93
+ // own test, and a fast one shrank the share until a 3 ms pass coarsened a world running at
94
+ // 400 fps against a 120 fps target (PRD-478).
95
+ const target = source?.targetFps?.();
96
+ const frameMs = 1000 / (target !== undefined && target > 0 ? target : DEFAULT_TARGET_FPS);
97
+ const gpuMs = source?.gpuMainMs?.();
98
+ if (gpuMs === undefined) return;
99
+ this.#stepAt = now;
100
+ const affordableMs = this.#mainGpuShare * frameMs;
101
+ if (!(affordableMs > 0)) return;
102
+ const bias =
103
+ gpuMs > affordableMs
104
+ ? this.#overBudget()
105
+ : gpuMs < LOD_BIAS_DECAY_SHARE * affordableMs
106
+ ? Math.max(LOD_BIAS_MIN, this.#bias * LOD_BIAS_DECAY)
107
+ : this.#bias;
108
+ if (bias === this.#bias) return;
109
+ this.#apply(bias);
110
+ if (now - this.#toldAt >= LOD_BIAS_MARKER_SECONDS * 1000) {
111
+ this.#toldAt = now;
112
+ const triangles = this.#host.gpuTriangles();
113
+ console.info(
114
+ `${LOD_BIAS_MARKER} bias=${bias.toFixed(3)} gpuMs=${gpuMs.toFixed(2)} ` +
115
+ `budgetMs=${affordableMs.toFixed(2)} ` +
116
+ `tris=${triangles === undefined ? "n/a" : String(triangles)}`,
117
+ );
118
+ }
119
+ }
120
+
121
+ /**
122
+ * The next bias while the main pass is over its share of the frame, or the bias unchanged when the
123
+ * world is not what that pass is drawing.
124
+ *
125
+ * A load's GPU time is shader compiles, buffer uploads and the prewarm — none of it main-pass world
126
+ * geometry, so a coarser selection cannot take any of it back. What it costs is the first playable
127
+ * frame: every tree selects the level authored for its distance times the bias, the coarsest levels
128
+ * hold almost nothing, and the shadow casters, which take no bias, leave a band of tree shadows with
129
+ * no trees 80-300 m out. Measured on Machinefall (RTX 2080, WebGPU), the bias climbed 1.08 → 2.33
130
+ * over six `TN_LOD_BIAS` steps, all of them before the loading overlay dropped.
131
+ *
132
+ * So the rise waits for the two measurements that say the world is being drawn: the prewarm gate —
133
+ * what a game's loading screen waits on, and `stats().pendingPrewarm` as the same thing as a number
134
+ * — and the main pass's own GPU-selected triangle tally, where a tally that landed and says zero is
135
+ * a world drawn as nothing. A world with no tally at all (no GPU scene, or nothing landed yet) has no
136
+ * opinion about its own triangles, so the prewarm speaks for it alone. Both are measurements of the
137
+ * thing being judged, which is what the warmup seconds were standing in for.
138
+ */
139
+ #overBudget(): number {
140
+ const prewarm = this.#host.prewarm();
141
+ if (prewarm.queued > 0 || prewarm.owed > prewarm.drawn) return this.#bias;
142
+ if (this.#host.gpuTriangles() === 0) return this.#bias;
143
+ return Math.min(LOD_BIAS_MAX, this.#bias * LOD_BIAS_RISE);
144
+ }
145
+
146
+ /** Writes the bias to both selection paths: the shared CPU multiplier and the GPU uniform. */
147
+ #apply(bias: number): void {
148
+ this.#bias = bias;
149
+ this.#host.apply(bias);
150
+ }
151
+ }