@threenative/core 0.3.11 → 0.3.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -0,0 +1,370 @@
1
+ /**
2
+ * What a {@link VirtualShadowNode} is asked for, what it reports, and the default of every knob.
3
+ *
4
+ * Types and defaults only: the node owns the mechanism these describe.
5
+ */
6
+
7
+ /**
8
+ * Options for {@link VirtualShadowNode}. Every value is a mechanism parameter; the light's own
9
+ * `shadow` keeps bias, normalBias, intensity, map type and filter, exactly as with a stock shadow.
10
+ */
11
+ export interface IVirtualShadowOptions {
12
+ /**
13
+ * Half-width of each clip level's window in world units, finest first and strictly
14
+ * increasing. Default `[16, 48, 144]`: three windows, each three times wider than the last.
15
+ */
16
+ readonly clipExtents?: readonly number[];
17
+ /**
18
+ * The widest step between two levels, default 2: where `clipExtents` jump further, levels are
19
+ * inserted at even ratios, as UE 5.8.3 doubles every clipmap level (`GetLevelRadius`,
20
+ * Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapClipmap.cpp:175-179). A
21
+ * receiver crossing a level edge then changes texel size by at most this ratio: across `[24, 320]`
22
+ * the texel grew 13 times at once and every tree on the edge flipped from self-shadowed to flat
23
+ * lit. Per-level lists (`mapSize`, `refreshStep`, `selectionGuard`, `invalidationDelay`) give an
24
+ * inserted level the value of the authored level it leads into. `Infinity` keeps the authored
25
+ * levels as they are, and `TN_VIRTUAL_SHADOW_OVERRIDE` reports it.
26
+ */
27
+ readonly maxLevelRatio?: number;
28
+ /**
29
+ * Resolution bias in stops, default 0. Mirrors Unreal's
30
+ * `r.Shadow.Virtual.ResolutionLodBiasDirectional`; a quality tier sets it. With the default map
31
+ * sizes each stop doubles every level's texel: `-1` halves it (twice the resolution), `-1.5` is
32
+ * 2.83 times finer, a positive bias coarsens it. With an authored `mapSize` the finest window
33
+ * scales by `2 ** bias` instead and every coarser level keeps its extent; a bias that would push
34
+ * that window past the next level throws.
35
+ */
36
+ readonly resolutionLodBiasDirectional?: number;
37
+ /**
38
+ * Texels per level edge: one number for every level, or one per level, finest first. Default:
39
+ * Unreal's clipmap rule, measured on the camera and viewport that first read the shadow, so a
40
+ * receiver's texel is at most `2^(1 + bias)` of its own screen pixels (`clipmapMapSizes`). Set it to
41
+ * hold fixed sizes.
42
+ */
43
+ readonly mapSize?: number | readonly number[];
44
+ /**
45
+ * The page budget of the default map sizes, in 128² pages over all levels, default 4096 (Unreal's
46
+ * `r.Shadow.Virtual.MaxPhysicalPages` at Epic). Sizes over it raise the bias until they fit.
47
+ */
48
+ readonly maxPhysicalPages?: number;
49
+ /**
50
+ * Texels per edge of each level's mover map — the map tracked casters draw into every frame.
51
+ * Default: `mapSize`, the cached levels' own density, so a caster keeps the edge it had at rest
52
+ * while it moves and does not pop to a crisper one when it settles. Lower it to buy back fill
53
+ * on a weak GPU; the soft edge it costs is on the mover only.
54
+ */
55
+ readonly moverMapSize?: number;
56
+ /**
57
+ * Fraction of a level's extent inside which a fragment still selects that level, `(0, 1]`,
58
+ * default 0.9 — the outer ring falls through to the next level so the edge is never sampled.
59
+ * `selectionGuard` minus `refreshStep`, since a window trails its centre by that much. One value
60
+ * for every level, or one per level finest first, the last entry standing in for the rest.
61
+ */
62
+ readonly selectionGuard?: number | readonly number[];
63
+ /**
64
+ * Fraction of a level's extent its window may trail the followed centre by before it re-renders,
65
+ * `[0, selectionGuard)`, default 0.125 — `refreshStep: 0` keeps the old one-texel step. The step
66
+ * is rounded to a whole number of that level's texels, so a walking camera re-renders a level
67
+ * ~`1/refreshStep` times less often while the shadow texels stay on one fixed world grid. Costs
68
+ * that much of `selectionGuard`, which it is already reduced by, so a window never reaches past
69
+ * the trailing edge of a map rendered before the centre moved. One value for every level, or one
70
+ * per level finest first, the last entry standing in for the rest — the fine level is the one a
71
+ * walking camera re-renders most, so it is the one that wants the larger step.
72
+ */
73
+ readonly refreshStep?: number | readonly number[];
74
+ /**
75
+ * Let a level buy itself a wider `refreshStep` out of what its own last render cost, default true.
76
+ *
77
+ * A level render is a whole scene draw, so the engine cannot know what one is worth until it has
78
+ * paid for it: the node measures the draw it just took and smooths that reading, and a level whose
79
+ * smoothed cost is a large share of the frame period is re-rendered less often. This is automatic
80
+ * because the value it reacts to is a measurement, not a setting — a game sets nothing, and a
81
+ * cheap level is never widened and behaves exactly as before. The widened trail is capped by the
82
+ * window's own margin, so the camera stays inside the region that level serves and everything that
83
+ * level serves stays inside the map; a level with no such margin is never widened at all.
84
+ *
85
+ * `false` puts every level back on the `refreshStep` it was given, which is also what a harness
86
+ * that wants to count today's renders uses.
87
+ * `?tnAdaptiveRefresh=0` in the page URL makes the default `false` from the node's first setup.
88
+ */
89
+ readonly adaptiveRefresh?: boolean;
90
+ /**
91
+ * Fraction of the display period a level's smoothed render cost may take before its refresh trail
92
+ * widens, `(0, 1]`, default 0.4.
93
+ *
94
+ * The period is the frame's own `deltaTime`, capped at the 60 fps frame (16.7 ms). The cap is what
95
+ * keeps the budget honest: the frame that renders an expensive level is itself long because of that
96
+ * render, so reading the share against its own inflated delta would count the cost twice and let
97
+ * the very level that needs adapting pass its own test. At 60 Hz the cap is the frame itself; on a
98
+ * 120 Hz panel the same render is twice the share it is at 60; below 60 the cap holds the budget
99
+ * at the 60 fps frame rather than growing with the stall. Below the share nothing changes at all,
100
+ * and above it the trail widens in proportion to the overshoot,
101
+ * because that is the ratio between what the level costs and what a frame can afford to spend on
102
+ * it — a level four times over the share refreshs about four times less often, until the cap
103
+ * below it runs out.
104
+ */
105
+ readonly expensiveRefreshShare?: number;
106
+ /**
107
+ * Raise the finest level's texel size gate while its own render is too expensive for the frame, default
108
+ * true.
109
+ *
110
+ * The same measurement adaptive refresh reads — the smoothed cost of the level's own last render,
111
+ * against the share of the frame it may take — drives a second, independent adaptation: a level
112
+ * whose render is over budget sizes its gate up in steps of 1.5 until it is affordable again, up
113
+ * to 8 times the configured gate, and halves it back toward 1 once the render is comfortably under
114
+ * half the budget. The gate only ever judges a caster by its size (see `minCasterTexels`), so this
115
+ * drops the tiniest props first and never a building, and a level that is cheap is never touched:
116
+ * it stays at scale 1 and submits exactly what it did before.
117
+ *
118
+ * Coarse levels always stay at scale 1 so resolved casters survive the handover.
119
+ * `false` pins every level at scale 1, which is also what a harness that wants today's draw
120
+ * counts uses.
121
+ */
122
+ readonly adaptiveCasterGate?: boolean;
123
+ /**
124
+ * How long a level waits after its own last render before an invalidation may re-render it, in
125
+ * seconds. One value for every level, or one per level finest first, the last entry standing in
126
+ * for the rest. Default `0.25 * extent / finestExtent` — 0.25 s, 1 s and 3.33 s for extents
127
+ * 24 / 96 / 320 — and `0` renders on the very next frame, which is what the node did before.
128
+ *
129
+ * A streamed world invalidates its shadows on every residency update, and a cell admitted at the
130
+ * ring edge lands in the coarsest window: the level that redraws for it is the one paying for the
131
+ * whole ring's wide casters, ten times a second where movement alone asks for two. A level
132
+ * waiting out its delay keeps the map and window it has, which is already right for every static
133
+ * caster in it, so only a newly streamed caster is missing — the trade is that a far tree's
134
+ * shadow can appear up to the delay late (3.33 s at extent 320, invisible on a level whose texel
135
+ * is wider than the tree). A window that moved is never delayed: that is a different reason, and
136
+ * it is not this option's.
137
+ */
138
+ readonly invalidationDelay?: number | readonly number[];
139
+ /**
140
+ * How far behind the window centre each level camera sits, in world units. Default 200. An
141
+ * explicit `lightDistance` *and* `depthRange` switch the level's light-space depth off the derived
142
+ * span below and back onto this pair, so a game that knows its own world sizes can still say so.
143
+ */
144
+ readonly lightDistance?: number;
145
+ /**
146
+ * Depth range each level camera covers past its centre, in world units. Default 400. Read only
147
+ * together with `lightDistance`; on its own the span is still derived.
148
+ */
149
+ readonly depthRange?: number;
150
+ /**
151
+ * Texels of a level a caster must cover before it draws into that level, default 1.5. A level's
152
+ * texel is `2 * extent / mapSize`, so the finest levels keep everything and the coarse ones keep
153
+ * only what they can resolve: a fern is a whole number of texels in a 48 m window and a fraction
154
+ * of one in a 640 m window, so it stops being drawn there and the shadow it casts is the ground
155
+ * cover's own, not its silhouette's. Set 0 to draw every caster into every level.
156
+ */
157
+ readonly minCasterTexels?: number;
158
+ /** Follow the framed receiving surface when the eye is more than one fine extent above it.
159
+ * Default true; false keeps eye follow for every camera. Walking cameras keep eye follow.
160
+ */
161
+ readonly followViewFocus?: boolean;
162
+ /**
163
+ * The smallest ratio of a level's light-space height to its width, `(0, 1]`, default 1 (square levels).
164
+ * A low sun stretches a shadow texel along the floor by `1 / sin(elevation)`. A value under 1 shrinks
165
+ * the height to `sin(elevation)` times the width, never under this value, so a texel covers the same
166
+ * floor area at any sun height. The costs: a wall taller than a level's height is read from a wider
167
+ * level, a level centred on the eye holds the floor only about `eye height / tan(elevation)` from the
168
+ * camera, and a wide filter disc (a source angle near 0.7 degrees) crosses the level's top and bottom
169
+ * edge and leaves a lit patch in a thin shadow (PRD-634, sun 4 ramp), so it is an opt-in.
170
+ */
171
+ readonly minWindowAspect?: number;
172
+ /** Measure receiver-plane slope across each level's texel footprint to prevent coarse acne.
173
+ * Default true; false preserves only the authored bias. Custom filterNode owns its footprint.
174
+ */
175
+ readonly receiverPlaneBias?: boolean;
176
+ /**
177
+ * Draw registered AutoLOD chains with a coarser rung past the finest level, default true. A level
178
+ * takes the coarsest rung whose geometric error is within one of its texels, and never a rung
179
+ * finer than the main pass shows; where no rung is that accurate the caster keeps its geometry.
180
+ * Alpha-tested and transparent casters keep casting on every level that resolves their bounds;
181
+ * dropping their whole shadow at the fine window edge loses canopy and fences.
182
+ * Geometry swaps are restored before the next level, mover map and main pass.
183
+ */
184
+ readonly shadowLodBias?: boolean;
185
+ /**
186
+ * The most error, in texels of a level, that a coarser rung may have on that level, default 1.
187
+ * A rung within a texel is as good as the full mesh at that resolution; a larger budget draws
188
+ * fewer triangles and shows facets on a shadow's edge, and `Infinity` draws the coarsest rung on
189
+ * every level past the finest. Read only with `shadowLodBias`.
190
+ */
191
+ readonly shadowLodTexels?: number;
192
+ /**
193
+ * Redraw only the pages an invalidation dirtied, default true. A level whose window did not move
194
+ * and whose asks named under half its pages renders those rectangles alone: pages casters were
195
+ * removed from are put back to the far plane first, pages casters streamed into are just drawn.
196
+ * `false` renders the whole level for every invalidation, as before. A VSM shadow map always
197
+ * renders whole, because its blur pass reads the entire map.
198
+ */
199
+ readonly partialRedraw?: boolean;
200
+ /**
201
+ * Quiet frames an automatically detected mover must exceed before it goes back into the cached
202
+ * levels, default 100 (Unreal's `FramesStaticThreshold`: it settles on quiet frame 101). A caster whose world matrix, instance matrix or
203
+ * deformation changed is drawn through the mover maps without a `trackCaster` call; this is how
204
+ * long it must hold still before its shadow is baked into the cache again. Positive integer.
205
+ */
206
+ readonly staticAfterFrames?: number;
207
+ /** Print the `TN_VIRTUAL_SHADOW` line every `markerEvery` frames; `false` silences it. Default 300. */
208
+ readonly marker?: boolean | number;
209
+ }
210
+
211
+ /** Per-frame counters, readable any time through {@link VirtualShadowNode.stats}. */
212
+ export interface IVirtualShadowStats {
213
+ readonly frame: number;
214
+ readonly levels: number;
215
+ /** Levels whose window moved this frame and were re-rendered. */
216
+ readonly moved: number;
217
+ /** Levels re-rendered because `invalidateAll()` or explicit tracker invalidation asked for it. */
218
+ readonly invalidated: number;
219
+ /** Tracked casters, as of this frame. */
220
+ readonly movers: number;
221
+ /**
222
+ * Casters the node classified as movers by measuring them, as of this frame: a world or instance
223
+ * matrix that changed, or a deforming mesh. Counted apart from {@link movers}, which is `trackCaster`.
224
+ */
225
+ readonly autoMovers: number;
226
+ /**
227
+ * Static-to-mover and mover-to-static changes of those casters over the node's lifetime. Each one
228
+ * asks the levels for one region redraw, never a full one.
229
+ */
230
+ readonly autoTransitions: number;
231
+ /**
232
+ * Mean JS time of the classification scan per frame, in milliseconds, over the node's lifetime.
233
+ * It is the number the scan's 0.05 ms budget is judged against.
234
+ */
235
+ readonly autoScanMs: number;
236
+ /** Mover maps rendered this frame: one per level when at least one caster is tracked. */
237
+ readonly moverRenders: number;
238
+ /** Levels served from their cached map this frame. */
239
+ readonly cached: number;
240
+ /** Levels rendered this frame, for any reason. */
241
+ readonly rendered: number;
242
+ /**
243
+ * Levels that wanted a render this frame and did not get one, because the node renders at most
244
+ * one level per frame. They keep the map they already have and come due again next frame.
245
+ */
246
+ readonly deferred: number;
247
+ /**
248
+ * Levels holding a redraw for an invalidation that is still inside its own `invalidationDelay`,
249
+ * so this frame is not the frame they render on. They keep the map they have, which is right for
250
+ * every static caster in it: only a caster streamed in since is missing, and the cumulative
251
+ * `coalesced` below is what is being waited out.
252
+ */
253
+ readonly held: number;
254
+ /** Fraction of levels served from cache over the node's lifetime. */
255
+ readonly reuseRatio: number;
256
+ /**
257
+ * Level renders over the node's lifetime, for any reason. `byMove` and `byInvalidation` are the two
258
+ * the node has — a window that moved, and an invalidation that asked and waited out its delay — and
259
+ * they add up to this exactly, because a render the single per-frame budget defers is counted
260
+ * against the reason that queued it and not again when it is finally taken.
261
+ */
262
+ readonly rendersTotal: number;
263
+ /** Of those, the renders taken because a level's window moved. */
264
+ readonly byMove: number;
265
+ /**
266
+ * Pages every level's window travelled between its renders, over the node's lifetime: the sum of
267
+ * `|ΔminX| + |ΔminY|` at each render. Unlike `byMove` it does not depend on how many frames sampled
268
+ * the path, so two runs of one route at different frame rates report the same number.
269
+ */
270
+ readonly windowSteps: number;
271
+ /** Of those, the renders taken because an invalidation asked and its level's delay had passed. */
272
+ readonly byInvalidation: number;
273
+ /** Of the renders taken for an invalidation (`byInvalidation`), those whose dirty set held only streamed-in casters. */
274
+ readonly byAdmission: number;
275
+ /** Of the renders taken for an invalidation, those whose dirty set held anything else: a removed caster, a region-less ask, a caster flag change. */
276
+ readonly byEviction: number;
277
+ /** Pages the dirty set held at each render, summed over the node's lifetime. A window move counts the whole level. */
278
+ readonly pagesDirty: number;
279
+ /** Pages each render actually drew, summed over the node's lifetime. Equals pagesDirty once a partial redraw exists. */
280
+ readonly pagesRedrawn: number;
281
+ /**
282
+ * Invalidation asks that cost no render of their own, over the node's lifetime: absorbed by a
283
+ * render the level was taking anyway for its window, or merged into an ask already waiting out
284
+ * that level's delay. The two of these are the shape of the win — with the default delays a walk
285
+ * asks once a second and renders about that often, and every ask in between is counted here.
286
+ */
287
+ readonly coalesced: number;
288
+ /**
289
+ * The same four counters per level, finest first: which window moved, which invalidation asked
290
+ * for a redraw, which level took the frame's single render, and which wanted one and did not get
291
+ * it. One entry per level per frame, so a harness reading this — or the `TN_VIRTUAL_SHADOW`
292
+ * marker line, which carries it — can see which level a walk keeps re-rendering instead of only
293
+ * how many.
294
+ */
295
+ readonly perLevel: readonly IVirtualShadowLevelStat[];
296
+ }
297
+
298
+ /** One level's row of {@link IVirtualShadowStats}: 1 or 0 per counter, per frame. */
299
+ export interface IVirtualShadowLevelStat {
300
+ /** The level's clip extent, in world units. */
301
+ readonly extent: number;
302
+ readonly deferred: number;
303
+ readonly invalidated: number;
304
+ readonly moved: number;
305
+ readonly rendered: number;
306
+ /** Caster meshes this level's chosen camera layers submit this frame. Zero if it did not render. */
307
+ readonly draws: number;
308
+ /** The same bill split by kind; the five parts sum to {@link draws}. */
309
+ readonly drawsBy: IVirtualShadowDraws;
310
+ /** The adaptive caster gate's scale on this level, 1 when it is not shedding casters. */
311
+ readonly gateScale: number;
312
+ /** Casters the gate hid on the render this level took this frame; zero if it did not render. */
313
+ readonly gateHidden: number;
314
+ }
315
+
316
+ /** One level's caster draws, by the kind of mesh that submitted them. */
317
+ export interface IVirtualShadowDraws {
318
+ /** Caster batch meshes on the cluster layer, when the cluster half is the level's choice. */
319
+ readonly cluster: number;
320
+ /** Key-wide caster meshes on the wide layer, when the wide half is the level's choice. */
321
+ readonly wide: number;
322
+ /** Small casters, submitted by the finest level and by any level rendering a prewarm. */
323
+ readonly small: number;
324
+ /** Merged per-chunk shadow proxies (`<name>-shadow`), drawn with either caster half. */
325
+ readonly chunkProxy: number;
326
+ /** Everything else casting from layer 0 — terrain, props — which every level draws. */
327
+ readonly layer0: number;
328
+ /**
329
+ * GPU-scene keys: one mesh per `asset:level:part` drawn from the level's own twin of the dispatch's
330
+ * output, which is the whole of what a keyed map submits of the world. Zero unless a provider
331
+ * registered and `?tnShadowGpuKeys=1` asked, and then it replaces {@link cluster} and {@link wide}
332
+ * rather than adding to them: the keys draw the placements those two would have.
333
+ */
334
+ readonly keys: number;
335
+ }
336
+
337
+ /** The mutable tally `#probe` fills; the public row only ever reads it. */
338
+ export interface IVirtualShadowDrawTally {
339
+ cluster: number;
340
+ wide: number;
341
+ small: number;
342
+ chunkProxy: number;
343
+ layer0: number;
344
+ keys: number;
345
+ }
346
+
347
+ /** Square levels. A fit to the ground (`0.25`, a 14.5 degree sun is where it ends) is the named override. */
348
+ export const DEFAULT_MIN_WINDOW_ASPECT = 1;
349
+ export const DEFAULT_MARKER_EVERY = 300;
350
+ /**
351
+ * The invalidation delay of the *finest* level, in seconds; every other level's is this times its
352
+ * extent over the finest one. A burst of streamed invalidations is paid as one render, and the
353
+ * level that pays it is the one whose window is widest.
354
+ */
355
+ export const BASE_INVALIDATION_DELAY = 0.25;
356
+ export const DEFAULT_MIN_CASTER_TEXELS = 1.5;
357
+ /** Unreal's `r.Shadow.Virtual.Cache.FramesStaticThreshold`: quiet frames before a mover is static. */
358
+ export const DEFAULT_STATIC_AFTER_FRAMES = 100;
359
+ /**
360
+ * The share of the display period a level's render may cost before adaptive refresh widens its
361
+ * trail: two frames in five, 6.7 ms of a 60 Hz frame. A draw that big is worth a whole frame of its
362
+ * own, and a share rather than a millisecond count is what makes the same number mean the same thing
363
+ * on a 120 Hz panel.
364
+ */
365
+ export const DEFAULT_EXPENSIVE_REFRESH_SHARE = 0.4;
366
+
367
+ /** The per-level entry of a scalar-or-array option, the last entry standing in for the rest. */
368
+ export function at(values: readonly number[], level: number): number {
369
+ return values[Math.min(level, values.length - 1)] as number;
370
+ }
@@ -806,6 +806,11 @@ export class ShadowInvalidationTracker {
806
806
  this.clipmap = clipmap;
807
807
  }
808
808
 
809
+ /** Dirty page keys not yet consumed by the next shadow render. */
810
+ get pending(): number {
811
+ return this.#invalidated.size;
812
+ }
813
+
809
814
  get trackedCount(): number {
810
815
  return this.#tracked.size;
811
816
  }
@@ -129,10 +129,23 @@ export function installPartialRender(
129
129
  current: () => IPartialPass | undefined,
130
130
  ): void {
131
131
  const stock = node.renderShadow.bind(node);
132
+ let quadBuilt = false;
132
133
  node.renderShadow = (frame) => {
133
134
  const pass = current();
134
135
  const pixels = pass?.pixels;
135
136
  if (pass === undefined || pixels === undefined) {
137
+ // The reset quad's pipeline is built on its first draw. Drawn once here, under the whole
138
+ // map's own clear, it is built with the first shadow render, behind a loading curtain, not on
139
+ // the first partial reset that a camera turn in play triggers (PRD-790).
140
+ if (!quadBuilt && frame.renderer !== null) {
141
+ quadBuilt = true;
142
+ const { scene, camera, object, material } = frame;
143
+ resetDepth(frame.renderer, node.shadow.camera.reversedDepth === true);
144
+ frame.scene = scene;
145
+ frame.camera = camera;
146
+ frame.object = object;
147
+ frame.material = material;
148
+ }
136
149
  stock(frame);
137
150
  return;
138
151
  }