@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
@@ -1,3 +1,4 @@
1
+ import { readLaunchFlag } from "../debug.js";
1
2
  // Generated for you: ordinary Three.js; ThreeNative does not read this file. Delete or
2
3
  // rewrite it freely — every default in here is a starting point, not a framework look.
3
4
  //
@@ -14,13 +15,9 @@
14
15
  // tier. Those are arguments, supplied by `postprocessing.ts`, yours to change.
15
16
 
16
17
  import {
17
- ACESFilmicToneMapping,
18
- AgXToneMapping,
19
18
  type Camera,
20
- CustomToneMapping,
21
19
  type DirectionalLight,
22
20
  MaterialBlending,
23
- NeutralToneMapping,
24
21
  type PerspectiveCamera,
25
22
  type RenderTarget,
26
23
  type Scene,
@@ -39,7 +36,6 @@ import { sharpen } from "three/addons/tsl/display/SharpenNode.js";
39
36
  import { traa } from "three/addons/tsl/display/TRAANode.js";
40
37
  import {
41
38
  Fn,
42
- If,
43
39
  color,
44
40
  convertToTexture,
45
41
  cross,
@@ -76,17 +72,23 @@ import {
76
72
  } from "../render/chain.js";
77
73
  import { GIVisualize, type GIVisualizeMode } from "../render/gi-visualize.js";
78
74
  import type { TracedReflections } from "../render/traced-reflections.js";
75
+ import { rendererFacts } from "../renderer-facts.js";
79
76
  import { STARTUP_EXPOSURE } from "../renderer.js";
77
+ import { aoRefusal } from "./ao-admission.js";
80
78
  import { AO_MULTIBOUNCE_FIT, UNREAL_AO_MULTIBOUNCE_ALBEDO } from "./ao-multibounce.js";
81
79
  import { UNREAL_AO_REACH_PX } from "./ao-reach.js";
82
80
  import { AutoExposureNode, applyExposure } from "./auto-exposure.js";
81
+ import {
82
+ RENDERER_TONE_MAPPINGS,
83
+ type RendererToneMapping,
84
+ applyRendererToneMapping,
85
+ isRendererToneMapping,
86
+ } from "./default-tone-mapping.js";
83
87
  import { type IExposureSettings, exposureSettings } from "./exposure-settings.js";
84
88
  import {
85
89
  type ColorGradeOptions,
86
90
  FILMIC_CURVE,
87
91
  type IFilmicCurve,
88
- LUT_CLIP,
89
- installFilmicToneMapping,
90
92
  resolveColorGrade,
91
93
  } from "./filmic-tone-mapping.js";
92
94
  import { cacheFallback, giCache } from "./gi-registry.js";
@@ -111,9 +113,10 @@ export type ScreenSpaceAA = "smaa" | "fxaa" | "disabled";
111
113
 
112
114
  /**
113
115
  * Godot's `Environment.tonemap_mode`: the modes Three.js ships, plus `filmic`, the Unreal 5
114
- * default curve written in `tonemap.ts`.
116
+ * default curve written in `tonemap.ts`. The list itself is `RendererToneMapping`'s, one owner
117
+ * beside `applyRendererToneMapping`, so a mode this accepts is a mode the renderer can install.
115
118
  */
116
- export type TonemapMode = "aces" | "agx" | "filmic" | "neutral";
119
+ export type TonemapMode = RendererToneMapping;
117
120
 
118
121
  /**
119
122
  * SSGI sample budget. The three tiers are the presets SSGINode's own documentation
@@ -132,12 +135,21 @@ const SSGI_QUALITY: Record<SsgiQuality, { sliceCount: number; stepCount: number
132
135
  epic: { sliceCount: 8, stepCount: 16 },
133
136
  };
134
137
 
135
- const TONEMAP: Record<TonemapMode, number> = {
136
- aces: ACESFilmicToneMapping,
137
- agx: AgXToneMapping,
138
- filmic: CustomToneMapping,
139
- neutral: NeutralToneMapping,
140
- };
138
+ /**
139
+ * Whether this launch draws the transparent draws' own target (see `seesThrough` below).
140
+ *
141
+ * On unless a launch asks for it off: `TN_TRANSLUCENT=0`, `?tnTranslucent=0`, or the global
142
+ * `__tnTranslucent = false` a test sets. Only `0` and `false` count, so an old URL that never
143
+ * named the switch keeps the target. A frame without it takes the occlusion on its sheets, which
144
+ * is wrong to look at, so this is a measurement switch and not a look: a lane prices the pass by
145
+ * running the same pose both ways.
146
+ */
147
+ export function translucentTargetWanted(): boolean {
148
+ return !readLaunchFlag(
149
+ { environment: "TN_TRANSLUCENT", global: "__tnTranslucent", query: "tnTranslucent" },
150
+ "off",
151
+ );
152
+ }
141
153
 
142
154
  /**
143
155
  * Publishes this install's exposure readiness for the startup's first visible frame
@@ -767,10 +779,10 @@ export class WorldEnvironment {
767
779
  `Unknown ssgiQuality '${String(quality)}'. Use one of: ${Object.keys(SSGI_QUALITY).join(", ")}.`,
768
780
  );
769
781
  }
770
- const tonemapMode = options.tonemapMode ?? "aces";
771
- if (TONEMAP[tonemapMode] === undefined) {
782
+ const tonemapMode = options.tonemapMode ?? "filmic";
783
+ if (!isRendererToneMapping(tonemapMode)) {
772
784
  throw new Error(
773
- `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${Object.keys(TONEMAP).join(", ")}.`,
785
+ `Unknown tonemapMode '${String(tonemapMode)}'. Use one of: ${RENDERER_TONE_MAPPINGS.join(", ")}.`,
774
786
  );
775
787
  }
776
788
  resolveColorGrade(options.colorGrade);
@@ -895,31 +907,21 @@ export class WorldEnvironment {
895
907
  ? this.#options
896
908
  : { ...this.#options, autoExposureEnabled: false };
897
909
  const raw = renderer.raw as { toneMapping?: number; toneMappingExposure?: number };
898
- raw.toneMapping = TONEMAP[options.tonemapMode];
899
- if (options.tonemapMode === "filmic") {
900
- // The curve is this game's source, registered as three's custom tone mapping. A renderer
901
- // without a node library cannot run it; that frame keeps ACES and says so.
902
- const installed = installFilmicToneMapping(
903
- renderer.raw,
904
- {
905
- ...FILMIC_CURVE,
906
- ...options.filmicCurve,
907
- ...(lookDiagnostics.lutClipOn ? { lutClip: LUT_CLIP } : {}),
908
- },
909
- resolveColorGrade(options.colorGrade),
910
- );
911
- if (installed === undefined) {
912
- raw.toneMapping = ACESFilmicToneMapping;
913
- console.warn(
914
- `TN_TONEMAP ${JSON.stringify({ requested: "filmic", applied: "aces", reason: `renderer:${renderer.kind}` })}`,
915
- );
916
- }
917
- }
910
+ // One writer of `toneMapping` for the whole engine: the curve this game supplies reaches the
911
+ // same library the renderer's own default uses, and a renderer without a node library keeps
912
+ // ACES and reports `TN_TONEMAP` once, here or in the renderer.
913
+ applyRendererToneMapping(raw, options.tonemapMode, (line) => console.warn(line), {
914
+ curve: {
915
+ ...FILMIC_CURVE,
916
+ ...options.filmicCurve,
917
+ ...(lookDiagnostics.lutClipOff ? { lutClip: 0 } : {}),
918
+ },
919
+ grade: resolveColorGrade(options.colorGrade),
920
+ });
918
921
 
919
922
  // Temporal AA is the owned engine's: it jitters the camera and blends the frames ahead of every stage. Any other
920
923
  // renderer keeps the spatial filter, and the report says why.
921
- const engineInfo = (renderer.raw as { info?: object }).info;
922
- const ownedEngine = engineInfo !== undefined && "engine" in engineInfo;
924
+ const { ownedEngine } = rendererFacts(renderer);
923
925
  const temporalRefusal = !options.temporalAA
924
926
  ? undefined
925
927
  : renderer.kind !== "webgpu"
@@ -1020,14 +1022,26 @@ export class WorldEnvironment {
1020
1022
  const temporalReport = temporal
1021
1023
  ? (): Record<string, unknown> => ({
1022
1024
  method: "traa",
1023
- ...(engineInfo as { engine?: { temporal?: object } }).engine?.temporal,
1025
+ ...(renderer.raw as { info?: { engine?: { temporal?: object } } }).info?.engine?.temporal,
1024
1026
  })
1025
1027
  : undefined;
1026
- // Contact occlusion dims the light that comes from around. With the world cache baked the frame's indirect
1027
- // diffuse is known per pixel, so only that share takes the occlusion and the sun keeps its light, as
1028
- // Unreal's AO (indirect light only) leaves it. Without a cache (the three.js engine) the whole frame is dimmed.
1029
- const indirectOcclusion =
1030
- ownedEngine && giCache.irradiance !== undefined && options.gtaoIndirectOnly;
1028
+ // Contact occlusion dims the light that comes from around. The owned engine writes each pixel's indirect diffuse
1029
+ // light to its own target, so only that share takes the occlusion and the sun keeps its light, as Unreal's AO
1030
+ // (indirect light only) leaves it. Upstream three has no such target, so there the whole frame is dimmed.
1031
+ const indirectOcclusion = ownedEngine && options.gtaoIndirectOnly;
1032
+ // Both screen-space stages below darken the frame with an occlusion gathered at the opaque surface's depth, so both
1033
+ // must leave the draws composited over it alone (see the MRT's `translucent` output and `translucentFrame`).
1034
+ // `TN_TRANSLUCENT=0` or `?tnTranslucent=0` keeps the target off the frame — the occlusion then darkens the sheets
1035
+ // over the opaque surface, as it did before the target existed — so one launch can price the pass; a diagnostic,
1036
+ // never a look.
1037
+ const seesThrough = (options.ssgiEnabled || options.gtaoEnabled) && translucentTargetWanted();
1038
+ // Upstream three has no scene-wide translucent target, so each material writes its own: its output, premultiplied
1039
+ // by its alpha, and nothing at all from an opaque material (whose alpha is 1). The owned engine draws the
1040
+ // transparent draws into the target itself (renderer.cpp, planAux), so it declares no output for it.
1041
+ const translucentMaterial = (): Node<"vec4"> =>
1042
+ vec4(output.rgb.mul(diffuseColor.a), diffuseColor.a).mul(
1043
+ diffuseColor.a.lessThan(0.999).select(float(1), float(0)),
1044
+ );
1031
1045
  const scenePass = pass(scene, camera, { samples: options.samples });
1032
1046
  const resolutionSubrect =
1033
1047
  requested.length === 0 || resolutionSubrectRefusal !== undefined
@@ -1056,8 +1070,16 @@ export class WorldEnvironment {
1056
1070
  : {}),
1057
1071
  // AO leaves emission alone: an emitter's underside stays its own radiance (Unreal's AO is indirect only).
1058
1072
  ...(options.gtaoEnabled || options.ssgiEnabled ? { emissive } : {}),
1073
+ // The occlusion and the gather belong to the opaque surface. A translucent draw composites over it after the
1074
+ // opaque pass, so a sheet over an occluded corner took the corner's occlusion with it (a waterfall showed the
1075
+ // cliff's stripes). This target carries what those draws composited, and the two composites below add it back
1076
+ // instead of darkening it, as they already do for `emissive`. Upstream three writes it from each material's
1077
+ // own output; the owned engine draws those draws into it while the graph reads it (renderer.cpp, planAux).
1078
+ ...(seesThrough && !ownedEngine ? { translucent: translucentMaterial() } : {}),
1059
1079
  });
1060
1080
  sceneMrt.setBlendMode("normal", new BlendMode(MaterialBlending));
1081
+ if (seesThrough && !ownedEngine)
1082
+ sceneMrt.setBlendMode("translucent", new BlendMode(MaterialBlending));
1061
1083
  scenePass.setMRT(sceneMrt);
1062
1084
  }
1063
1085
  // Requested lazily, and this is not a micro-optimisation. **Asking a pass for `normal`,
@@ -1102,6 +1124,12 @@ export class WorldEnvironment {
1102
1124
  const gain = exposure === undefined ? float(options.exposure) : exposure.exposureNode;
1103
1125
  const frameGain = localExposure === undefined ? gain : gain.mul(localExposure.gainNode);
1104
1126
  const exposed = applyExposure(colour, frameGain);
1127
+ // What the transparent draws composited over the frame, in the frame's own units: scene-referred, so it takes the
1128
+ // exposure multiplier the emitted radiance takes. The occlusion darkens the opaque surface only, and this part is
1129
+ // added back instead (the `emissive` restore's twin). A frame that runs neither stage never asks for it.
1130
+ const translucentFrame: Node<"vec3"> = seesThrough
1131
+ ? textureNode("translucent").rgb.mul(gain)
1132
+ : vec3(0);
1105
1133
  let released = false;
1106
1134
  const releaseGraph = (): void => {
1107
1135
  if (released) return;
@@ -1159,7 +1187,7 @@ export class WorldEnvironment {
1159
1187
  build: (input) => {
1160
1188
  // The gather reads the lit frame at each ray's hit, so the frame is materialised once and reused.
1161
1189
  const base = convertToTexture(input);
1162
- const wasmEngine = "engine" in (renderer.raw as { info: object }).info;
1190
+ const wasmEngine = rendererFacts(renderer).ownedEngine;
1163
1191
  // Harness: on the owned engine the gather also answers for the tier below it (the world-space cache), so
1164
1192
  // a ray that hits returns `hit - cache` and the two never add the same light twice (Lumen's tiering,
1165
1193
  // Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp).
@@ -1238,8 +1266,9 @@ export class WorldEnvironment {
1238
1266
  // The gathered light is incident radiance (E / pi). The surface returns it times its own
1239
1267
  // albedo, which the scene pass writes as the `diffuseColor` target, and a metal returns none
1240
1268
  // of it as diffuse. `ssgiIntensity` is the game's dial on that term.
1241
- // The owned engine's gather answers occlusion with a constant 1 (GTAO is its own stage): nothing to denoise.
1242
- const occlusion = wasmEngine ? gi.getAONode() : giDenoise(gi.getAONode());
1269
+ // Both engines answer the occlusion from their own gather, and both are denoised: the gather traces a few
1270
+ // rays a pixel, so an undenoised occlusion reads as a speckle rather than a shadowed corner.
1271
+ const occlusion = giDenoise(gi.getAONode());
1243
1272
  const indirect = giDenoise(gi.getGINode());
1244
1273
  if (options.denoiseEnabled && options.ssgiDenoiseRadius !== undefined)
1245
1274
  (indirect as typeof indirect & { radius: { value: number } }).radius.value =
@@ -1248,8 +1277,9 @@ export class WorldEnvironment {
1248
1277
  .rgb.mul(float(1).sub(metal().r))
1249
1278
  .mul(indirect.rgb)
1250
1279
  .mul(options.ssgiIntensity);
1251
- // The gather's own AO leaves emission alone too (see the GTAO stage).
1252
- const emitted = textureNode("emissive").rgb.mul(gain);
1280
+ // The gather's own AO leaves emission alone too (see the GTAO stage), and a translucent draw's own colour
1281
+ // is in the same position: the gather answered for the surface behind it.
1282
+ const emitted = textureNode("emissive").rgb.mul(gain).add(translucentFrame);
1253
1283
  // The contact term multiplied the frame before this stage ran, and the correction below is the one
1254
1284
  // part of the light that frame never carried: it takes the same factor, or a hit darker than the
1255
1285
  // cache subtracts more than the frame still holds and a lit floor under a sphere clips to black.
@@ -1283,6 +1313,19 @@ export class WorldEnvironment {
1283
1313
  releaseAo = () => {};
1284
1314
  },
1285
1315
  build: (input) => {
1316
+ // The reach form occludes indirect light only, so a frame that cannot tell its indirect share apart (upstream
1317
+ // three with no baked world cache) cannot run it: the whole-frame multiply it would fall back to darkens the sun.
1318
+ const refusal = aoRefusal({
1319
+ reach: options.gtaoRadius === undefined,
1320
+ indirectOnly: options.gtaoIndirectOnly,
1321
+ // The preset's own declaration covers the frame whose bake has not finished when the chain is built:
1322
+ // the gather's fallback reads the cache at render time, and the registration is the other signal.
1323
+ hasIndirect:
1324
+ ownedEngine ||
1325
+ options.finalGatherMethod !== "none" ||
1326
+ giCache.irradiance !== undefined,
1327
+ });
1328
+ if (refusal !== undefined) throw new Error(refusal);
1286
1329
  // GTAO rebuilds the normal from the depth, so it agrees with the depth's facets. The pass's
1287
1330
  // smooth vertex normal against a faceted depth (a 32-sided capsule) read as one dark stripe per facet and a
1288
1331
  // stair-step band under the cap; the denoiser, GTAO scale and radius did not change them.
@@ -1441,63 +1484,30 @@ export class WorldEnvironment {
1441
1484
  indirectOcclusion && options.gtaoMultiBounceAlbedo > 0 ? bounce() : undefined;
1442
1485
  contactOcclusion = keeps ?? occlusion.r;
1443
1486
  // Emission is radiance a surface gives off, not light it receives: AO keeps it, as Unreal's AO darkens only
1444
- // indirect light. The emitted part passes at full weight; the rest takes the occlusion.
1487
+ // indirect light. The emitted part passes at full weight; the rest takes the occlusion. A translucent draw's
1488
+ // own colour is in the same position: the occlusion was gathered for the surface behind it.
1445
1489
  // The chain reads exposed light, so the emitted radiance takes the frame's gain too.
1446
- const emitted = textureNode("emissive").rgb.mul(gain);
1490
+ const emitted = textureNode("emissive").rgb.mul(gain).add(translucentFrame);
1447
1491
  // Scale the colour only: `input.mul(occlusion.r)` scales alpha too, which darkens the frame a second time.
1448
1492
  const composited = input
1449
1493
  .mul(vec4(occlusion.r, occlusion.r, occlusion.r, 1))
1450
1494
  .add(vec4(emitted.mul(float(1).sub(occlusion.r)), 0));
1451
- const cache = indirectOcclusion ? cacheFallback(view) : undefined;
1452
- if (cache === undefined) return composited;
1453
- // The pixel's view-space position from its depth and the camera's projection terms, read live each
1454
- // render: the engine has no getViewPosition, and a post quad's own camera nodes are the quad's.
1455
- const term = (index: number) =>
1456
- uniform(view.projectionMatrix.elements[index] ?? 0).onRenderUpdate(
1457
- () => view.projectionMatrix.elements[index] ?? 0,
1458
- );
1459
- const [p0, p5, p8, p9, p10, p14] = [
1460
- term(0),
1461
- term(5),
1462
- term(8),
1463
- term(9),
1464
- term(10),
1465
- term(14),
1466
- ];
1467
- const compose = Fn(() => {
1468
- const coordinate = uv();
1469
- const result = vec3(composited.rgb).toVar();
1470
- const sceneDepth = depth().sample(coordinate).r;
1471
- const sceneNormal = normal().sample(coordinate).xyz;
1472
- // The sky and a draw the normal pass skips (an unlit material) keep the whole-frame multiply.
1473
- If(sceneDepth.lessThan(1).and(sceneNormal.dot(sceneNormal).greaterThan(0.25)), () => {
1474
- const viewZ = p14.negate().div(sceneDepth.add(p10));
1475
- const ndc = vec2(
1476
- coordinate.x.mul(2).sub(1),
1477
- float(1).sub(coordinate.y).mul(2).sub(1),
1478
- );
1479
- const position = vec3(
1480
- viewZ.negate().mul(ndc.x.add(p8)).div(p0),
1481
- viewZ.negate().mul(ndc.y.add(p9)).div(p5),
1482
- viewZ,
1483
- );
1484
- // The indirect diffuse the material added: the cache's irradiance times the albedo, in the frame's
1485
- // units (the gather's own fallback reads it the same way). Only it takes the occlusion, and the
1486
- // result is never darker than the whole-frame multiply.
1487
- const indirect = albedo()
1488
- .rgb.mul(float(1).sub(metal().r))
1489
- .mul(cache(position, sceneNormal.normalize()))
1490
- .mul(frameGain);
1491
- result.assign(
1492
- max(
1493
- input.rgb.sub(indirect.mul(float(1).sub(keeps ?? occlusion.r))),
1494
- composited.rgb,
1495
- ),
1496
- );
1497
- });
1498
- return vec4(result, input.a);
1499
- });
1500
- return compose();
1495
+ if (!indirectOcclusion) return composited;
1496
+ // The indirect diffuse light the materials added, from the engine's own target (hemisphere, ambient,
1497
+ // environment and baked irradiance, never a direct light), in the frame's units. Only it takes the
1498
+ // occlusion, as Unreal's composite multiplies only the indirect term by the AO (UE 5.8.3:
1499
+ // Engine/Shaders/Private/DiffuseIndirectComposite.usf:195). An unlit draw and the sky add none, so
1500
+ // they keep their colour. The result is never darker than the whole-frame multiply.
1501
+ const indirect = textureNode("indirectDiffuse").rgb.mul(frameGain);
1502
+ // Only the opaque part of the frame carries that indirect light: a draw composited over it did not receive it.
1503
+ const opaque = input.rgb.sub(translucentFrame);
1504
+ return vec4(
1505
+ max(
1506
+ opaque.sub(indirect.mul(float(1).sub(keeps ?? occlusion.r))).add(translucentFrame),
1507
+ composited.rgb,
1508
+ ),
1509
+ input.a,
1510
+ );
1501
1511
  },
1502
1512
  }),
1503
1513
  stage({
package/src/loop.ts CHANGED
@@ -356,6 +356,35 @@ export class FixedStepLoop {
356
356
  this.#settleSteps = settleSteps;
357
357
  this.#lastTime = Number.POSITIVE_INFINITY;
358
358
  }
359
+
360
+ /**
361
+ * Spend the settling pass now, from a caller that knows the world's scene is live.
362
+ *
363
+ * A freeze names the steps the world needs; the loop waits for the first live frame to spend
364
+ * them. On a game that boots through a loading scene that frame is often still the loading
365
+ * scene: the steps ran, the world's own clock never saw them, and how many were lost depended on
366
+ * how fast the machine booted. Measured on the sailing template's pose at the same anchor, the
367
+ * native engine was 60 steps (1.0 s) ahead of the legacy one for exactly this reason. A runner
368
+ * freezes with zero steps and calls this once the start scene has entered, so the settle lands
369
+ * on the world on every engine.
370
+ */
371
+ settleNow(steps = FROZEN_SETTLE_STEPS): void {
372
+ if (!Number.isInteger(steps) || steps < 0)
373
+ throw new Error("settleNow steps must be a non-negative integer.");
374
+ this.#primePending = false;
375
+ if (steps === 0) return;
376
+ // `advance()` freezes the clock, because a counted step is a statement that the run counts
377
+ // ticks. A settle asked of a loop that was live makes no such statement — a wall-clock run
378
+ // measures frames — so it hands the loop back the way it found it instead of leaving a profile
379
+ // of a game that stopped playing.
380
+ const wasFrozen = this.#clockFrozen;
381
+ this.advance(steps);
382
+ if (wasFrozen) return;
383
+ // The transition back banks no elapsed time, exactly as `_setClockMode("wall-clock")` does:
384
+ // the 60 steps are already on the tick count, and the next live frame owns the time after it.
385
+ this.#clockFrozen = false;
386
+ this.#lastTime = undefined;
387
+ }
359
388
  /** True once the live clock no longer drives the simulation. */
360
389
  get clockFrozen(): boolean {
361
390
  return this.#clockFrozen;
@@ -233,17 +233,13 @@ type NormalElements = readonly [
233
233
  * Positions of one part, placed, written into `values` at `at`.
234
234
  *
235
235
  * The expression is three's `Vector3.applyMatrix4` term for term over the same elements in the same
236
- * order, including its homogeneous divide, so a merged buffer holds the values it held before. The
237
- * second half of it is what `setXYZ` wrote back into the part's own typed array before the
238
- * de-quantizing copy read it again: `normalize` rounds into the channel's own range — the scratch
239
- * store keeps a value outside that range wrapping exactly as three's store did — and `denormalize`
240
- * reads it back as a float.
236
+ * order, including its homogeneous divide. A placed position leaves a quantized channel's range, so
237
+ * it goes straight to float and never back into the channel's own type.
241
238
  */
242
239
  function writePosition(
243
240
  channel: IChannel,
244
241
  indices: Uint16Array | Uint32Array | null,
245
242
  elements: PlacementElements | null,
246
- scratch: IScratch | null,
247
243
  values: Float32Array,
248
244
  at: number,
249
245
  ): void {
@@ -271,14 +267,6 @@ function writePosition(
271
267
  pz = (e[2] * x + e[6] * y + e[10] * z + e[14]) * w;
272
268
  }
273
269
  const out = at + vertex * 3;
274
- if (scratch !== null) {
275
- scratch[0] = Math.round(px * scale);
276
- scratch[1] = Math.round(py * scale);
277
- scratch[2] = Math.round(pz * scale);
278
- px = Math.max((scratch[0] as number) / scale, -1);
279
- py = Math.max((scratch[1] as number) / scale, -1);
280
- pz = Math.max((scratch[2] as number) / scale, -1);
281
- }
282
270
  values[out] = px;
283
271
  values[out + 1] = py;
284
272
  values[out + 2] = pz;
@@ -399,6 +387,15 @@ function scratchOf(array: IRawNumbers): IScratch | null {
399
387
  return null;
400
388
  }
401
389
 
390
+ /** A channel as plain float, read through its own accessors so normalization and interleaving resolve. */
391
+ function floatCopy(attribute: BufferAttribute | InterleavedBufferAttribute): BufferAttribute {
392
+ const values = new Float32Array(attribute.count * attribute.itemSize);
393
+ for (let index = 0; index < attribute.count; index += 1)
394
+ for (let component = 0; component < attribute.itemSize; component += 1)
395
+ values[index * attribute.itemSize + component] = attribute.getComponent(index, component);
396
+ return new BufferAttribute(values, attribute.itemSize);
397
+ }
398
+
402
399
  function flatten(
403
400
  part: IMergePart,
404
401
  paint: boolean,
@@ -406,6 +403,10 @@ function flatten(
406
403
  deindex: boolean,
407
404
  ): BufferGeometry {
408
405
  const placed = part.geometry.clone();
406
+ // Placed before it is float, a quantized position is stored back into its own range and clamps.
407
+ const position = placed.getAttribute("position");
408
+ if (position !== undefined && (!(position.array instanceof Float32Array) || position.normalized))
409
+ placed.setAttribute("position", floatCopy(position));
409
410
  const matrix = placementMatrix(part);
410
411
  if (matrix !== undefined) placed.applyMatrix4(matrix);
411
412
  const flat = deindex && placed.index !== null ? placed.toNonIndexed() : placed;
@@ -428,17 +429,13 @@ function flatten(
428
429
  !("isInterleavedBufferAttribute" in attribute)
429
430
  )
430
431
  continue;
431
- const values = new Float32Array(attribute.count * attribute.itemSize);
432
- for (let index = 0; index < attribute.count; index += 1)
433
- for (let component = 0; component < attribute.itemSize; component += 1)
434
- values[index * attribute.itemSize + component] = attribute.getComponent(index, component);
435
- flat.setAttribute(name, new BufferAttribute(values, attribute.itemSize));
432
+ flat.setAttribute(name, floatCopy(attribute));
436
433
  }
437
- const position = flat.getAttribute("position");
438
- if (!paint || position === undefined) return flat;
434
+ const flatPosition = flat.getAttribute("position");
435
+ if (!paint || flatPosition === undefined) return flat;
439
436
  const tone = new Color(part.color);
440
- const painted = new Float32Array(position.count * 3);
441
- for (let vertex = 0; vertex < position.count; vertex += 1) {
437
+ const painted = new Float32Array(flatPosition.count * 3);
438
+ for (let vertex = 0; vertex < flatPosition.count; vertex += 1) {
442
439
  painted[vertex * 3] = tone.r;
443
440
  painted[vertex * 3 + 1] = tone.g;
444
441
  painted[vertex * 3 + 2] = tone.b;
@@ -602,7 +599,6 @@ function writeChannel(
602
599
  indices,
603
600
  // quality-allow: Matrix4.elements is number[] in three's types and always 16 long.
604
601
  matrix === undefined ? null : (matrix.elements as unknown as PlacementElements),
605
- scratchOf(channel.array),
606
602
  values,
607
603
  at,
608
604
  );