@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
@@ -152,6 +152,8 @@ export function impostorViewWeights(direction: Vector3): IViewBlend {
152
152
  export function impostorBounds(parts: readonly IImpostorPart[]): {
153
153
  readonly center: Vector3;
154
154
  readonly radius: number;
155
+ /** Half the baked box's size per asset-local axis, which fits the quad (`impostorQuadExtents`). */
156
+ readonly halfExtents: Vector3;
155
157
  } {
156
158
  const whole = new Box3();
157
159
  whole.makeEmpty();
@@ -168,10 +170,11 @@ export function impostorBounds(parts: readonly IImpostorPart[]): {
168
170
  whole.union(localBox);
169
171
  any = true;
170
172
  }
171
- if (!any) return { center: new Vector3(), radius: 0.5 };
173
+ if (!any) return { center: new Vector3(), radius: 0.5, halfExtents: new Vector3(0.5, 0.5, 0.5) };
172
174
  const center = whole.getCenter(new Vector3());
173
175
  const radius = whole.getBoundingSphere(new Sphere()).radius;
174
- return { center, radius: radius > 0 ? radius : 0.5 };
176
+ const halfExtents = whole.getSize(new Vector3()).multiplyScalar(0.5);
177
+ return { center, radius: radius > 0 ? radius : 0.5, halfExtents };
175
178
  }
176
179
 
177
180
  /** The exact byte cost of a mip chain of `levels` RGBA8 levels at `pixels` square and `depth` deep. */
@@ -112,6 +112,17 @@ const animationRateRootRefs = new WeakMap<Object3D, WeakRef<Object3D>>();
112
112
  /** The stand-ins named in {@link animationRateSources}, so the pass can reach them without a scene walk. */
113
113
  const animationRateCarriers = new Set<WeakRef<Object3D>>();
114
114
 
115
+ /** AnimationPlayer's disposal: the root stops carrying `state`, unless a newer player already took it. */
116
+ export function untrackAnimationRate(root: Object3D, state: IAnimationRateState): void {
117
+ if (animationRateStates.get(root) !== state) return;
118
+ animationRateStates.delete(root);
119
+ const id = engineRateIds.get(root);
120
+ if (id === undefined) return;
121
+ setEngineRateState(id, undefined);
122
+ const engineRig = root as Partial<IEngineRateRig>;
123
+ if (typeof engineRig.__trackAnimationRate === "function") engineRig.__trackAnimationRate(-1);
124
+ }
125
+
115
126
  /** A projection stand-in or skinned batch names the rigs it draws (see {@link animationRateSources}). */
116
127
  export function observeAnimationRates(
117
128
  carrier: Object3D,
@@ -121,9 +132,37 @@ export function observeAnimationRates(
121
132
  animationRateSources.set(carrier, sources);
122
133
  }
123
134
 
135
+ /**
136
+ * The engine's handle for each tracked root (PRD-878): the engine keeps the rigs and answers [handle, rate]
137
+ * pairs, so a frame finds each state by index instead of walking the roots in JS.
138
+ */
139
+ const engineRateIds = new WeakMap<Object3D, number>();
140
+ const engineRateStates: (IAnimationRateState | undefined)[] = [];
141
+ /** The live entries of {@link engineRateStates}: with none, a frame makes no band call at all. */
142
+ let engineRateRigs = 0;
143
+
144
+ function setEngineRateState(id: number, state: IAnimationRateState | undefined): void {
145
+ engineRateRigs += (state === undefined ? 0 : 1) - (engineRateStates[id] === undefined ? 0 : 1);
146
+ engineRateStates[id] = state;
147
+ }
148
+
149
+ interface IEngineRateRig {
150
+ __trackAnimationRate(id: number): void;
151
+ }
152
+
124
153
  /** AnimationPlayer's registration: the state the camera pass writes, and the root it is found on. */
125
154
  export function trackAnimationRate(root: Object3D, state: IAnimationRateState): void {
126
155
  animationRateStates.set(root, state);
156
+ const engineRig = root as Partial<IEngineRateRig>;
157
+ if (typeof engineRig.__trackAnimationRate === "function") {
158
+ let id = engineRateIds.get(root);
159
+ if (id === undefined) {
160
+ id = engineRateStates.length;
161
+ engineRateIds.set(root, id);
162
+ }
163
+ setEngineRateState(id, state);
164
+ engineRig.__trackAnimationRate(id);
165
+ }
127
166
  // One ref per root: a respawn's new player on the same root must not add a second walk of it.
128
167
  let ref = animationRateRootRefs.get(root);
129
168
  if (ref === undefined) {
@@ -236,6 +275,26 @@ function countEngineCost(name: string): void {
236
275
  host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + 1;
237
276
  }
238
277
 
278
+ /**
279
+ * A scene root whose engine runs the whole band pass (scene/projected_cull.h bandAnimation): [handle, rate]
280
+ * pairs, [handle, -1] for a freed rig, or undefined when a tracked rig sits inside another.
281
+ */
282
+ interface IEngineBandRoot {
283
+ __bandAnimation(
284
+ camera: Camera,
285
+ cameraResolved: boolean,
286
+ scale: number,
287
+ frame: number,
288
+ ): readonly number[] | undefined;
289
+ }
290
+
291
+ function engineBandRoot(root: unknown): IEngineBandRoot | undefined {
292
+ const candidate = root as Partial<IEngineBandRoot> | null;
293
+ return typeof candidate?.__bandAnimation === "function"
294
+ ? (candidate as IEngineBandRoot)
295
+ : undefined;
296
+ }
297
+
239
298
  function engineCullRoot(root: unknown): IEngineCullRoot | undefined {
240
299
  const candidate = root as Partial<IEngineCullRoot> | null;
241
300
  return typeof candidate?.__cullProjected === "function" &&
@@ -414,7 +473,7 @@ export class RenderCameraCull {
414
473
  this.#animationFrame += 1;
415
474
  this.#animationPrepared = true;
416
475
  this.#prepareCamera(camera, viewportHeight);
417
- if (!this.#prepareAnimated()) return;
476
+ if (this.#bandOnEngine(root, camera) || !this.#prepareAnimated()) return;
418
477
  // Start at each rig and each stand-in that observes one, never at the scene: the walk then visits
419
478
  // the same objects a scene walk would have acted on, and nothing else.
420
479
  const rootShown = this.#isVisibleInWorld(root as Object3D);
@@ -429,8 +488,8 @@ export class RenderCameraCull {
429
488
  const rig = ref.deref();
430
489
  if (rig === undefined || !this.#reaches(rig, root)) continue;
431
490
  turn += 1;
432
- if (!holds || turn % RATE_MEASURE_FRAMES === 0 || !this.#holdRate(rig))
433
- this.#visitRig(rig, rootShown);
491
+ if (holds && turn % RATE_MEASURE_FRAMES !== 0 && this.#holdRate(rig)) continue;
492
+ this.#visitRig(rig, rootShown);
434
493
  }
435
494
  for (const ref of animationRateCarriers) {
436
495
  const carrier = ref.deref();
@@ -447,6 +506,42 @@ export class RenderCameraCull {
447
506
  }
448
507
  }
449
508
 
509
+ /**
510
+ * On the engine, with no stand-in observing a rig, the whole pass is one call (PRD-878): the engine keeps the
511
+ * rigs, checks which reach the root, holds a crowd's rates and bands the rest. False sends the frame to the
512
+ * walk below: plain three, a stand-in, or a rig inside a rig.
513
+ */
514
+ #bandOnEngine(root: unknown, camera: Camera): boolean {
515
+ const engine = animationRateCarriers.size === 0 ? engineBandRoot(root) : undefined;
516
+ if (engine !== undefined && engineRateRigs === 0) return true;
517
+ const pairs = engine?.__bandAnimation(
518
+ camera,
519
+ this.#cameraResolved,
520
+ this.#scale,
521
+ this.#animationFrame,
522
+ );
523
+ if (pairs === undefined) return false;
524
+ this.#takeBands(pairs);
525
+ return true;
526
+ }
527
+
528
+ /** The engine's [handle, rate] pairs, written to each state as the JS walk writes it; -1 drops a freed rig. */
529
+ #takeBands(pairs: readonly number[]): void {
530
+ for (let index = 0; index + 1 < pairs.length; index += 2) {
531
+ const id = pairs[index] as number;
532
+ const rate = pairs[index + 1] as number;
533
+ if (rate < 0) {
534
+ setEngineRateState(id, undefined);
535
+ continue;
536
+ }
537
+ const state = engineRateStates[id];
538
+ if (state === undefined) continue;
539
+ state.rate = rate;
540
+ state.source = this;
541
+ state.frame = this.#animationFrame;
542
+ }
543
+ }
544
+
450
545
  /** Carries a rig's rate into this frame; false when last frame did not measure or hold it, as for a rig just shown. */
451
546
  #holdRate(rig: Object3D): boolean {
452
547
  const state = animationRateStates.get(rig);
@@ -0,0 +1,41 @@
1
+ /**
2
+ * The environment measure-and-sample mechanism every kit repeats: what the scene's environment
3
+ * actually contributes, a bounded GPU sample of it with a cache and a readback deadline, the
4
+ * provenance a stale readback is rejected by, and the gate that decides which renderer may run
5
+ * the material lane. The backlight itself is a shader with fixed constants, so it stays in each
6
+ * kit's `src/render/` (stamped from one source there) where the game can change how it looks.
7
+ *
8
+ * This is machinery, not a look: every colour, gain and threshold arrives as an argument, and a kit
9
+ * that wants a different bound passes a different one. It lives here because twelve kits held
10
+ * byte-identical copies — 9 084 lines — so a fix to one left eleven wrong with every gate green
11
+ * (`c93b427d0` touched 552 files for one look change).
12
+ *
13
+ * @situation measure what a scene's environment actually contributes
14
+ * @situation sample the environment on the GPU without stalling the frame
15
+ * @situation keep an environment readback from reaching a frame it does not belong to
16
+ */
17
+ export {
18
+ type IEnvironmentMeasurement,
19
+ measureEnvironment,
20
+ reportEnvironmentContribution,
21
+ } from "./render/environment/environmentContribution.js";
22
+ export { sampledRadiance } from "./render/environment/environmentRadiance.js";
23
+ export {
24
+ cacheEnvironmentSample,
25
+ cachedEnvironmentSample,
26
+ } from "./render/environment/environmentSampleCache.js";
27
+ export {
28
+ type IEnvironmentSample,
29
+ sampleEnvironment,
30
+ } from "./render/environment/environmentSampling.js";
31
+ export {
32
+ type IEnvironmentSourceSnapshot,
33
+ captureEnvironmentSnapshot,
34
+ environmentSnapshotCurrent,
35
+ samplingSourceSupported,
36
+ } from "./render/environment/environmentSnapshot.js";
37
+ export {
38
+ type IMaterialLightingEnvironment,
39
+ isWebGLFallbackRenderer,
40
+ materialLightingEnabled,
41
+ } from "./render/environment/gate.js";
@@ -223,7 +223,7 @@ function readCounters(target: IRenderPassTarget): { draws: number; triangles: nu
223
223
  return { draws, triangles };
224
224
  }
225
225
 
226
- const installed = new WeakSet<object>();
226
+ const installed = new WeakMap<object, RenderPassBudget>();
227
227
 
228
228
  /**
229
229
  * Resolved frames kept for GPU attribution. A resolve lags the frame it measures by a few frames,
@@ -233,15 +233,25 @@ const installed = new WeakSet<object>();
233
233
  const GPU_UID_FRAME_LIMIT = 64;
234
234
 
235
235
  /**
236
- * Names a render call by what three already calls it: the first camera call is the main pass, and a
237
- * nested call carries the scene name three or the reflector gave it.
236
+ * Names a render call by what three already calls it: a nested call carries the scene name three or
237
+ * the reflector gave it, and outside a scoped `renderWorld` draw the first camera call is the main pass.
238
238
  *
239
239
  * The name is read before the depth because a post pipeline makes its shadow or reflection passes at
240
- * world depth 0 — the composite quad is not a world call, so it does not hold one.
240
+ * world depth 0 — the composite quad is not a world call, so it does not hold one. A draw the game
241
+ * scoped with `renderWorld` names its authored root/camera directly, so three's shadow/reflection
242
+ * names still take priority and a standalone raw render retains the outermost-main convention.
241
243
  */
242
- function passKind(name: string, depth: number): FramePassKind {
244
+ function passKind(
245
+ scene: unknown,
246
+ camera: unknown,
247
+ name: string,
248
+ depth: number,
249
+ world: { scene: unknown; camera: unknown } | undefined,
250
+ ): FramePassKind {
243
251
  if (name.startsWith("Shadow Map")) return "shadow";
244
252
  if (/reflect/iu.test(name)) return "reflection";
253
+ if (world !== undefined)
254
+ return scene === world.scene && camera === world.camera ? "main" : "nested";
245
255
  return depth === 0 ? "main" : "nested";
246
256
  }
247
257
 
@@ -352,6 +362,7 @@ export class RenderPassBudget {
352
362
  readonly #original: (scene: unknown, camera: unknown) => void;
353
363
  readonly #frame: IRenderPassSample[] = [];
354
364
  readonly #stack: IPassFrame[] = [];
365
+ #world: { scene: unknown; camera: unknown } | undefined;
355
366
  /** How many non-quad render calls are open: the depth the camera pass is classified at. */
356
367
  #worldDepth = 0;
357
368
  /** Timestamp uids each render call allocated, keyed by the Three.js frame they belong to. */
@@ -377,7 +388,7 @@ export class RenderPassBudget {
377
388
  childTriangles: 0,
378
389
  entryDraws: counters.draws,
379
390
  entryTriangles: counters.triangles,
380
- kind: quad ? "nested" : passKind(name, this.#worldDepth),
391
+ kind: quad ? "nested" : passKind(scene, camera, name, this.#worldDepth, this.#world),
381
392
  name,
382
393
  };
383
394
  this.#stack.push(frame);
@@ -416,7 +427,7 @@ export class RenderPassBudget {
416
427
  };
417
428
  target.render = instrumented;
418
429
  this.#instrumentDraws(target.info);
419
- installed.add(target);
430
+ installed.set(target, this);
420
431
  }
421
432
 
422
433
  /**
@@ -456,6 +467,22 @@ export class RenderPassBudget {
456
467
  return new RenderPassBudget(target);
457
468
  }
458
469
 
470
+ /** The renderer's authored root/camera, including scene passes nested beneath post processing. */
471
+ static renderWorld(target: object, scene: unknown, camera: unknown, draw: () => void): void {
472
+ const budget = installed.get(target);
473
+ if (budget === undefined) {
474
+ draw();
475
+ return;
476
+ }
477
+ const previous = budget.#world;
478
+ budget.#world = { scene, camera };
479
+ try {
480
+ draw();
481
+ } finally {
482
+ budget.#world = previous;
483
+ }
484
+ }
485
+
459
486
  /**
460
487
  * The kind of the innermost render call currently running, or undefined outside one.
461
488
  *
@@ -1,4 +1,5 @@
1
1
  import type { Camera, Material, Matrix4, Object3D, Scene } from "three";
2
+ import type { Node } from "three/webgpu";
2
3
 
3
4
  import type { IGeometryOwnership } from "./geometry-capture.js";
4
5
  import type { MatrixWorldPass } from "./matrix-world.js";
@@ -15,6 +16,19 @@ import {
15
16
  import { ProjectionStability } from "./projection-stability.js";
16
17
  import { VelocityTracker } from "./render/velocity.js";
17
18
 
19
+ /**
20
+ * three r187's two node inputs on a scene. `@types/three` does not declare them, but the renderer
21
+ * reads both: `scene.fogNode` replaces the `scene.fog` factor (`NodeManager.getFogNode`,
22
+ * `renderers/common/nodes/NodeManager.js:636-641`, applied by `NodeMaterial.setupFog`,
23
+ * `materials/nodes/NodeMaterial.js:1150-1160`) and `scene.backgroundNode` replaces the background
24
+ * shader (`NodeManager.getBackgroundNode`, same file). The game authors them; the mirror has to
25
+ * carry them or the frame it draws is not the frame the game asked for.
26
+ */
27
+ interface ISceneNodeInputs {
28
+ fogNode?: Node | null;
29
+ backgroundNode?: Node | null;
30
+ }
31
+
18
32
  /**
19
33
  * An optimizer that the game never has to know about.
20
34
  *
@@ -425,6 +439,14 @@ export class SceneRenderProjection {
425
439
  mirrorScene.background = this.#source.background;
426
440
  mirrorScene.environment = this.#source.environment;
427
441
  mirrorScene.fog = this.#source.fog;
442
+ // A fog or background NODE is not part of `scene.fog`/`scene.background`: a mirror that copies
443
+ // only those two renders a frame the game never asked for. The platformer's height fog is one:
444
+ // the authored scene draws it, the mirror drew `scene.fog` alone, so the same game came out
445
+ // hazy under the native host and clear in the browser (PRD-617).
446
+ const sourceNodes = this.#source as Scene & ISceneNodeInputs;
447
+ const mirrorNodes = mirrorScene as Scene & ISceneNodeInputs;
448
+ mirrorNodes.fogNode = sourceNodes.fogNode ?? null;
449
+ mirrorNodes.backgroundNode = sourceNodes.backgroundNode ?? null;
428
450
  mirrorScene.backgroundBlurriness = this.#source.backgroundBlurriness;
429
451
  mirrorScene.backgroundIntensity = this.#source.backgroundIntensity;
430
452
  mirrorScene.environmentIntensity = this.#source.environmentIntensity;
@@ -1,10 +1,46 @@
1
1
  import type { IThreeNativeConfig } from "./config.js";
2
2
  import type { MatrixWorldMode } from "./matrix-world.js";
3
3
  import type { PlatformOS } from "./platform.js";
4
+ import type { IRendererOptions } from "./renderer.js";
4
5
  import { RESOLUTION_SCALER } from "./resolution-scaler.js";
5
6
 
6
7
  type RendererConfig = NonNullable<IThreeNativeConfig["renderer"]>;
7
8
 
9
+ /**
10
+ * What `defineGame({ renderer })` accepts: the project's portable renderer config (`threenative.config.ts`
11
+ * `renderer`, including its `android` block and `"auto"` scale) beside the live renderer options.
12
+ *
13
+ * One key for both. `defineGame` once took the portable config as `render` and the live options as
14
+ * `renderer`, so a game wrote `render: config.renderer` beside a second `renderer:` and the
15
+ * antialias and scale resolvers each fell back from one to the other. The scale is the one field
16
+ * the two disagreed on, and the portable form (a number or `"auto"`) is the superset.
17
+ */
18
+ export type GameRendererConfig = Omit<IRendererOptions, "resolutionScale" | "scaleSource"> &
19
+ RendererConfig;
20
+
21
+ const LEGACY_RENDER_KEY_MESSAGE =
22
+ 'TN_GAME_RENDER_KEY_RENAMED: defineGame({ render }) is now defineGame({ renderer }). Move the object to `renderer` with no other change: preferWebGPU, antialias, alphaAntialiasing, resolutionScale (a number in (0, 1] or "auto"), the android block, matrixWorld, projection and minimumProjectedPixels keep their names and meaning, and `config.renderer` from threenative.config.ts passes through unchanged. `scaleSource` is reported by the engine and is not an input. Where a game set both keys, `render` won, so merge them with the `render` values on top.';
23
+
24
+ /**
25
+ * Adopt the retired `render` key for one release, reporting the rename it names.
26
+ *
27
+ * Dropping the key silently would lose a game's scale, sampling and Android overrides; throwing on
28
+ * it refuses to boot every game written against 0.3.12, `config.renderer` and all. So the values are
29
+ * forwarded onto `renderer` — where a game set both, `render` won, so they go on top — and the
30
+ * rename is reported once with the guidance that names every field and its meaning.
31
+ */
32
+ export function adoptLegacyRenderKey<T extends object>(config: T): T {
33
+ const { render, ...rest } = config as T & { render?: unknown };
34
+ if (render === undefined) return config;
35
+ if (typeof render !== "object" || render === null)
36
+ throw new Error(
37
+ `TN_GAME_RENDER_KEY_INVALID: defineGame({ render }) must be an object, received ${typeof render}.`,
38
+ );
39
+ console.warn(LEGACY_RENDER_KEY_MESSAGE);
40
+ const renderer = (config as { renderer?: object }).renderer;
41
+ return { ...rest, renderer: { ...renderer, ...render } } as T;
42
+ }
43
+
8
44
  /** How the active drawing-buffer scale was arrived at, reported beside every fps number. */
9
45
  export type ScaleSource = "pinned" | "auto";
10
46
 
@@ -0,0 +1,37 @@
1
+ /**
2
+ * What a renderer is, asked in one place.
3
+ *
4
+ * The facade wraps either the owned C++ engine or upstream three, and four core subsystems used to
5
+ * answer that by probing the renderer's own `info` object with `"engine" in info` — a fact spelled
6
+ * in four files, so a rename in the engine's info table would have left them all reporting the wrong
7
+ * backend with nothing failing. This is the one reader.
8
+ *
9
+ * `kind` is the wrapper's own label (`"webgpu"` for either backend: three's WebGPU renderer can run
10
+ * a WebGL fallback behind it, which is `isWebGLFallbackRenderer`'s question, not this one).
11
+ */
12
+ export interface IRendererFacts {
13
+ /** The wrapper's backend label, as `OutputRenderer.kind` reports it. */
14
+ readonly kind: string;
15
+ /** Whether the owned engine is behind the facade, rather than upstream three. */
16
+ readonly ownedEngine: boolean;
17
+ }
18
+
19
+ /** The renderer shape these facts are read from: a `kind` label and the raw three renderer. */
20
+ export interface IRendererFactSource {
21
+ readonly kind?: string;
22
+ readonly raw?: unknown;
23
+ }
24
+
25
+ /**
26
+ * The facts about `renderer`, from its own `info` table.
27
+ *
28
+ * A renderer with no `info` at all, or one from upstream three, is not the owned engine. A test
29
+ * double may pass nothing, which is the same answer.
30
+ */
31
+ export function rendererFacts(renderer: IRendererFactSource | undefined): IRendererFacts {
32
+ const info = (renderer?.raw as { info?: { engine?: unknown } } | undefined)?.info;
33
+ return {
34
+ kind: renderer?.kind ?? "unknown",
35
+ ownedEngine: info !== undefined && info.engine !== undefined,
36
+ };
37
+ }