@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
package/dist/index.d.ts CHANGED
@@ -1,17 +1,18 @@
1
1
  import * as three from 'three';
2
- import { Object3D, AnimationClip, AnimationMixer, Camera, Vector3, Group, Matrix4, Mesh, BufferGeometry, Material, InstancedMesh, ColorRepresentation, Box3, Scene, DirectionalLight, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
3
- export { I as IAssetLoader, a as IAssetLoaderOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-CYKk2WTu.js';
4
- export { A as AudioBus, I as IAudioBusOptions, b as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-7i3Xl0l3.js';
5
- export { C as CanvasLayer } from './canvas-layer-C1SnMoJ-.js';
6
- import { a as IGamePluginRuntime, b as IGamePluginHooks } from './game-D_6r-k4Y.js';
7
- export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as InputPlatformSource, a3 as PointerEvent3DListener, a4 as PointerEvent3DType, a5 as PointerEvents3D, a6 as Scene, a7 as SceneFrame, a8 as ScenePicker, a9 as ScheduleHandle, aa as Scheduler, ab as ThreeNativeBackgroundMode, ac as ThreeNativeLodMinTrianglesScope, ad as ThreeNativeLodPreset, ae as ThreeNativeOrientation, af as ThreeNativeUiRenderer, ag as WarmUpCacheStatus, ah as WarmUpObservationStatus, ai as afterPhysics, aj as createRandom, ak as defineGame, al as warmUpScene } from './game-D_6r-k4Y.js';
2
+ import { Object3D, AnimationClip, AnimationMixer, Vector3, Camera, Group, Matrix4, Mesh, BufferGeometry, InstancedMesh, Material, ColorRepresentation, Box3, Scene, DirectionalLight, HemisphereLight, Color, ToneMapping, FogExp2, Sprite, DataTexture, CatmullRomCurve3, Texture } from 'three';
3
+ export { I as IAssetLoader, a as IAssetLoaderOptions, b as ITextureOptions, c as createAssetLoader, r as reconcileMirroredClips } from './assets-CqvE429w.js';
4
+ export { A as AudioBus, I as IAudioBusOptions, b as IAudioCompressorOptions, c as IAudioPlayOptions, r as resetAudioCueLedger } from './audio-DIJE5HTr.js';
5
+ export { C as CanvasLayer } from './canvas-layer-C1-5CviZ.js';
6
+ import { b as IGamePluginRuntime, a as IGamePluginHooks } from './game-Bj8G1wmD.js';
7
+ export { A as AfterPhysicsCallback, C as ContextMenuPolicy, G as GEOMETRY_ASSET_KEY, c as GEOMETRY_CAPTURE_DEFAULT_LIMIT, d as GEOMETRY_CAPTURE_MAX_LIMIT, e as GEOMETRY_CAPTURE_SORTS, f as GEOMETRY_CAPTURE_TIMEOUT_MS, g as GEOMETRY_CAPTURE_WALK_CAP, h as GeometryCaptureSort, i as ICtx, I as IGame, j as IGameObservationContribution, k as IGameObservationSampleRequest, l as IGamePlatformSource, m as IGeometryCaptureAsset, n as IGeometryCaptureMesh, o as IGeometryCapturePass, p as IGeometryCaptureReport, q as IGeometryCaptureRequest, r as IGeometryCaptureRow, s as IInputAction, t as IInputGamepad, u as IPointerDragHandle, v as IPointerEvent3D, w as IPointerEvents3D, x as IPointerEvents3DOptions, y as IPointerEvents3DPicker, z as IPointerState, B as IRandom, D as IRawInputPointer, E as IRawInputPointerEdge, F as IRawInputState, H as IRaycastOptions, J as IScenePickerOptions, K as IThreeNativeAudioConfig, L as IThreeNativeAudioLoop, M as IThreeNativeAudioOverride, N as IThreeNativeAudioSpectrum, O as IThreeNativeBootSplash, P as IThreeNativeConfig, Q as IThreeNativeIconVariants, R as IThreeNativeLodConfig, S as IThreeNativeLodGenerationConfig, T as IThreeNativeLodOverride, U as IThreeNativeLodRuntimeConfig, V as IThreeNativeTexturesConfig, W as ITweenOptions, X as IWarmUpCacheOptions, Y as IWarmUpObservation, Z as IWarmUpOptions, _ as IWarmUpProgress, $ as IWarmUpRenderer, a0 as IWarmUpReport, a1 as InputBindings, a2 as InputMap, a3 as InputPlatformSource, a4 as PointerEvent3DListener, a5 as PointerEvent3DType, a6 as PointerEvents3D, a7 as Scene, a8 as SceneFrame, a9 as ScenePicker, aa as ScheduleHandle, ab as Scheduler, ac as ThreeNativeBackgroundMode, ad as ThreeNativeLodMinTrianglesScope, ae as ThreeNativeLodPreset, af as ThreeNativeOrientation, ag as ThreeNativeUiRenderer, ah as WarmUpCacheStatus, ai as WarmUpObservationStatus, aj as afterPhysics, ak as captureMouse, al as createRandom, am as defineGame, an as warmUpScene } from './game-Bj8G1wmD.js';
8
8
  import * as three_webgpu from 'three/webgpu';
9
- import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode } from 'three/webgpu';
10
- import { I as IRendererLike, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-Cy4qeBOA.js';
11
- export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, b as FRAME_BUDGET_MARKER, c as FRAME_BUDGET_PHASES, d as FRAME_HITCH_MARKER, e as FrameBudget, f as FrameBudgetPhase, g as FrameCounters, h as ICounterDevice, i as IFrameBudgetOptions, j as IFrameBudgetPassSummary, k as IFrameBudgetSummary, l as IFrameCounters, m as IFramePhaseSample, n as IPipelineCensus, o as IPipelineCensusCounts, p as IPipelineCensusEvent, q as IPipelineCensusOptions, r as IPipelineProvenance, s as IPipelineShaderObservation, t as IRenderChainApplied, u as IRenderChainBudgetWindow, v as IRenderChainDroppedStage, w as IRenderChainOptions, x as IRenderChainRenderer, y as IRenderChainRequest, z as IRenderChainStage, A as IRenderChainStageContext, B as IRenderChainVelocityMeasurement, C as IRenderChainVelocityReport, E as IRenderChainVelocityRequest, G as IRenderChainVelocityResult, H as IRenderPassSample, J as IVelocityRenderPass, P as PIPELINE_CENSUS_CAPABILITY, K as PIPELINE_CENSUS_VERSION, L as PipelineCensus, M as PipelineCensusMode, N as PipelineCensusStatus, R as RENDER_CHAIN_MARKER, O as RENDER_CHAIN_STAGE_ORDER, Q as RENDER_CHAIN_TIERS, S as RenderChain, T as RenderChainSource, U as RenderChainStageId, V as RenderChainStageName, W as RenderChainTier, X as RenderChainTierRequest, Y as RenderChainVelocitySource, Z as VELOCITY_OUTPUT_NAME, _ as VELOCITY_PREVIOUS_BONE_MATRICES, $ as VELOCITY_PREVIOUS_INSTANCE_MATRICES, a0 as VELOCITY_PREVIOUS_WORLD_MATRIX, a1 as VelocityTracker, a2 as counterDeviceOf, a3 as createPipelineCensus, a4 as ensureVelocityOutput, a5 as prewarm, a6 as readRenderChainObservation, a7 as readRenderChainReport, a8 as readVelocityPreviousBoneMatrices, a9 as readVelocityPreviousMatrices, aa as readVelocityPreviousWorldMatrix, ab as velocityTexture, ac as withVelocityContext } from './renderer-Cy4qeBOA.js';
12
- import { I as IComputeDriven$1, a as IGPUReadbackSample } from './gpu-readback-CMklJs6r.js';
13
- export { C as ComputeDrivenRegistry, G as GPUReadback, b as IGPUReadbackOptions } from './gpu-readback-CMklJs6r.js';
14
- import { Node as Node$1 } from 'three/src/nodes/Nodes.js';
9
+ import { StorageTexture, ComputeNode, UniformNode, Node, TextureNode, NodeMaterial, StorageBufferNode, StructTypeNode, Data3DTexture, ShadowBaseNode, NodeBuilder, NodeFrame, SpriteNodeMaterial, StorageTextureNode, Storage3DTexture } from 'three/webgpu';
10
+ import { I as IRendererLike, F as FramePassKind, a as IFrameBudgetWindow } from './renderer-9yEo9hPa.js';
11
+ export { D as DEFAULT_PIPELINE_CENSUS_LIMIT, h as DEFAULT_TARGET_FPS, i as FRAME_BUDGET_MARKER, j as FRAME_BUDGET_PHASES, k as FRAME_HITCH_MARKER, l as FrameBudget, m as FrameBudgetPhase, n as FrameCounters, o as ICounterDevice, g as IFrameBudgetOptions, p as IFrameBudgetPassSummary, b as IFrameBudgetSimulation, q as IFrameBudgetSummary, r as IFrameCounters, d as IFramePhaseSample, e as IPipelineCensus, s as IPipelineCensusCounts, t as IPipelineCensusEvent, u as IPipelineCensusOptions, v as IPipelineProvenance, w as IPipelineShaderObservation, x as IPlatformInfo, y as IRenderChainApplied, z as IRenderChainBudgetWindow, A as IRenderChainDroppedStage, B as IRenderChainOptions, C as IRenderChainRenderer, E as IRenderChainRequest, G as IRenderChainStage, H as IRenderChainStageContext, J as IRenderChainVelocityMeasurement, K as IRenderChainVelocityReport, L as IRenderChainVelocityRequest, M as IRenderChainVelocityResult, c as IRenderPassSample, N as ITargetFps, O as IVelocityRenderPass, P as MAX_TARGET_FPS, Q as MainDrawSource, R as PIPELINE_CENSUS_CAPABILITY, S as PIPELINE_CENSUS_VERSION, T as PipelineCensus, U as PipelineCensusMode, V as PipelineCensusStatus, W as PlatformFormFactor, X as PlatformOS, Y as PlatformRuntime, Z as RENDER_CHAIN_MARKER, _ as RENDER_CHAIN_STAGE_ORDER, $ as RENDER_CHAIN_TIERS, a0 as RenderChain, a1 as RenderChainSource, a2 as RenderChainStageId, a3 as RenderChainStageName, a4 as RenderChainTier, a5 as RenderChainTierRequest, a6 as RenderChainVelocitySource, a7 as TargetFpsSource, a8 as VELOCITY_OUTPUT_NAME, a9 as VELOCITY_PREVIOUS_BONE_MATRICES, aa as VELOCITY_PREVIOUS_INSTANCE_MATRICES, ab as VELOCITY_PREVIOUS_WORLD_MATRIX, ac as VelocityTracker, ad as counterDeviceOf, ae as createPipelineCensus, af as ensureVelocityOutput, ag as getPlatform, ah as isMobile, ai as isNative, aj as isTouchscreenAvailable, ak as isWeb, al as prewarm, am as readRenderChainObservation, an as readRenderChainReport, ao as readVelocityPreviousBoneMatrices, ap as readVelocityPreviousMatrices, aq as readVelocityPreviousWorldMatrix, ar as resolveTargetFps, as as snapRefreshRate, at as velocityTexture, au as withVelocityContext } from './renderer-9yEo9hPa.js';
12
+ import { I as IComputeDriven$1, c as IGPUReadbackSample, d as IBudgetCandidate } from './model-lod-BDAUYgsS.js';
13
+ export { C as ComputeDrivenRegistry, D as DISCRETE_LOD_DEFAULT_ERROR_PIXELS, e as DISCRETE_LOD_DEFAULT_HYSTERESIS, G as GPUReadback, f as IGPUReadbackOptions, g as baseGeometryOf, l as lodPixelScale, u as updateModelLods } from './model-lod-BDAUYgsS.js';
14
+ import { SkyMesh } from 'three/addons/objects/SkyMesh.js';
15
+ import { Node as Node$1, UniformNode as UniformNode$1 } from 'three/src/nodes/Nodes.js';
15
16
  import 'zustand/vanilla';
16
17
 
17
18
  /**
@@ -83,6 +84,10 @@ declare const SPANS: {
83
84
  readonly sort: 12;
84
85
  /** Per-draw submission inside a render call, accumulated across the draws of one pass. */
85
86
  readonly draw: 13;
87
+ /** Terrain block rebuild and merged-attribute swap on the calling thread. */
88
+ readonly terrainBlock: 14;
89
+ /** Terrain seam reconciliation and bridge-attribute swap on the calling thread. */
90
+ readonly terrainSeam: 15;
86
91
  };
87
92
  type SpanId = (typeof SPANS)[keyof typeof SPANS];
88
93
  /** Names, indexed by id. The only place a span name is a string. */
@@ -165,14 +170,14 @@ declare class SpanRecorder {
165
170
  /** The window just closed, or `undefined` when no frame was recorded in it. */
166
171
  window(): ISpanWindow | undefined;
167
172
  }
168
- /** Installs or removes the recorder every `beginSpan`/`endSpan` routes to. */
173
+ /** Installs or removes the recorder every `beginSpan`/`endSpan` routes to, in every entry copy. */
169
174
  declare function setSpanRecorder(next: SpanRecorder | undefined): void;
170
175
  declare function spanRecorder(): SpanRecorder | undefined;
171
176
  /** The one clock the spans and the frame budget share, so their numbers are comparable. */
172
177
  declare function spanNow(): number;
173
178
  /**
174
179
  * Opens a span. One guarded return when spans are off — no clock read, no allocation, no branch on
175
- * anything but the recorder's own presence.
180
+ * anything but the recorder's own presence. The opt-in native wall-time sink sees it first.
176
181
  */
177
182
  declare function beginSpan(id: SpanId): void;
178
183
  declare function endSpan(id: SpanId): void;
@@ -290,11 +295,197 @@ declare class AnimationPlayer {
290
295
  /** The clip behind a name, for a game that wants the action or the raw `AnimationClip`. */
291
296
  clip(name: string): AnimationClip;
292
297
  play(name: string, options?: IAnimationPlayOptions): void;
298
+ /**
299
+ * Whether a clip has posed the skeleton. False until the first `play` or `playWeighted`, so a
300
+ * rig that never plays a clip stays observably in its bind pose.
301
+ */
302
+ get posed(): boolean;
303
+ /**
304
+ * Play several clips at once, at weights the game computed — the plumbing half of a locomotion
305
+ * blend space. The samples, the thresholds and the interpolation domain stay the game's: this
306
+ * takes the answer (`{ clip, weight }[]`) and owns what happens to the actions.
307
+ *
308
+ * What it guarantees, because every blend space needs the same four things:
309
+ *
310
+ * - **One mixer, one updater, one action per clip.** Nothing here creates an `AnimationMixer`.
311
+ * - **A still-contributing clip keeps its phase.** Returning to a walk mid-cycle does not
312
+ * restart it — the same convention `play` follows.
313
+ * - **An entering clip joins the gait.** Its normalized time is set to the dominant
314
+ * contributor's, so a walk→run change does not cross the feet mid-stride. Pass
315
+ * `phaseSync: false` for authored cycles that are deliberately out of phase with each other.
316
+ * - **Weights stay finite, non-negative and summing to 1.** Malformed input throws rather than
317
+ * producing a pose nobody can explain.
318
+ *
319
+ * `transition` is the bounded authored transition: weights move linearly towards the request
320
+ * over that many seconds, so a large instantaneous intent change cannot pop the pose, and `0`
321
+ * snaps them on the call. A clip that drops out of the request fades to zero and is then
322
+ * stopped, so repeated blends release their actions.
323
+ *
324
+ * Entries are played as loops. Events — a hit, a death, a reload — are `play`'s job.
325
+ */
326
+ playWeighted(entries: readonly {
327
+ readonly clip: string;
328
+ readonly weight: number;
329
+ }[], options?: {
330
+ readonly transition?: number;
331
+ readonly phaseSync?: boolean;
332
+ }): void;
293
333
  update(dt: number): void;
294
334
  stop(): void;
295
335
  dispose(): void;
296
336
  }
297
337
 
338
+ interface IAnimationMask {
339
+ readonly bones: readonly string[];
340
+ readonly descendants?: boolean;
341
+ /** Explicit root ownership; refused when root motion owns that same track. */
342
+ readonly includeRoot?: boolean;
343
+ }
344
+ interface IAnimationLayer {
345
+ readonly name: string;
346
+ readonly clip: string;
347
+ readonly mask: IAnimationMask;
348
+ readonly mode: "override" | "additive";
349
+ readonly once?: boolean;
350
+ readonly reference?: {
351
+ readonly clip: AnimationClip;
352
+ readonly time: number;
353
+ };
354
+ }
355
+
356
+ /*!
357
+ * Selectively adapted from GGEZ packages/anim-core/src/root-motion.ts
358
+ * (translation difference, quaternion yaw) at
359
+ * 45ed541cb163ef98694467758f60d5533373ac60. Adds explicit root binding,
360
+ * continuous loop intervals, yaw unwrapping and validated Three transforms.
361
+ * MIT License
362
+ * Copyright (c) 2026 @alightinastorm (x.com/alightinastorm)
363
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
364
+ * of this software and associated documentation files (the "Software"), to deal
365
+ * in the Software without restriction, including without limitation the rights
366
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
367
+ * copies of the Software, and to permit persons to whom the Software is
368
+ * furnished to do so, subject to the following conditions:
369
+ * The above copyright notice and this permission notice shall be included in all
370
+ * copies or substantial portions of the Software.
371
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
372
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
373
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
374
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
375
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
376
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
377
+ * SOFTWARE.
378
+ */
379
+
380
+ interface IAnimationRootMotionOptions {
381
+ readonly bone: string;
382
+ /** Existing character-body object. Its parent must be identity in this first slice. */
383
+ readonly body: Object3D;
384
+ }
385
+ interface IAnimationMotionDelta {
386
+ readonly translation: Pick<Vector3, "x" | "y" | "z">;
387
+ readonly yaw: number;
388
+ }
389
+
390
+ interface IAnimationComposerOptions {
391
+ readonly root: Object3D;
392
+ /**
393
+ * Copied into owned pose snapshots at construction. Constant stock quaternion tracks use
394
+ * equivalent discrete sampling there; reauthor source keys before constructing a new composer.
395
+ */
396
+ readonly clips: readonly AnimationClip[];
397
+ readonly samples: readonly string[];
398
+ readonly layers?: readonly IAnimationLayer[];
399
+ readonly rootMotion?: IAnimationRootMotionOptions;
400
+ }
401
+ /**
402
+ * One bounded Three player/mixer. Game-owned intent supplies normalized sample weights;
403
+ * every base action samples one normalized phase, while layered events retain authored time.
404
+ */
405
+ declare class AnimationComposer {
406
+ #private;
407
+ paused: boolean;
408
+ constructor(options: IAnimationComposerOptions);
409
+ get mixer(): three.AnimationMixer<three.AnimationMixerEventMap>;
410
+ get root(): Object3D<three.Object3DEventMap>;
411
+ get phase(): number;
412
+ get speed(): number;
413
+ set speed(value: number);
414
+ get weights(): readonly number[];
415
+ get sampleTimes(): readonly number[];
416
+ get resources(): {
417
+ actions: number;
418
+ bindings: number;
419
+ scratchBytes: number;
420
+ clipBuffers: number;
421
+ clipBufferBytes: number;
422
+ rootBuffers: number;
423
+ rootBufferBytes: number;
424
+ };
425
+ /** Snapshots remain honest while blocked: phase advances at authored speed, never re-timed by the wall. */
426
+ get motion(): {
427
+ readonly authority: "phase" | "rootMotion";
428
+ readonly requested: Vector3;
429
+ readonly requestedYaw: number;
430
+ readonly accepted: Vector3;
431
+ readonly acceptedYaw: number;
432
+ readonly blocked: boolean;
433
+ };
434
+ get blocked(): boolean;
435
+ setWeights(weights: ArrayLike<number>, transition?: number): void;
436
+ setLayerWeight(name: string, weight: number): void;
437
+ /** Explicit replay; repeated weight requests do not re-fire a completed one-shot. */
438
+ restartLayer(name: string): void;
439
+ update(dt: number): void;
440
+ /** Borrowed proposal: queue it once with CharacterBody3D.move, then finish after physics. */
441
+ advance(dt: number): {
442
+ readonly translation: Vector3;
443
+ readonly yaw: number;
444
+ };
445
+ /** Final authored pose precedes the game's existing IK. This method never writes the body. */
446
+ finish(accepted?: IAnimationMotionDelta): void;
447
+ dispose(): void;
448
+ }
449
+
450
+ /*!
451
+ * Selectively adapted from GGEZ packages/anim-runtime/src/runtime/helpers.ts
452
+ * (findBlend1DChildren, computeTriangleBarycentricWeights, findBlend2DEdgeWeights)
453
+ * at 45ed541cb163ef98694467758f60d5533373ac60. Replaced graph children with
454
+ * validated fixed sample indices, initialization-only sorting and reusable output.
455
+ * MIT License
456
+ * Copyright (c) 2026 @alightinastorm (x.com/alightinastorm)
457
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
458
+ * of this software and associated documentation files (the "Software"), to deal
459
+ * in the Software without restriction, including without limitation the rights
460
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
461
+ * copies of the Software, and to permit persons to whom the Software is
462
+ * furnished to do so, subject to the following conditions:
463
+ * The above copyright notice and this permission notice shall be included in all
464
+ * copies or substantial portions of the Software.
465
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
466
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
467
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
468
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
469
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
470
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
471
+ * SOFTWARE.
472
+ */
473
+ type Point = readonly [number, number];
474
+ type Triangle = readonly [number, number, number];
475
+ declare class BlendSpace1D {
476
+ #private;
477
+ readonly weights: Float64Array;
478
+ constructor(thresholds: readonly number[]);
479
+ sample(value: number): Float64Array;
480
+ }
481
+ /** Fixed complete convex-hull triangulation. Collinear triangles and overlapping tiles fail at load. */
482
+ declare class BlendSpace2D {
483
+ #private;
484
+ readonly weights: Float64Array;
485
+ constructor(points: readonly Point[], triangles: readonly Triangle[]);
486
+ sample(x: number, y: number): Float64Array;
487
+ }
488
+
298
489
  type NormaliseAxis = "height" | "longest";
299
490
  interface INormaliseToMetresOptions {
300
491
  readonly metres: number;
@@ -405,8 +596,12 @@ declare class CameraShake {
405
596
  * that needs it. The page owns the presentation (and the copy-to-clipboard button players are
406
597
  * asked for when they report a launch that hung); this owns the noticing and the wording.
407
598
  */
408
- /** What failed. `stalled` is "no progress for a while"; `device-lost` is the GPU going away. */
409
- type LaunchFailureKind = "stalled" | "device-lost";
599
+ /**
600
+ * What failed. `stalled` is "no progress for a while"; `device-lost` is the GPU going away;
601
+ * `scene-load-failed` is a scene's `load()` rejecting and `start-failed` is `start()` rejecting,
602
+ * each of which otherwise reads as a stall.
603
+ */
604
+ type LaunchFailureKind = "stalled" | "device-lost" | "scene-load-failed" | "start-failed";
410
605
  interface ILaunchFailure {
411
606
  readonly kind: LaunchFailureKind;
412
607
  /** One human sentence, already naming the numbers — this is what the Copy button copies. */
@@ -571,7 +766,7 @@ type AtmosphereDirection = Vector3 | readonly [number, number, number] | Node<"v
571
766
  * those, and the same object remains useful when a game supplies a completely different look.
572
767
  * @situation render a sunrise that changes as time and place change
573
768
  * @situation add distance haze from the depth of a scene pass
574
- * @alias bright sky saturated green platforms
769
+ * @alias green platforms bright saturated sky
575
770
  * @constraint supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback
576
771
  * @constraint the game creates the sky object, surface, and sun from the returned nodes
577
772
  * @example const atmosphere = new Atmosphere({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });
@@ -721,7 +916,7 @@ declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
721
916
  get released(): boolean;
722
917
  get triangleCount(): number;
723
918
  get vertexCount(): number;
724
- attachRenderer(renderer: IRendererLike): void;
919
+ attachRenderer(_renderer: IRendererLike): void;
725
920
  process(_renderer: IRendererLike): void;
726
921
  /** Repack the selected scene objects and replace the GPU buffers behind the stable node handles. */
727
922
  rebuild(): void;
@@ -729,6 +924,19 @@ declare class GPUSceneBVH extends Group implements IComputeDriven$1 {
729
924
  detach(): void;
730
925
  }
731
926
 
927
+ interface IInstancedLodOptions {
928
+ /** Baked-chain selection is automatic. `false` leaves detail to the caller. */
929
+ readonly autoLod?: false | {
930
+ readonly maxPixelError?: number;
931
+ readonly hysteresis?: number;
932
+ };
933
+ /** Authored distance levels win over the baked chain. Missing geometries report once at build. */
934
+ readonly lods?: readonly {
935
+ readonly distance: number;
936
+ readonly geometry: BufferGeometry | undefined;
937
+ }[];
938
+ }
939
+
732
940
  /** One instance's transform, in the units the geometry was authored in. */
733
941
  interface IInstancedPlacement {
734
942
  /** World position of the instance's origin, as `[x, y, z]`. */
@@ -738,7 +946,7 @@ interface IInstancedPlacement {
738
946
  /** Per-axis scale as `[x, y, z]`, or one number for all three. Default 1. */
739
947
  readonly scale?: readonly [number, number, number] | number;
740
948
  }
741
- interface IInstancedBatchOptions {
949
+ interface IInstancedBatchOptions extends IInstancedLodOptions {
742
950
  /** The shape every instance draws, supplied by the game. */
743
951
  readonly geometry: BufferGeometry;
744
952
  /**
@@ -757,6 +965,15 @@ interface IInstancedBatchBuildOptions {
757
965
  readonly parent?: Object3D;
758
966
  /** Passed straight to the built mesh. Default `false`, as in Three.js. */
759
967
  readonly receiveShadow?: boolean;
968
+ /**
969
+ * An existing mesh to refill instead of creating one: used when it draws this batch's geometry
970
+ * and material and holds at least this many instances. Reusing matters on WebGPU, where three
971
+ * keys an instanced mesh's compiled node program by the mesh itself — every new InstancedMesh
972
+ * rebuilds its shader, and a streamed world creating hundreds a cell stalls on it.
973
+ */
974
+ readonly into?: InstancedMesh;
975
+ /** Instance slots to allocate when a new mesh is created, so later refills fit. Default: count. */
976
+ readonly capacity?: number;
760
977
  }
761
978
  /**
762
979
  * Collapses many copies of one shape into a single draw, without knowing the count up front.
@@ -777,8 +994,22 @@ declare class InstancedBatch {
777
994
  constructor(options: IInstancedBatchOptions);
778
995
  /** How many instances have been placed so far. */
779
996
  get count(): number;
997
+ /**
998
+ * Writes every placed matrix into `target` (a mesh's `instanceMatrix.array`), starting at instance
999
+ * `offset`, and returns how many were written. For a caller that packs several batches into one
1000
+ * shared instance buffer instead of building a mesh per batch.
1001
+ */
1002
+ writeMatrices(target: Float32Array, offset: number): number;
780
1003
  /** The built mesh, or `undefined` before {@link build} — never a guess. */
781
1004
  get mesh(): InstancedMesh | undefined;
1005
+ /**
1006
+ * True when this batch holds element-for-element the matrices of `other`.
1007
+ *
1008
+ * A refilter rebuilds a cell's batch from the same run in the same order, so "did the answer
1009
+ * change" is exactly this question, and comparing is what lets the swap skip a rebuild that came
1010
+ * back identical instead of writing, clearing and compacting records the buffer already holds.
1011
+ */
1012
+ equals(other: InstancedBatch | undefined): boolean;
782
1013
  /**
783
1014
  * Records one instance from a matrix the game composed itself, and returns its instance index.
784
1015
  *
@@ -833,6 +1064,33 @@ interface IMergePartsOptions {
833
1064
  */
834
1065
  readonly preserve?: readonly ("uv" | "normal")[];
835
1066
  }
1067
+ interface IMergeByMaterialOptions {
1068
+ /** Named in the error when a group's merge is refused. Say what was being built. */
1069
+ readonly label: string;
1070
+ /**
1071
+ * Leaves one mesh out of its material's group and out of the result — a piece that moves at run
1072
+ * time, or one a capture script addresses by name.
1073
+ */
1074
+ readonly skip?: (mesh: Mesh) => boolean;
1075
+ /**
1076
+ * An `InstancedMesh` is baked into its material's group as one part per instance matrix while that
1077
+ * group stays at or below this many triangles. Above it — or absent, which is the old behaviour —
1078
+ * it comes back in the result untouched, because one instanced draw is already cheaper than the
1079
+ * triangles it expands into.
1080
+ */
1081
+ readonly expandInstancedUnderTriangles?: number;
1082
+ /**
1083
+ * Vertices one merged group may hold before the rest of its material's parts start a second mesh.
1084
+ *
1085
+ * One merged group is one upload on the frame that first draws it, and that upload is the frame's
1086
+ * whole cost: measured in a browser, a streamed world created 826 GPU buffers totalling 228.8 MB
1087
+ * out of `createAttribute`, 33 of them over 1 MB, and the first draw of the largest chunk meshes
1088
+ * took up to 230 ms. Splitting a material group in traversal order — which keeps the pieces
1089
+ * adjacent to the pieces they were placed beside — bounds each of those uploads instead of
1090
+ * trading one draw for a single enormous buffer. See `CHUNK_MERGE_MAX_VERTICES`.
1091
+ */
1092
+ readonly maxGroupVertices?: number;
1093
+ }
836
1094
  /**
837
1095
  * Merge game-authored pieces into one buffer, keeping each piece's own colour and, when asked,
838
1096
  * its uv and authored normals.
@@ -846,8 +1104,69 @@ interface IMergePartsOptions {
846
1104
  * are entirely the game's, one per part, and changing them changes nothing here. By default the
847
1105
  * merged normals are recomputed from the merged buffer; `preserve` keeps the authored normals and
848
1106
  * texture coordinates instead so an imported model's shading survives the bake.
1107
+ *
1108
+ * A group whose parts are all indexed merges indexed — the sum of their vertex counts, not three
1109
+ * times their triangles — and only a mixed group falls back to the de-indexed soup. One crossing
1110
+ * 65,535 vertices gets a 32-bit index, because a 16-bit one cannot name the vertex.
849
1111
  */
850
1112
  declare function mergeParts(parts: Iterable<IMergePart>, options: IMergePartsOptions): BufferGeometry;
1113
+ /**
1114
+ * Bake a hierarchy's static meshes into one mesh per material, transforms and all.
1115
+ *
1116
+ * A building or a ship is dozens of boxes and cylinders that never move relative to each other, and
1117
+ * every one of them is a draw call. Grouping by material and merging each group is the ordinary
1118
+ * fix, and the ordinary fix is thirty lines an agent rewrites in every game, each time slightly
1119
+ * differently: walk the tree, group by material, bake `matrixWorld` into the vertices, hand the
1120
+ * group to `mergeParts`, build a mesh on the game's own material. The parts here are the same
1121
+ * `IMergePart` list, so a game that already merges by hand gets the same refusals — a group that
1122
+ * cannot merge throws naming `label:material`, not silently vanishing.
1123
+ *
1124
+ * Nothing here decides how anything looks: the material is the game's own instance, the geometry is
1125
+ * exactly what was authored, and the group split follows the materials the game already made.
1126
+ *
1127
+ * `normal` survives when every mesh in a group carries it and is recomputed otherwise. `uv` survives
1128
+ * when any mesh carries it, so a group where only some do is the refusal `mergeParts` raises, never
1129
+ * a texture silently left unmapped. Skinned meshes are left alone — their vertices are posed per
1130
+ * frame — and an instanced one is left alone unless `expandInstancedUnderTriangles` names a cap its
1131
+ * group fits under and its own shape is small enough to be worth repeating, which bakes every
1132
+ * instance matrix into the merge.
1133
+ *
1134
+ * `maxGroupVertices` bounds a single group, and a material whose parts cross it is merged into
1135
+ * several meshes in traversal order — more draws, none of them carrying a buffer big enough to stall
1136
+ * the frame that first submits it.
1137
+ */
1138
+ declare function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions): Mesh[];
1139
+
1140
+ /**
1141
+ * A debug switch a game reads the same way on every platform it ships to.
1142
+ *
1143
+ * Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
1144
+ * turn this on for one run without changing the code, and how does a capture script reach the object
1145
+ * it wants to look at. The answers here are one function each, and neither decides how anything
1146
+ * looks.
1147
+ */
1148
+ /**
1149
+ * A debug switch read from the URL, or from the environment on a native launch.
1150
+ *
1151
+ * @situation read a debug toggle from the URL or an environment variable
1152
+ *
1153
+ * A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
1154
+ * launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
1155
+ * a command line. `0` and `false` are off, so a saved URL that used to enable a switch still says
1156
+ * "off" rather than quietly turning it back on.
1157
+ */
1158
+ declare function debugFlag(name: string): boolean;
1159
+ /**
1160
+ * Publish one game object for a capture script or the console, in development builds only.
1161
+ *
1162
+ * @situation expose a game object to a capture script or the console in dev builds
1163
+ *
1164
+ * Playtest reads `__THREENATIVE__` in a dev build and is silent in a production one, so a game that
1165
+ * publishes its player, its camera or a scene handle under `.debug` is reachable from the same
1166
+ * place a production build is not. Other keys on the shared object are left alone; the dev surfaces
1167
+ * the engine installs beside them keep working.
1168
+ */
1169
+ declare function exposeDebug(name: string, value: unknown): void;
851
1170
 
852
1171
  /**
853
1172
  * A mesh that draws only the clusters this camera can resolve.
@@ -901,13 +1220,32 @@ interface IClusteredMeshOptions {
901
1220
  }
902
1221
  declare class ClusteredMesh extends Mesh {
903
1222
  #private;
904
- /** The baked payload. Read-only at run time; the bake is the only thing that writes it. */
905
- readonly table: IClusterTable;
1223
+ /** The baked payload. The bake is the only thing that writes it; a copy takes the source's. */
1224
+ table: IClusterTable;
906
1225
  /** Screen-space error budget in pixels. Writable — it is the game's call. */
907
1226
  errorPixels: number;
908
1227
  /** Camera movement, in the mesh's own units, below which the previous cut is kept. */
909
1228
  recutDistance: number;
910
1229
  constructor(geometry: BufferGeometry, surface: Material | Material[], table: IClusterTable, options?: IClusteredMeshOptions);
1230
+ /**
1231
+ * A second mesh over the same body, cut for its own place in the scene.
1232
+ *
1233
+ * three's `Object3D.clone` builds through `new this.constructor()`, and this class's constructor
1234
+ * wants a table — so every game that stood a second copy of a cooked model where it wanted a
1235
+ * statue died in `assertTable` before drawing anything. The arguments are the source's own,
1236
+ * which is what a copy is.
1237
+ */
1238
+ clone(recursive?: boolean): this;
1239
+ /**
1240
+ * Becomes a copy of `source`, sharing the bake and the vertices and keeping a cut of its own.
1241
+ *
1242
+ * `Mesh.copy` shares the geometry outright, which this class cannot let it do: the cut lives in
1243
+ * the geometry's index buffer, so two meshes on one geometry would overwrite each other's index
1244
+ * every frame and both would draw whichever spoke last. The copy takes the vertex attributes by
1245
+ * reference instead — one copy of them on the GPU, because three keys its attributes on the
1246
+ * attribute — and the shared table, which is frozen at bake time and cannot go stale.
1247
+ */
1248
+ copy(source: this, recursive?: boolean): this;
911
1249
  /** Clusters in the current cut. */
912
1250
  get drawnClusters(): number;
913
1251
  /** Triangles the current cut submits. */
@@ -1015,22 +1353,6 @@ declare class ClusteredBatch {
1015
1353
  update(camera: Camera, viewportHeight: number): number;
1016
1354
  }
1017
1355
 
1018
- /** The LOD0 geometry of a mesh under a discrete chain, or the mesh's own geometry otherwise. */
1019
- declare function baseGeometryOf(mesh: Mesh): BufferGeometry;
1020
- /**
1021
- * Takes every discrete-LOD mesh under `root` through this frame's selection.
1022
- *
1023
- * The engine calls this itself, once a frame, after matrices are synced and before the render.
1024
- * Multi-view callers that need the finest level across passes use {@link selectLodLevel} directly;
1025
- * this entry point selects for the one camera it is handed — which is the main view, and is at
1026
- * least as fine as a shadow pass of lower resolution needs.
1027
- *
1028
- * @returns triangles the managed meshes will submit this frame.
1029
- */
1030
- declare function updateModelLods(root: {
1031
- traverse(callback: (object: object) => void): void;
1032
- }, camera: Camera, viewportHeight: number): number;
1033
-
1034
1356
  /**
1035
1357
  * What the gate did on the last frame, in the shape a frame-budget window reports.
1036
1358
  *
@@ -1096,22 +1418,39 @@ declare function alwaysRender(object: Object3D, enabled?: boolean): void;
1096
1418
  *
1097
1419
  * The pass mirrors three exactly for a visible node: `matrixAutoUpdate` -> `updateMatrix()`, then
1098
1420
  * the `matrixWorldNeedsUpdate || force` recompute honouring `matrixWorldAutoUpdate` and a null
1099
- * parent, then force the children. A node with `visible === false` still composes its **own**
1100
- * matrix — that is what makes the next part cheap — and is not recursed into; when it was forced
1101
- * (or carried a dirty flag) it is remembered, so the first frame it is visible again its whole
1102
- * subtree is recomputed with `force = true`.
1421
+ * parent, then force the children. A node with `visible === false` defers its own compose and its
1422
+ * subtree's walk. Every skipped root is remembered, so the first frame it is visible again both
1423
+ * its own world matrix and its descendants are recomputed with `force = true`.
1103
1424
  *
1104
1425
  * Two things are never dropped by the pruning, because both are read while nothing above them is
1105
1426
  * visible:
1106
1427
  *
1107
- * - a class that overrides `updateMatrixWorld` runs its own. `SkinnedMesh` refreshes
1108
- * `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base walk
1109
- * left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
1428
+ * - a class that overrides `updateMatrixWorld` runs its own — never a `Scene`, which three does not
1429
+ * override and whose method only differs when something patched the prototype. `SkinnedMesh`
1430
+ * refreshes `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base
1431
+ * walk left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
1110
1432
  * vanishing from the frame. Their subtrees are small, so walking them whole costs nothing;
1111
1433
  * - a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its
1112
1434
  * skeleton's matrices wherever the armature happens to sit. Whether bones sit below a node is
1113
1435
  * decided once and remembered — a rig is built whole and does not grow.
1114
1436
  *
1437
+ * A third thing is dropped, and it is the walk's largest single share on a streamed world: a subtree
1438
+ * frozen with `markStatic`. `markStatic` composes the subtree once and turns off the two flags that
1439
+ * would recompose it, which until now still left three's unconditional recursion visiting every node
1440
+ * under it every frame. A frozen root that carries no dirty flag is a leaf here, and it is one
1441
+ * whether the walk was forced or not: `refreshStaticTransforms` re-arms a root whose own transform
1442
+ * moved, `invalidateStatic` re-arms one something wrote inside, and both compose the subtree once at
1443
+ * that moment. `isStatic` is what separates the engine's freeze from a game that turned the flags off
1444
+ * for its own reasons. See `static-transform.ts`.
1445
+ *
1446
+ * Where the root is a native-engine object it has its own walk, `__tnUpdateMatrixWorld(force, prune)`: this
1447
+ * pass run natively in one call, answering the nodes it visited. The pass calls that and nothing else, since the
1448
+ * walk above costs a bridge call per node read and written (about 16 to 25 thousand a frame at 4,096 cubes).
1449
+ * With `prune` (the `"visible"` mode) the native walk leaves a hidden subtree where it stands by the same rules,
1450
+ * bones included; `"all"` visits every node. A JS subclass of `Object3D` that overrides `updateMatrixWorld` is not
1451
+ * called from inside it; the engine's own `SkinnedMesh` and `Camera` keep their derived matrices. The web and the
1452
+ * legacy host have no such method and walk as above.
1453
+ *
1115
1454
  * A game that reads a **hidden** object's `matrixWorld` directly must not rely on this pass
1116
1455
  * having reached it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` (which update the
1117
1456
  * chain they need) or call `object.updateWorldMatrix(true, false)` first. The convention's named
@@ -1286,6 +1625,58 @@ declare function describeSceneWarning(warning: ISceneWarning): string;
1286
1625
  /** The marker line. */
1287
1626
  declare function formatSceneWarning(warning: ISceneWarning): string;
1288
1627
 
1628
+ /**
1629
+ * The engine telling the agent that built the scene what a human finds by playing it once.
1630
+ *
1631
+ * Imported foliage drawn with no image-based light looks like cardboard, and nothing in the build
1632
+ * says so. A GLB's leaf card is `MeshStandardMaterial` (or its Node twin), `alphaTest` above zero,
1633
+ * `side: DoubleSide`; with `scene.environment === null` and no `envMap` on the material, `envMapIntensity`
1634
+ * has nothing to apply — three r185's WebGPU path only uses it when the material carries its own
1635
+ * `envMap`, and `scene.environmentIntensity` only reaches a scene that has an environment. What is
1636
+ * left is a hemisphere fill, so a shaded needle card and its back face land on one flat dark value
1637
+ * and the author compensates with a tint or a fake emissive, which is the paperboard.
1638
+ *
1639
+ * So the rule is derived from the scene graph, never from a constant: cutout PBR, counted by
1640
+ * material, with no environment anywhere in the scene. It fires once per scene entry, warns, and
1641
+ * changes nothing — the fix is the game's own `scene.environment`, which is appearance and therefore
1642
+ * the game's to set.
1643
+ */
1644
+
1645
+ /** Marker printed once per scene entry, for a log reader and a harness to grep. */
1646
+ declare const UNLIT_FOLIAGE_MARKER = "TN_UNLIT_FOLIAGE";
1647
+ /** The one line that says what to change. Never a second sentence: the fix is one decision. */
1648
+ declare const UNLIT_FOLIAGE_FIX = "set scene.environment (an HDRI or a sky texture) or give these materials an envMap; do not tint or flatten their normals to compensate";
1649
+ /** The verdict: what is affected, and enough names to find it in the scene graph. */
1650
+ interface IUnlitFoliageWarning {
1651
+ /** Distinct materials with no image-based light, the number an author can act on. */
1652
+ readonly materials: number;
1653
+ /** Meshes drawn with them, so one shared material is not mistaken for a scene-wide one. */
1654
+ readonly meshes: number;
1655
+ readonly examples: readonly string[];
1656
+ }
1657
+ /**
1658
+ * The warning for one scene entry, or `undefined` when nothing in it is unlit.
1659
+ *
1660
+ * Fails closed on the reading it needs: a scene with an environment, or a material carrying its own
1661
+ * `envMap`, gets no warning, because the absence of an image-based light is the whole claim and
1662
+ * anything else is speculation. Materials are counted once however many meshes share them, because
1663
+ * a hundred instances of one imported atlas are one decision, not a hundred.
1664
+ */
1665
+ declare function unlitFoliageWarning(scene: Object3D & {
1666
+ environment?: unknown;
1667
+ }): IUnlitFoliageWarning | undefined;
1668
+ /** The marker line. */
1669
+ declare function formatUnlitFoliageWarning(warning: IUnlitFoliageWarning): string;
1670
+
1671
+ /** Marker for an equirectangular environment below three's minimum PMREM cube size. */
1672
+ declare const ENVIRONMENT_TOO_SMALL_MARKER = "TN_ENVIRONMENT_TOO_SMALL";
1673
+ /** Marker for a drawn material whose opacity three ignores. */
1674
+ declare const OPACITY_IGNORED_MARKER = "TN_OPACITY_IGNORED";
1675
+ /** Structural reads only: Node materials, native adapters and test stubs share this audit. */
1676
+ declare function renderTrapAudit(scene: Object3D & {
1677
+ environment?: unknown;
1678
+ }): string[];
1679
+
1289
1680
  /**
1290
1681
  * Authored static subtrees: stop recomposing transforms that nobody moves.
1291
1682
  *
@@ -1609,6 +2000,8 @@ interface IClipWindow {
1609
2000
  readonly level: number;
1610
2001
  readonly extent: number;
1611
2002
  readonly pageWorldSize: number;
2003
+ /** Pages a window trails its followed centre by before it moves and re-renders. */
2004
+ readonly refreshPages: number;
1612
2005
  readonly minX: number;
1613
2006
  readonly minY: number;
1614
2007
  readonly maxX: number;
@@ -1620,8 +2013,18 @@ interface IDirectionalClipmapOptions {
1620
2013
  /** Half-width of each level's window in world units, finest first. */
1621
2014
  readonly clipExtents: readonly number[];
1622
2015
  readonly pagesPerAxis: number;
1623
- /** Fraction of an extent inside which a point selects that level; `(0, 1]`. */
1624
- readonly selectionGuard?: number;
2016
+ /**
2017
+ * Fraction of an extent inside which a point selects that level, `(0, 1]`, default 0.9. One value
2018
+ * for every level, or one per level finest first, the last entry standing in for the rest.
2019
+ */
2020
+ readonly selectionGuard?: number | readonly number[];
2021
+ /**
2022
+ * Fraction of an extent a level's window may trail its followed centre by before it re-renders,
2023
+ * `[0, 1)`, default 0.125. Rounded to whole texels with one texel reserved for a deferred render;
2024
+ * `0` keeps the old one-texel step. Larger steps re-render a level less often as the camera walks. One value
2025
+ * for every level, or one per level finest first, the last entry standing in for the rest.
2026
+ */
2027
+ readonly refreshStep?: number | readonly number[];
1625
2028
  }
1626
2029
  /**
1627
2030
  * Camera-centred clip windows in a light-space basis, snapped to whole pages.
@@ -1634,14 +2037,21 @@ declare class DirectionalClipmap {
1634
2037
  #private;
1635
2038
  readonly clipExtents: readonly number[];
1636
2039
  readonly pagesPerAxis: number;
1637
- readonly selectionGuard: number;
2040
+ /**
2041
+ * Per level, finest first; the last entry stands in for every level past it. Mutable through
2042
+ * {@link setRefreshStep} so a level whose own render is expensive can be stepped further, which
2043
+ * is fewer grid positions for its window rather than a different grid.
2044
+ */
2045
+ refreshStep: number[];
2046
+ /** Per level, finest first; the last entry stands in for every level past it. */
2047
+ readonly selectionGuard: readonly number[];
1638
2048
  readonly levelCount: number;
1639
2049
  basisU: IVector3Like;
1640
2050
  basisV: IVector3Like;
1641
2051
  basisW: IVector3Like;
1642
2052
  centerWorld: IVector3Like;
1643
2053
  centerLight: ILightSpacePoint;
1644
- constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, }: IDirectionalClipmapOptions);
2054
+ constructor({ direction, clipExtents, pagesPerAxis, selectionGuard, refreshStep, }: IDirectionalClipmapOptions);
1645
2055
  /** Re-orient the basis; returns true when it changed enough that cached pages are stale. */
1646
2056
  setDirection(direction: IVector3Like): boolean;
1647
2057
  project(worldPoint: IVector3Like): ILightSpacePoint;
@@ -1650,6 +2060,8 @@ declare class DirectionalClipmap {
1650
2060
  v: number;
1651
2061
  w?: number;
1652
2062
  }): IVector3Like;
2063
+ /** Re-step one level's window: the trail its followed centre may move before it re-renders. */
2064
+ setRefreshStep(level: number, step: number): void;
1653
2065
  updateCenter(worldPoint: IVector3Like): readonly IClipWindow[];
1654
2066
  getWindow(level: number): IClipWindow;
1655
2067
  pageWorldSize(level: number): number;
@@ -1715,19 +2127,143 @@ interface IVirtualShadowOptions {
1715
2127
  readonly mapSize?: number;
1716
2128
  /**
1717
2129
  * Texels per edge of each level's mover map — the map tracked casters draw into every frame.
1718
- * Default: half of `mapSize`, never below 256. Movers are few and close, so half the texels
1719
- * over the same window reads as the same shadow at a quarter of the fill.
2130
+ * Default: `mapSize`, the cached levels' own density, so a caster keeps the edge it had at rest
2131
+ * while it moves and does not pop to a crisper one when it settles. Lower it to buy back fill
2132
+ * on a weak GPU; the soft edge it costs is on the mover only.
1720
2133
  */
1721
2134
  readonly moverMapSize?: number;
1722
2135
  /**
1723
2136
  * Fraction of a level's extent inside which a fragment still selects that level, `(0, 1]`,
1724
2137
  * default 0.9 — the outer ring falls through to the next level so the edge is never sampled.
2138
+ * `selectionGuard` minus `refreshStep`, since a window trails its centre by that much. One value
2139
+ * for every level, or one per level finest first, the last entry standing in for the rest.
2140
+ */
2141
+ readonly selectionGuard?: number | readonly number[];
2142
+ /**
2143
+ * Fraction of a level's extent its window may trail the followed centre by before it re-renders,
2144
+ * `[0, selectionGuard)`, default 0.125 — `refreshStep: 0` keeps the old one-texel step. The step
2145
+ * is rounded to a whole number of that level's texels, so a walking camera re-renders a level
2146
+ * ~`1/refreshStep` times less often while the shadow texels stay on one fixed world grid. Costs
2147
+ * that much of `selectionGuard`, which it is already reduced by, so a window never reaches past
2148
+ * the trailing edge of a map rendered before the centre moved. One value for every level, or one
2149
+ * per level finest first, the last entry standing in for the rest — the fine level is the one a
2150
+ * walking camera re-renders most, so it is the one that wants the larger step.
2151
+ */
2152
+ readonly refreshStep?: number | readonly number[];
2153
+ /**
2154
+ * Let a level buy itself a wider `refreshStep` out of what its own last render cost, default true.
2155
+ *
2156
+ * A level render is a whole scene draw, so the engine cannot know what one is worth until it has
2157
+ * paid for it: the node measures the draw it just took and smooths that reading, and a level whose
2158
+ * smoothed cost is a large share of the frame period is re-rendered less often. This is automatic
2159
+ * because the value it reacts to is a measurement, not a setting — a game sets nothing, and a
2160
+ * cheap level is never widened and behaves exactly as before. The widened trail is capped by the
2161
+ * window's own margin, so the camera stays inside the region that level serves and everything that
2162
+ * level serves stays inside the map; a level with no such margin is never widened at all.
2163
+ *
2164
+ * `false` puts every level back on the `refreshStep` it was given, which is also what a harness
2165
+ * that wants to count today's renders uses.
2166
+ * `?tnAdaptiveRefresh=0` in the page URL makes the default `false` from the node's first setup.
2167
+ */
2168
+ readonly adaptiveRefresh?: boolean;
2169
+ /**
2170
+ * Fraction of the display period a level's smoothed render cost may take before its refresh trail
2171
+ * widens, `(0, 1]`, default 0.4.
2172
+ *
2173
+ * The period is the frame's own `deltaTime`, capped at the 60 fps frame (16.7 ms). The cap is what
2174
+ * keeps the budget honest: the frame that renders an expensive level is itself long because of that
2175
+ * render, so reading the share against its own inflated delta would count the cost twice and let
2176
+ * the very level that needs adapting pass its own test. At 60 Hz the cap is the frame itself; on a
2177
+ * 120 Hz panel the same render is twice the share it is at 60; below 60 the cap holds the budget
2178
+ * at the 60 fps frame rather than growing with the stall. Below the share nothing changes at all,
2179
+ * and above it the trail widens in proportion to the overshoot,
2180
+ * because that is the ratio between what the level costs and what a frame can afford to spend on
2181
+ * it — a level four times over the share refreshs about four times less often, until the cap
2182
+ * below it runs out.
2183
+ */
2184
+ readonly expensiveRefreshShare?: number;
2185
+ /**
2186
+ * Raise the finest level's texel size gate while its own render is too expensive for the frame, default
2187
+ * true.
2188
+ *
2189
+ * The same measurement adaptive refresh reads — the smoothed cost of the level's own last render,
2190
+ * against the share of the frame it may take — drives a second, independent adaptation: a level
2191
+ * whose render is over budget sizes its gate up in steps of 1.5 until it is affordable again, up
2192
+ * to 8 times the configured gate, and halves it back toward 1 once the render is comfortably under
2193
+ * half the budget. The gate only ever judges a caster by its size (see `minCasterTexels`), so this
2194
+ * drops the tiniest props first and never a building, and a level that is cheap is never touched:
2195
+ * it stays at scale 1 and submits exactly what it did before.
2196
+ *
2197
+ * Coarse levels always stay at scale 1 so resolved casters survive the handover.
2198
+ * `false` pins every level at scale 1, which is also what a harness that wants today's draw
2199
+ * counts uses.
2200
+ */
2201
+ readonly adaptiveCasterGate?: boolean;
2202
+ /**
2203
+ * How long a level waits after its own last render before an invalidation may re-render it, in
2204
+ * seconds. One value for every level, or one per level finest first, the last entry standing in
2205
+ * for the rest. Default `0.25 * extent / finestExtent` — 0.25 s, 1 s and 3.33 s for extents
2206
+ * 24 / 96 / 320 — and `0` renders on the very next frame, which is what the node did before.
2207
+ *
2208
+ * A streamed world invalidates its shadows on every residency update, and a cell admitted at the
2209
+ * ring edge lands in the coarsest window: the level that redraws for it is the one paying for the
2210
+ * whole ring's wide casters, ten times a second where movement alone asks for two. A level
2211
+ * waiting out its delay keeps the map and window it has, which is already right for every static
2212
+ * caster in it, so only a newly streamed caster is missing — the trade is that a far tree's
2213
+ * shadow can appear up to the delay late (3.33 s at extent 320, invisible on a level whose texel
2214
+ * is wider than the tree). A window that moved is never delayed: that is a different reason, and
2215
+ * it is not this option's.
2216
+ */
2217
+ readonly invalidationDelay?: number | readonly number[];
2218
+ /**
2219
+ * How far behind the window centre each level camera sits, in world units. Default 200. An
2220
+ * explicit `lightDistance` *and* `depthRange` switch the level's light-space depth off the derived
2221
+ * span below and back onto this pair, so a game that knows its own world sizes can still say so.
1725
2222
  */
1726
- readonly selectionGuard?: number;
1727
- /** How far behind the window centre each level camera sits, in world units. Default 200. */
1728
2223
  readonly lightDistance?: number;
1729
- /** Depth range each level camera covers past its centre, in world units. Default 400. */
2224
+ /**
2225
+ * Depth range each level camera covers past its centre, in world units. Default 400. Read only
2226
+ * together with `lightDistance`; on its own the span is still derived.
2227
+ */
1730
2228
  readonly depthRange?: number;
2229
+ /**
2230
+ * Texels of a level a caster must cover before it draws into that level, default 1.5. A level's
2231
+ * texel is `2 * extent / mapSize`, so the finest levels keep everything and the coarse ones keep
2232
+ * only what they can resolve: a fern is a whole number of texels in a 48 m window and a fraction
2233
+ * of one in a 640 m window, so it stops being drawn there and the shadow it casts is the ground
2234
+ * cover's own, not its silhouette's. Set 0 to draw every caster into every level.
2235
+ */
2236
+ readonly minCasterTexels?: number;
2237
+ /** Follow the framed receiving surface when the eye is more than one fine extent above it.
2238
+ * Default true; false keeps eye follow for every camera. Walking cameras keep eye follow.
2239
+ */
2240
+ readonly followViewFocus?: boolean;
2241
+ /** Measure receiver-plane slope across each level's texel footprint to prevent coarse acne.
2242
+ * Default true; false preserves only the authored bias. Custom filterNode owns its footprint.
2243
+ */
2244
+ readonly receiverPlaneBias?: boolean;
2245
+ /**
2246
+ * Draw registered AutoLOD chains with their coarsest geometry past the finest level, default true.
2247
+ * Alpha-tested and transparent casters keep casting on every level that resolves their bounds;
2248
+ * dropping their whole shadow at the fine window edge loses canopy and fences.
2249
+ * Geometry swaps are restored before the next level, mover map and main pass.
2250
+ */
2251
+ readonly shadowLodBias?: boolean;
2252
+ /**
2253
+ * Redraw only the pages an invalidation dirtied, default true. A level whose window did not move
2254
+ * and whose asks named under half its pages renders those rectangles alone: pages casters were
2255
+ * removed from are put back to the far plane first, pages casters streamed into are just drawn.
2256
+ * `false` renders the whole level for every invalidation, as before. A VSM shadow map always
2257
+ * renders whole, because its blur pass reads the entire map.
2258
+ */
2259
+ readonly partialRedraw?: boolean;
2260
+ /**
2261
+ * Quiet frames before an automatically detected mover goes back into the cached levels, default
2262
+ * 100 (Unreal's `FramesStaticThreshold`). A caster whose world matrix, instance matrix or
2263
+ * deformation changed is drawn through the mover maps without a `trackCaster` call; this is how
2264
+ * long it must hold still before its shadow is baked into the cache again. Positive integer.
2265
+ */
2266
+ readonly staticAfterFrames?: number;
1731
2267
  /** Print the `TN_VIRTUAL_SHADOW` line every `markerEvery` frames; `false` silences it. Default 300. */
1732
2268
  readonly marker?: boolean | number;
1733
2269
  }
@@ -1741,14 +2277,118 @@ interface IVirtualShadowStats {
1741
2277
  readonly invalidated: number;
1742
2278
  /** Tracked casters, as of this frame. */
1743
2279
  readonly movers: number;
2280
+ /**
2281
+ * Casters the node classified as movers by measuring them, as of this frame: a world or instance
2282
+ * matrix that changed, or a deforming mesh. Counted apart from {@link movers}, which is `trackCaster`.
2283
+ */
2284
+ readonly autoMovers: number;
2285
+ /**
2286
+ * Static-to-mover and mover-to-static changes of those casters over the node's lifetime. Each one
2287
+ * asks the levels for one region redraw, never a full one.
2288
+ */
2289
+ readonly autoTransitions: number;
2290
+ /**
2291
+ * Mean JS time of the classification scan per frame, in milliseconds, over the node's lifetime.
2292
+ * It is the number the scan's 0.05 ms budget is judged against.
2293
+ */
2294
+ readonly autoScanMs: number;
1744
2295
  /** Mover maps rendered this frame: one per level when at least one caster is tracked. */
1745
2296
  readonly moverRenders: number;
1746
2297
  /** Levels served from their cached map this frame. */
1747
2298
  readonly cached: number;
1748
2299
  /** Levels rendered this frame, for any reason. */
1749
2300
  readonly rendered: number;
2301
+ /**
2302
+ * Levels that wanted a render this frame and did not get one, because the node renders at most
2303
+ * one level per frame. They keep the map they already have and come due again next frame.
2304
+ */
2305
+ readonly deferred: number;
2306
+ /**
2307
+ * Levels holding a redraw for an invalidation that is still inside its own `invalidationDelay`,
2308
+ * so this frame is not the frame they render on. They keep the map they have, which is right for
2309
+ * every static caster in it: only a caster streamed in since is missing, and the cumulative
2310
+ * `coalesced` below is what is being waited out.
2311
+ */
2312
+ readonly held: number;
1750
2313
  /** Fraction of levels served from cache over the node's lifetime. */
1751
2314
  readonly reuseRatio: number;
2315
+ /**
2316
+ * Level renders over the node's lifetime, for any reason. `byMove` and `byInvalidation` are the two
2317
+ * the node has — a window that moved, and an invalidation that asked and waited out its delay — and
2318
+ * they add up to this exactly, because a render the single per-frame budget defers is counted
2319
+ * against the reason that queued it and not again when it is finally taken.
2320
+ */
2321
+ readonly rendersTotal: number;
2322
+ /** Of those, the renders taken because a level's window moved. */
2323
+ readonly byMove: number;
2324
+ /**
2325
+ * Pages every level's window travelled between its renders, over the node's lifetime: the sum of
2326
+ * `|ΔminX| + |ΔminY|` at each render. Unlike `byMove` it does not depend on how many frames sampled
2327
+ * the path, so two runs of one route at different frame rates report the same number.
2328
+ */
2329
+ readonly windowSteps: number;
2330
+ /** Of those, the renders taken because an invalidation asked and its level's delay had passed. */
2331
+ readonly byInvalidation: number;
2332
+ /** Of the renders taken for an invalidation (`byInvalidation`), those whose dirty set held only streamed-in casters. */
2333
+ readonly byAdmission: number;
2334
+ /** 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. */
2335
+ readonly byEviction: number;
2336
+ /** Pages the dirty set held at each render, summed over the node's lifetime. A window move counts the whole level. */
2337
+ readonly pagesDirty: number;
2338
+ /** Pages each render actually drew, summed over the node's lifetime. Equals pagesDirty once a partial redraw exists. */
2339
+ readonly pagesRedrawn: number;
2340
+ /**
2341
+ * Invalidation asks that cost no render of their own, over the node's lifetime: absorbed by a
2342
+ * render the level was taking anyway for its window, or merged into an ask already waiting out
2343
+ * that level's delay. The two of these are the shape of the win — with the default delays a walk
2344
+ * asks once a second and renders about that often, and every ask in between is counted here.
2345
+ */
2346
+ readonly coalesced: number;
2347
+ /**
2348
+ * The same four counters per level, finest first: which window moved, which invalidation asked
2349
+ * for a redraw, which level took the frame's single render, and which wanted one and did not get
2350
+ * it. One entry per level per frame, so a harness reading this — or the `TN_VIRTUAL_SHADOW`
2351
+ * marker line, which carries it — can see which level a walk keeps re-rendering instead of only
2352
+ * how many.
2353
+ */
2354
+ readonly perLevel: readonly IVirtualShadowLevelStat[];
2355
+ }
2356
+ /** One level's row of {@link IVirtualShadowStats}: 1 or 0 per counter, per frame. */
2357
+ interface IVirtualShadowLevelStat {
2358
+ /** The level's clip extent, in world units. */
2359
+ readonly extent: number;
2360
+ readonly deferred: number;
2361
+ readonly invalidated: number;
2362
+ readonly moved: number;
2363
+ readonly rendered: number;
2364
+ /** Caster meshes this level's chosen camera layers submit this frame. Zero if it did not render. */
2365
+ readonly draws: number;
2366
+ /** The same bill split by kind; the five parts sum to {@link draws}. */
2367
+ readonly drawsBy: IVirtualShadowDraws;
2368
+ /** The adaptive caster gate's scale on this level, 1 when it is not shedding casters. */
2369
+ readonly gateScale: number;
2370
+ /** Casters the gate hid on the render this level took this frame; zero if it did not render. */
2371
+ readonly gateHidden: number;
2372
+ }
2373
+ /** One level's caster draws, by the kind of mesh that submitted them. */
2374
+ interface IVirtualShadowDraws {
2375
+ /** Caster batch meshes on the cluster layer, when the cluster half is the level's choice. */
2376
+ readonly cluster: number;
2377
+ /** Key-wide caster meshes on the wide layer, when the wide half is the level's choice. */
2378
+ readonly wide: number;
2379
+ /** Small casters, submitted by the finest level and by any level rendering a prewarm. */
2380
+ readonly small: number;
2381
+ /** Merged per-chunk shadow proxies (`<name>-shadow`), drawn with either caster half. */
2382
+ readonly chunkProxy: number;
2383
+ /** Everything else casting from layer 0 — terrain, props — which every level draws. */
2384
+ readonly layer0: number;
2385
+ /**
2386
+ * GPU-scene keys: one mesh per `asset:level:part` drawn from the level's own twin of the dispatch's
2387
+ * output, which is the whole of what a keyed map submits of the world. Zero unless a provider
2388
+ * registered and `?tnShadowGpuKeys=1` asked, and then it replaces {@link cluster} and {@link wide}
2389
+ * rather than adding to them: the keys draw the placements those two would have.
2390
+ */
2391
+ readonly keys: number;
1752
2392
  }
1753
2393
  declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
1754
2394
  /**
@@ -1756,6 +2396,21 @@ declare const VIRTUAL_SHADOW_MARKER = "TN_VIRTUAL_SHADOW";
1756
2396
  * Keep it free of other uses; the main camera never needs it (tracked objects keep layer 0).
1757
2397
  */
1758
2398
  declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
2399
+ /**
2400
+ * The object layer a shadow-only caster is put on, so each level's own shadow camera renders it and
2401
+ * the main camera never sees it. The level cameras have it enabled already; an object that exists
2402
+ * only as a shadow caster calls `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)`.
2403
+ */
2404
+ declare const VIRTUAL_SHADOW_CASTER_LAYER = 28;
2405
+ /**
2406
+ * The wide counterpart of {@link VIRTUAL_SHADOW_CASTER_LAYER}: one caster mesh per
2407
+ * `asset:level:part` holding every resident cell's records, for the levels whose window covers the
2408
+ * whole resident ring. A level renders exactly one of the two caster layers — whichever submits
2409
+ * fewer draws, counted off the meshes themselves, because a cluster per square is a draw per square
2410
+ * for the same pixels once the window holds the ring. `WorldCells` writes both halves of every key,
2411
+ * so whichever a level picks is there; the main camera renders neither.
2412
+ */
2413
+ declare const VIRTUAL_SHADOW_WIDE_CASTER_LAYER = 27;
1759
2414
  /**
1760
2415
  * One directional shadow for a whole open world: camera-centred clip levels, each snapped to its
1761
2416
  * own texel grid and re-rendered only when its window moves. Movers never touch that cache: a
@@ -1770,7 +2425,9 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
1770
2425
  * map type and filter, and those source settings are mirrored into each stock level node before
1771
2426
  * rendering. Per-level map sizes, cameras, `autoUpdate` and `needsUpdate` are owned by this node.
1772
2427
  * Each level is rendered by the stock {@link ShadowNode} through the renderer's shadow-map type,
1773
- * so the look is the same code path a plain shadow uses.
2428
+ * so the look is the same code path a plain shadow uses. At most one level renders per frame,
2429
+ * finest first — a level render is a whole scene draw, and a level passed over keeps the map and
2430
+ * window it has, so a fragment only ever samples a map that level drew.
1774
2431
  *
1775
2432
  * Ported from the virtual-shadow-map prototype's clipmap and invalidation; the sparse page atlas
1776
2433
  * is deliberately not the first cut — a page needs the scene rendered once per page, and on a
@@ -1783,8 +2440,10 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
1783
2440
  * @situation shadows shimmer when the camera moves
1784
2441
  * @constraint the light must be a DirectionalLight with `castShadow` and a target in the scene
1785
2442
  * @constraint clipExtents are half-widths in world units, finest first, strictly increasing
1786
- * @constraint call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves
2443
+ * @constraint movers sort themselves: a layer-0 caster whose world matrix, instance matrix or deformation changed draws through the mover maps and leaves the cached levels, and returns to them after `staticAfterFrames` quiet frames; the cache redraws only the region it left
2444
+ * @constraint `trackCaster(object)` is the override that pins an object as a mover for good (it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants), and `pinStatic(object)` opts an object out of detection; tracking or untracking refreshes only that object's region
1787
2445
  * @override bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults
2446
+ * @override followViewFocus: false keeps eye follow; receiverPlaneBias: false uses only authored bias
1788
2447
  * @example
1789
2448
  * const sun = new DirectionalLight(0xffffff, 3);
1790
2449
  * sun.castShadow = true;
@@ -1793,8 +2452,18 @@ declare const VIRTUAL_SHADOW_MOVER_LAYER = 29;
1793
2452
  declare class VirtualShadowNode extends ShadowBaseNode {
1794
2453
  #private;
1795
2454
  static get type(): string;
1796
- readonly options: Required<Omit<IVirtualShadowOptions, "marker">> & {
2455
+ readonly options: Required<Omit<IVirtualShadowOptions, "marker" | "refreshStep" | "selectionGuard" | "invalidationDelay">> & {
1797
2456
  readonly markerEvery: number;
2457
+ /** Per level, finest first; the last entry stands in for every level past it. */
2458
+ readonly refreshStep: readonly number[];
2459
+ /** The per-level `selectionGuard` each level's own window is drawn with. */
2460
+ readonly selectionGuard: readonly number[];
2461
+ /**
2462
+ * Per level, finest first: the seconds a dirty level waits after its own last render before an
2463
+ * invalidation may re-render it. Already scaled by that level's extent, so the fine levels
2464
+ * answer a streamed caster promptly and the coarse ones let a burst merge into one render.
2465
+ */
2466
+ readonly invalidationDelay: readonly number[];
1798
2467
  };
1799
2468
  readonly clipmap: DirectionalClipmap;
1800
2469
  /**
@@ -1818,8 +2487,32 @@ declare class VirtualShadowNode extends ShadowBaseNode {
1818
2487
  */
1819
2488
  trackCaster(object: Object3D): string;
1820
2489
  untrackCaster(objectOrId: Object3D | string): boolean;
2490
+ /**
2491
+ * Keep an object and its descendants out of automatic mover detection: they are static casters
2492
+ * whatever their transforms do, so a game that moves one takes on the stale shadow itself, or
2493
+ * calls `invalidateRegion`. Takes effect from the next frame.
2494
+ */
2495
+ pinStatic(object: Object3D): void;
1821
2496
  /** Force every level to re-render on the next frame — a tree fell, a door opened. */
1822
2497
  invalidateAll(): void;
2498
+ /**
2499
+ * Force only the levels whose current window covers `bounds`, on the next frame. A streamed world
2500
+ * that hands its shadow casters over has a moving near set, and a blanket `invalidateAll()` on
2501
+ * every refresh redrew all three levels for a change that lands in one corner of one of them. A
2502
+ * level whose window does not cover the region draws the same thing either way, so skipping it is
2503
+ * the same frame with fewer draws in it.
2504
+ *
2505
+ * `bounds` is `{ min: {x,y,z}, max: {x,y,z} }`, a plain object so a game can hand one over without
2506
+ * importing three. Regions are consumed by the next `updateBefore`; one that arrives before the
2507
+ * levels exist is dropped, because their first frame renders all of them anyway.
2508
+ *
2509
+ * `admission` says the region only gained casters. An added caster can only bring a texel's depth
2510
+ * closer, so a redraw for admissions alone never has to clear what the map already holds. The
2511
+ * default reads `bounds.admission === true`; an explicit second argument overrides it.
2512
+ */
2513
+ invalidateRegion(bounds: IBoundsLike & {
2514
+ admission?: boolean;
2515
+ }, admission?: boolean): void;
1823
2516
  setup(builder: NodeBuilder): Node | null | undefined;
1824
2517
  updateBefore(frame: NodeFrame): undefined;
1825
2518
  dispose(): void;
@@ -1835,6 +2528,91 @@ declare class VirtualShadowNode extends ShadowBaseNode {
1835
2528
  */
1836
2529
  declare function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined;
1837
2530
 
2531
+ /** Every value is the game's: this rig wires them and chooses none. */
2532
+ interface IDaylightOptions {
2533
+ /** The eye the sky, the sun's shadow windows and the haze centre on; usually the camera. */
2534
+ readonly follow: Object3D;
2535
+ /** Unit vector from the ground towards the sun. */
2536
+ readonly sunDirection: Vector3;
2537
+ readonly sunColor: Color;
2538
+ /** Irradiance in three's physical units; the same number a Blender sun strength carries. */
2539
+ readonly sunIntensity: number;
2540
+ /** Half-widths of the shadow windows in world units, finest first, strictly increasing. */
2541
+ readonly shadowExtents: readonly number[];
2542
+ /** Texels per shadow level edge; a level's texel is `2 * extent / shadowMapSize`. Default: the sun's `shadow.mapSize.width` (512). */
2543
+ readonly shadowMapSize?: number;
2544
+ /**
2545
+ * How far a window may trail the camera before it re-renders, as a fraction of its own extent:
2546
+ * one value for every level, or one per level finest first, the last entry standing in for the
2547
+ * rest. One for all of them spends the hysteresis the fine level can least afford on the coarse
2548
+ * one, which is the level a walking camera re-renders least. Default 0.125.
2549
+ */
2550
+ readonly refreshStep?: number | readonly number[];
2551
+ /** Preetham sky parameters, as three's `SkyMesh` takes them. */
2552
+ readonly sky: {
2553
+ readonly turbidity: number;
2554
+ readonly rayleigh: number;
2555
+ readonly mieCoefficient: number;
2556
+ readonly mieDirectionalG: number;
2557
+ };
2558
+ /** Sky fill from above and bounce from below, as a hemisphere light. */
2559
+ readonly fill: {
2560
+ readonly sky: Color;
2561
+ readonly ground: Color;
2562
+ readonly intensity: number;
2563
+ };
2564
+ /** Exponential-squared haze in the sky's horizon colour, so distance fades into the sky. */
2565
+ readonly haze: {
2566
+ readonly color: Color;
2567
+ readonly density: number;
2568
+ };
2569
+ /** Linear exposure multiplier for the tone curve (2^EV). */
2570
+ readonly exposure: number;
2571
+ /** The tone curve, a look the game picks; AgX when it names none. */
2572
+ readonly toneMapping?: ToneMapping;
2573
+ /**
2574
+ * Edge of the sky box in world units. It must sit inside the camera's far plane with its corners
2575
+ * included (a box, so half-diagonal ≈ 0.87 × this).
2576
+ */
2577
+ readonly skySize: number;
2578
+ }
2579
+ /**
2580
+ * An outdoor daylight rig: a physical sky that stays on the eye, one sun whose open-world shadow
2581
+ * windows follow the eye (`VirtualShadowNode`), a hemisphere fill, sky-coloured distance haze and
2582
+ * the AgX tone curve at the game's exposure. It is plumbing, not a look: every colour, angle,
2583
+ * intensity and density is a required option, and the rig adds nothing a game did not ask for.
2584
+ *
2585
+ * Add it with `ctx.add(daylight)`: `attachRenderer` sets tone mapping, exposure and the shadow map
2586
+ * once, and `process` (render cadence) keeps the sky box, the sun and its target on the eye every
2587
+ * frame, so a 2 km map never walks out of its own sky or shadow.
2588
+ *
2589
+ * @situation daytime sky, sun and shadows for a large outdoor map
2590
+ * @situation distant terrain should fade into the sky instead of a coloured wall
2591
+ * @situation match a Blender look-dev scene's sun, sky and exposure in the game
2592
+ * @constraint every value is required; there is no default sun, sky, haze or exposure
2593
+ * @constraint `skySize` must keep the sky box's corners inside the camera's far plane
2594
+ * @constraint shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
2595
+ * @override sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
2596
+ * @example
2597
+ * const daylight = new Daylight({ follow: ctx.camera, sunDirection, sunColor, sunIntensity: 4, shadowExtents: [24, 96, 320], sky: { turbidity: 3, rayleigh: 1.4, mieCoefficient: 0.004, mieDirectionalG: 0.8 }, fill: { sky, ground, intensity: 1.1 }, haze: { color: horizon, density: 0.0011 }, exposure: 2 ** -0.6, skySize: 1600 });
2598
+ * ctx.add(daylight);
2599
+ */
2600
+ declare class Daylight extends Group implements IComputeDriven$1 {
2601
+ #private;
2602
+ readonly warmupNodes: readonly unknown[];
2603
+ readonly processCadence: "render";
2604
+ readonly sky: SkyMesh;
2605
+ readonly sun: DirectionalLight;
2606
+ readonly fill: HemisphereLight;
2607
+ constructor(options: IDaylightOptions);
2608
+ get released(): boolean;
2609
+ /** The haze this rig owns; `attachRenderer` puts it on the scene the rig was added to. */
2610
+ get haze(): FogExp2;
2611
+ attachRenderer(renderer: IRendererLike): void;
2612
+ process(): void;
2613
+ detach(): void;
2614
+ }
2615
+
1838
2616
  /**
1839
2617
  * Two load-time mechanisms every streaming game writes by hand, and gets wrong in the same places.
1840
2618
  *
@@ -1879,18 +2657,13 @@ interface IAddInSlicesProgress {
1879
2657
  }
1880
2658
  interface IAddInSlicesOptions {
1881
2659
  /**
1882
- * Objects attached between presented frames. Default 256.
2660
+ * Objects attached between presented frames, when the game wants that count.
1883
2661
  *
1884
- * The default is large because the reason it used to be small has been taken over by something
1885
- * better. One per frame was right when nothing else compiled the world: the renderer built a few
1886
- * newly visible pipelines per presented frame instead of all of them inside one multi-second
1887
- * frame. It is not right once the framework warms the held scene (`warmUpScene`) — the compile is
1888
- * then paid either way and the slice only chooses where, so a small slice buys nothing and costs
1889
- * one present per object.
1890
- *
1891
- * 256 is where the measured curve flattens without giving up the yields entirely: over a few
1892
- * hundred objects it still presents a handful of frames, so a browser watchdog cannot see a hung
1893
- * page, and it costs nothing against attaching everything in one go.
2662
+ * Omitted, a slice ends on elapsed time instead: the loop measures what the game's own `add`
2663
+ * costs, in the place where the cost is paid, and presents a frame once the slice has run for its
2664
+ * budget. Objects that cost nothing stop paying a frame each, and objects that cost more than any
2665
+ * fixed count allows get cut sooner than that count would. Given, the count decides and the budget
2666
+ * is not used at all.
1894
2667
  */
1895
2668
  readonly sliceSize?: number;
1896
2669
  /** Called once per slice, and once more for a partial final slice. */
@@ -1919,14 +2692,19 @@ interface IAddInSlicesReport {
1919
2692
  readonly added: number;
1920
2693
  /** Objects the run was given. */
1921
2694
  readonly total: number;
1922
- /** Slices the work was cut into, and therefore the frames the loop got to present, plus one. */
2695
+ /** Slices the work was cut into: one host turn between each, several of which can share a frame. */
1923
2696
  readonly slices: number;
1924
2697
  /** Wall-clock milliseconds the run took, attaching and yielding together. */
1925
2698
  readonly elapsedMs: number;
1926
- /** The slice size actually used — the default, or the one the game chose. */
2699
+ /**
2700
+ * Objects per slice this run actually landed on: the count the game chose, or — when
2701
+ * the budget chose — the measured average, which is the number a caller copies into `sliceSize`.
2702
+ */
1927
2703
  readonly sliceSize: number;
1928
- /** Whether that slice size came from the game rather than from the default. */
2704
+ /** Whether that count came from the game rather than from the engine. */
1929
2705
  readonly sliceSizeOverridden: boolean;
2706
+ /** Milliseconds of attaching one slice may spend before it presents. Absent when the game gave a count. */
2707
+ readonly sliceBudgetMs?: number;
1930
2708
  /** True when `while` ended the run early. `added` is then less than `total`. */
1931
2709
  readonly stopped: boolean;
1932
2710
  }
@@ -2042,7 +2820,7 @@ interface ISpectralOceanOptions {
2042
2820
  *
2043
2821
  * This is not the simulation resolution. It is the size of the only thing copied back off the
2044
2822
  * GPU, so it is the whole cost of being able to float something: `readbackResolution` squared
2045
- * floats, every `readbackEveryFrames` frames.
2823
+ * pairs of height and vertical-velocity floats, every `readbackEveryFrames` frames.
2046
2824
  */
2047
2825
  readonly readbackResolution: number;
2048
2826
  /** Frames between height copies. Ignored when `readbackResolution` is zero. */
@@ -2051,6 +2829,8 @@ interface ISpectralOceanOptions {
2051
2829
  /** A height read from the CPU copy, with the age of the frame that produced it. */
2052
2830
  interface ISpectralOceanHeight {
2053
2831
  readonly height: number;
2832
+ /** Metres per second at this same point and sample time, for temporal age correction. */
2833
+ readonly verticalVelocity: number;
2054
2834
  /**
2055
2835
  * Frames between the GPU state this height came from and now.
2056
2836
  *
@@ -2109,12 +2889,109 @@ declare class SpectralOcean extends Object3D implements IComputeDriven$1 {
2109
2889
  interface IGPUParticles3DBuffers {
2110
2890
  readonly positions: StorageBufferNode<"vec3">;
2111
2891
  readonly velocities: StorageBufferNode<"vec3">;
2112
- }
2113
- interface IGPUParticles3DOptions {
2892
+ /** Emitter-clock second of each slot's last spawn. Present only when `spawn` is given. */
2893
+ readonly births?: StorageBufferNode<"float">;
2894
+ }
2895
+ /** The engine clock, as TSL nodes, handed to `process` as its second argument. */
2896
+ interface IGPUParticles3DRuntime {
2897
+ readonly time: Node$1<"float">;
2898
+ readonly delta: Node$1<"float">;
2899
+ }
2900
+ /** Engine-owned uniforms for one `emitParticle` call. The slot is `(first + instanceIndex) % amount`. */
2901
+ interface IGPUParticles3DSpawnRequest {
2902
+ readonly first: UniformNode$1<"uint", number>;
2903
+ readonly count: UniformNode$1<"uint", number>;
2904
+ readonly origin: UniformNode$1<"vec3", Vector3>;
2905
+ readonly direction: UniformNode$1<"vec3", Vector3>;
2906
+ readonly seed: UniformNode$1<"float", number>;
2907
+ readonly time: Node$1<"float">;
2908
+ }
2909
+ /** Buffers a spawn-driven emitter's kernels receive: `births` always exists. */
2910
+ interface IGPUParticles3DSpawnBuffers extends IGPUParticles3DBuffers {
2911
+ readonly births: StorageBufferNode<"float">;
2912
+ }
2913
+ interface IGPUParticles3DBaseOptions {
2114
2914
  readonly amount: number;
2115
2915
  readonly material: SpriteNodeMaterial;
2916
+ /** World space when `spawn` is given, emitter space otherwise. */
2917
+ readonly localCoords?: boolean;
2918
+ /**
2919
+ * Override the local bounds from frame zero and skip GPU measurement.
2920
+ * @situation Supply known bounds for a particle cloud.
2921
+ * @constraint Must be a finite, non-empty box in the emitter's local space.
2922
+ */
2923
+ readonly bounds?: Box3;
2924
+ /**
2925
+ * Metres added around the world box. Defaults to half the largest world scale.
2926
+ * @situation Cover the sprite quad; name padding when the material uses scaleNode.
2927
+ * @constraint Must be finite and non-negative, in world metres.
2928
+ */
2929
+ readonly padding?: number;
2930
+ /**
2931
+ * Keep buffers on pause, or restart on return with clear. Defaults to pause.
2932
+ * @situation Choose whether a returning effect continues or starts again.
2933
+ * @constraint Must be pause or clear.
2934
+ */
2935
+ readonly onCull?: "pause" | "clear";
2936
+ /**
2937
+ * Seconds continuously outside the view before culling. Defaults to 1.
2938
+ * @situation Avoid toggling effects near the view edge; Infinity disables view culling.
2939
+ * @constraint Must be non-negative; Infinity is allowed.
2940
+ */
2941
+ readonly graceSeconds?: number;
2942
+ /**
2943
+ * Frames between GPU bounds measurements. Defaults to 8.
2944
+ * @situation Trade readback cost for a delayed view of the cloud bounds.
2945
+ * @constraint Must be a positive integer; paused emitters do not measure.
2946
+ */
2947
+ readonly boundsEveryFrames?: number;
2948
+ }
2949
+ /** The closed-form tier: every particle is a function of time, `start` seeds the buffers. */
2950
+ interface IGPUParticles3DClosedFormOptions extends IGPUParticles3DBaseOptions {
2116
2951
  readonly start: (buffers: IGPUParticles3DBuffers) => ComputeNode;
2117
- readonly process: (buffers: IGPUParticles3DBuffers) => ComputeNode;
2952
+ readonly process: (buffers: IGPUParticles3DBuffers, runtime: IGPUParticles3DRuntime) => ComputeNode;
2953
+ readonly spawn?: undefined;
2954
+ readonly lifetime?: undefined;
2955
+ readonly maxSpawnPerFrame?: undefined;
2956
+ }
2957
+ /** The spawn tier: a burst is a request, and the engine owns the slots and the birth stamps. */
2958
+ interface IGPUParticles3DSpawnOptions extends IGPUParticles3DBaseOptions {
2959
+ /** Optional here: the engine already resets every birth. */
2960
+ readonly start?: (buffers: IGPUParticles3DSpawnBuffers) => ComputeNode;
2961
+ readonly process: (buffers: IGPUParticles3DSpawnBuffers, runtime: IGPUParticles3DRuntime) => ComputeNode;
2962
+ /**
2963
+ * Writes one burst. Dispatched over `amount` threads per `emitParticle`: a thread with
2964
+ * `instanceIndex >= request.count` returns at once. ponytail: costs `amount` threads per emit;
2965
+ * upgrade to an indirect dispatch of `count` threads if `amount` passes about 100,000.
2966
+ */
2967
+ readonly spawn: (buffers: IGPUParticles3DSpawnBuffers, request: IGPUParticles3DSpawnRequest) => ComputeNode;
2968
+ /** Game-owned longest life in seconds. Lets `stats.recycledLive` count slots recycled while alive. */
2969
+ readonly lifetime?: number;
2970
+ /** Cap on particles spawned between two `process` calls. Defaults to `amount`. */
2971
+ readonly maxSpawnPerFrame?: number;
2972
+ }
2973
+ type IGPUParticles3DOptions = IGPUParticles3DClosedFormOptions | IGPUParticles3DSpawnOptions;
2974
+ interface IEmitParticleRequest {
2975
+ readonly count?: number;
2976
+ readonly origin?: {
2977
+ readonly x: number;
2978
+ readonly y: number;
2979
+ readonly z: number;
2980
+ };
2981
+ readonly direction?: {
2982
+ readonly x: number;
2983
+ readonly y: number;
2984
+ readonly z: number;
2985
+ };
2986
+ readonly seed?: number;
2987
+ }
2988
+ interface IGPUParticles3DStats {
2989
+ /** Particles requested but not spawned (over `amount` or over `maxSpawnPerFrame`). */
2990
+ readonly clamped: number;
2991
+ /** Particles spawned. */
2992
+ readonly spawned: number;
2993
+ /** Live slots overwritten by the ring. `undefined` without the `lifetime` option, never `0`. */
2994
+ readonly recycledLive: number | undefined;
2118
2995
  }
2119
2996
  declare class GPUParticles3D extends Sprite implements IComputeDriven$1 {
2120
2997
  #private;
@@ -2122,11 +2999,34 @@ declare class GPUParticles3D extends Sprite implements IComputeDriven$1 {
2122
2999
  readonly buffers: IGPUParticles3DBuffers;
2123
3000
  readonly processCadence: "render";
2124
3001
  readonly warmupNodes: readonly ComputeNode[];
3002
+ readonly localCoords: boolean;
2125
3003
  emitting: boolean;
3004
+ /** Cooperate with measured frame-budget shedding without changing particle storage. */
3005
+ readonly budget: IBudgetCandidate;
2126
3006
  constructor(options: IGPUParticles3DOptions);
2127
3007
  get released(): boolean;
3008
+ get stats(): IGPUParticles3DStats;
3009
+ /** Seconds outside view before culling; Infinity disables it at runtime. */
3010
+ get graceSeconds(): number;
3011
+ set graceSeconds(value: number);
2128
3012
  attachRenderer(renderer: IRendererLike): void;
2129
- process(renderer?: IRendererLike | undefined): void;
3013
+ /** The override or newest landed local bounds; absent until a valid sample lands. */
3014
+ get measuredBounds(): Box3 | undefined;
3015
+ /** Simulation compute calls, excluding starts and bounds reduction. */
3016
+ get dispatches(): number;
3017
+ /** Current cull state and the number of state changes. */
3018
+ get cull(): {
3019
+ readonly state: "running" | "paused" | "cleared";
3020
+ readonly reason: "outside-view" | "over-budget" | undefined;
3021
+ readonly transitions: number;
3022
+ };
3023
+ process(renderer?: IRendererLike | undefined, camera?: Camera, _covered?: boolean, _view?: undefined, simulatedSeconds?: number): void;
3024
+ /**
3025
+ * Spawns `count` particles at `origin` (world space unless `localCoords`). Every call gets its own ring
3026
+ * slots, so a second burst never touches the first one's live particles. No readback.
3027
+ */
3028
+ emitParticle(request?: IEmitParticleRequest): void;
3029
+ /** Reruns `start`. A spawn-driven emitter instead kills every particle and rewinds the ring. */
2130
3030
  restart(): void;
2131
3031
  detach(): void;
2132
3032
  }
@@ -2188,6 +3088,154 @@ declare class FluidField2D extends Group {
2188
3088
  detach(): void;
2189
3089
  }
2190
3090
 
3091
+ type Vec3 = readonly [number, number, number];
3092
+ type Vec4 = readonly [number, number, number, number];
3093
+ declare const instancedArray: any;
3094
+ interface IFluidBounds {
3095
+ readonly min: Vec3;
3096
+ readonly max: Vec3;
3097
+ }
3098
+ /** An obstacle the water flows around. Boxes carry an xyzw quaternion; spheres have no orientation. */
3099
+ type IFluidCollider = {
3100
+ readonly kind: "sphere";
3101
+ readonly center: Vec3;
3102
+ readonly radius: number;
3103
+ } | {
3104
+ readonly kind: "box";
3105
+ readonly center: Vec3;
3106
+ readonly halfExtents: Vec3;
3107
+ readonly rotation?: Vec4;
3108
+ };
3109
+ interface IFluidParticlesOptions {
3110
+ /** Particle slots. The solver never holds more than this many live particles. */
3111
+ readonly capacity: number;
3112
+ /** Rest spacing in metres. The smoothing radius is twice this. */
3113
+ readonly spacing?: number;
3114
+ /** The container. Particles are projected back inside it every iteration. */
3115
+ readonly bounds?: IFluidBounds;
3116
+ /** Density-constraint iterations per fixed step, 0 to 8. */
3117
+ readonly iterations?: number;
3118
+ readonly viscosity?: number;
3119
+ readonly cohesion?: number;
3120
+ readonly vorticity?: number;
3121
+ readonly gravity?: number;
3122
+ /** Vector speed limit in m/s. Prediction projects radius-sized segments; this is not swept CCD. */
3123
+ readonly maxSpeed?: number;
3124
+ readonly timeStep?: number;
3125
+ /** Colliders updated per step through `setColliders`. */
3126
+ readonly maxColliders?: number;
3127
+ /** Queued `fill`/`emit` calls consumed per step. Extra calls return `false`. */
3128
+ readonly maxSpawns?: number;
3129
+ /** Voxel edge of the density volume, in metres. Defaults to half the spacing. */
3130
+ readonly voxelSize?: number;
3131
+ /** Fixed steps between GPU-to-CPU copies of stats and column heights. */
3132
+ readonly readbackEvery?: number;
3133
+ /** Extra acceleration (m/s²) added to every particle, from the game's own TSL. */
3134
+ readonly force?: (position: Node$1<"vec3">, velocity: Node$1<"vec3">, time: Node$1<"float">) => Node$1;
3135
+ }
3136
+ interface IFluidParticlesStats {
3137
+ readonly count: number;
3138
+ /** Mean of `max(0, density - 1)` over live particles; 0 is incompressible. */
3139
+ readonly meanCompression: number;
3140
+ readonly maxSpeed: number;
3141
+ readonly min: Vec3;
3142
+ readonly max: Vec3;
3143
+ /** Fixed steps between the GPU state these numbers describe and now. */
3144
+ readonly staleFrames: number;
3145
+ }
3146
+ /**
3147
+ * Simulate liquid as particles on the GPU and expose the data, never the look.
3148
+ *
3149
+ * It is a Position Based Fluids solver (density constraints, XSPH viscosity, cohesion, vorticity
3150
+ * confinement) whose passes run as compute kernels every fixed step. Nothing is drawn: `positions`
3151
+ * and `velocities` are storage nodes (`.w` of `positions` is the live flag, `.w` of `velocities`
3152
+ * is a 0..1 foam hint), `density` is a 3D texture of smoothed particle density a game raymarches
3153
+ * or thresholds, and `sample(x, z)` is the free-surface height a `Buoyancy3D` consumes.
3154
+ * Appearance — refraction, absorption, foam, spray — stays in the game's `src/render/` code.
3155
+ * @situation pour, splash, or dam-break water that fills a container and flows around obstacles
3156
+ * @situation simulate water or another liquid as particles in a fluid simulation
3157
+ * @situation drop a ball or box into liquid and let it displace and float on the water
3158
+ * @situation emit a stream or waterfall of particle fluid and drain it somewhere else
3159
+ * @situation sample particle-fluid density or surface height in a game-owned render node
3160
+ * @constraint add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
3161
+ * @constraint a renderer without WebGPU compute throws a named error at attach; it never draws nothing
3162
+ * @constraint `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity
3163
+ * @constraint `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
3164
+ * @override iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
3165
+ * @example const water = new FluidParticles3D({ capacity: 6000 });
3166
+ * ctx.add(water);
3167
+ * water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
3168
+ */
3169
+ declare class FluidParticles3D extends Group {
3170
+ #private;
3171
+ readonly capacity: number;
3172
+ readonly spacing: number;
3173
+ readonly bounds: IFluidBounds;
3174
+ readonly iterations: number;
3175
+ readonly maxSpeed: number;
3176
+ readonly timeStep: number;
3177
+ readonly maxColliders: number;
3178
+ readonly maxSpawns: number;
3179
+ readonly processCadence: "fixed";
3180
+ readonly warmupNodes: readonly ComputeNode[];
3181
+ /** vec4 per slot: xyz position, w = 1 live / 0 free. */
3182
+ readonly positions: ReturnType<typeof instancedArray>;
3183
+ /** vec4 per slot: xyz velocity, w = foam 0..1. */
3184
+ readonly velocities: ReturnType<typeof instancedArray>;
3185
+ /** Smoothed particle density, ~1 inside water; sample it with `texture3D`. */
3186
+ readonly density: Storage3DTexture;
3187
+ /** Voxel counts of `density`. */
3188
+ readonly volumeSize: Vec3;
3189
+ /** World-space corner of voxel (0,0,0) and the edge length of one voxel. */
3190
+ readonly volumeOrigin: Vec3;
3191
+ readonly voxelSize: number;
3192
+ constructor(options: IFluidParticlesOptions);
3193
+ get released(): boolean;
3194
+ /** Slots handed out so far; never above `capacity`. */
3195
+ get used(): number;
3196
+ get steps(): number;
3197
+ get viscosity(): number;
3198
+ set viscosity(value: number);
3199
+ get cohesion(): number;
3200
+ set cohesion(value: number);
3201
+ get vorticity(): number;
3202
+ set vorticity(value: number);
3203
+ get gravity(): number;
3204
+ set gravity(value: number);
3205
+ attachRenderer(renderer: IRendererLike): void;
3206
+ /**
3207
+ * Place a lattice of particles in `[min, max]`, one per `spacing`, and return how many fit.
3208
+ * Particles never wrap: a full solver places none.
3209
+ */
3210
+ fill(min: Vec3, max: Vec3, velocity?: Vec3): number;
3211
+ /** Spawn one particle. Once every slot has been used the oldest slot is recycled. */
3212
+ emit(position: Vec3, velocity?: Vec3): boolean;
3213
+ /** Free every live particle inside the box on the next step. */
3214
+ drain(min: Vec3, max: Vec3): boolean;
3215
+ /** Push particles within `radius` of `point` outward and up, strongest at the centre. */
3216
+ stir(point: Vec3, strength: number, radius: number): boolean;
3217
+ /** Replace the colliders. Call it every fixed step with the bodies' current transforms. */
3218
+ setColliders(colliders: readonly IFluidCollider[]): void;
3219
+ /**
3220
+ * Free-surface height near `(x, z)`, box-filtered over open columns of the newest landed GPU
3221
+ * copy; `bounds.min.y` where no water is near or nothing has landed yet. Shaped for `Buoyancy3D`'s `surface`.
3222
+ */
3223
+ sample(x: number, z: number, _time?: number): {
3224
+ readonly height: number;
3225
+ };
3226
+ /** Surface height at `(x, z)`; see {@link sample}. */
3227
+ heightAt(x: number, z: number): number;
3228
+ /**
3229
+ * Fixed steps between the GPU state the newest copy holds and now; grows until the first copy
3230
+ * lands. `sample` and `heightAt` read the same copy, so this is their age too.
3231
+ */
3232
+ get staleFrames(): number;
3233
+ /** Counts and extremes from the newest landed GPU copy, or `undefined` before one lands. */
3234
+ get stats(): IFluidParticlesStats | undefined;
3235
+ process(renderer?: IRendererLike | undefined): void;
3236
+ detach(): void;
3237
+ }
3238
+
2191
3239
  /**
2192
3240
  * A disturbance that propagates. `WaveField` in this same package evaluates a fixed analytic
2193
3241
  * swell: it is the sea a game always has, and nothing a game does changes it. This is the other
@@ -2399,20 +3447,13 @@ interface IWaterReflectionOptions {
2399
3447
  /** Whether this surface may appear in other reflectors' passes. Off is one pass; on is n². */
2400
3448
  readonly bounces?: boolean;
2401
3449
  /**
2402
- * Which layers the mirrored pass draws, as a three `Layers` mask. Omit to draw everything the
2403
- * scene camera draws, which is the default and what a reflection means when nothing says
2404
- * otherwise.
2405
- *
2406
- * This is how much *world* the second pass costs, and on a crowded scene it is the whole bill.
2407
- * The mirrored pass is a second draw of everything, so a frame with sixty-eight aircraft in it
2408
- * pays for sixty-eight aircraft twice — once where the player can see them and once in the water,
2409
- * where they are a few pixels and half of them are behind the camera anyway. Put the big
2410
- * silhouettes a player actually reads in the water on their own layer and name it here.
2411
- *
2412
- * The mask decides what appears in the mirror, so the game owns it: this only carries the number
2413
- * through to the pass, and a game that omits it gets the whole world reflected as before.
3450
+ * Explicit Three Layers mask. Wins over automatic selection, including `1` (all layer-0 props).
3451
+ * Omit to reflect terrain-sized surfaces and large non-instanced shadow casters. Instanced and
3452
+ * skinned props are excluded automatically; sky/background and lighting remain available.
2414
3453
  */
2415
3454
  readonly layers?: number;
3455
+ /** Minimum world-space extent for automatic terrain/casters, in metres. Default 10. */
3456
+ readonly minSize?: number;
2416
3457
  /**
2417
3458
  * How often the mirrored pass redraws, in presented frames.
2418
3459
  *
@@ -2491,7 +3532,7 @@ declare class WaterSurface3D {
2491
3532
  * cannot inspect is a reflection you cannot cost. Undefined when this surface has no reflection.
2492
3533
  */
2493
3534
  reflectionCameraFor(camera: Camera): Camera | undefined;
2494
- /** What the mirrored pass draws, as the mask the game supplied. Undefined means everything. */
3535
+ /** Explicit mask supplied by the game. Undefined means automatic terrain/large-caster selection. */
2495
3536
  readonly reflectionLayers: number | undefined;
2496
3537
  /** How often the mirrored pass redraws, in presented frames. `1` is every frame, the default. */
2497
3538
  readonly reflectionRefreshInterval: number;
@@ -2938,21 +3979,6 @@ declare function measureThreePose(object: Object3D, options?: IMeasureThreePoseO
2938
3979
  */
2939
3980
  declare function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds;
2940
3981
 
2941
- type PlatformRuntime = "web" | "native";
2942
- type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
2943
- type PlatformFormFactor = "mobile" | "desktop" | "unknown";
2944
- interface IPlatformInfo {
2945
- readonly runtime: PlatformRuntime;
2946
- readonly os: PlatformOS;
2947
- readonly formFactor: PlatformFormFactor;
2948
- readonly maxTouchPoints: number;
2949
- }
2950
- declare function getPlatform(): Readonly<IPlatformInfo>;
2951
- declare function isWeb(): boolean;
2952
- declare function isNative(): boolean;
2953
- declare function isMobile(): boolean;
2954
- declare function isTouchscreenAvailable(): boolean;
2955
-
2956
3982
  type ReplayPointer = readonly [number, number, number, number, number];
2957
3983
  interface IReplayRecordingSample {
2958
3984
  readonly keys: readonly string[];
@@ -3210,6 +4236,6 @@ declare function boneLengthDeviations(root: Object3D, bind: IBoneLengthSnapshot,
3210
4236
  * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
3211
4237
  * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
3212
4238
  */
3213
- declare const version = "0.3.3";
4239
+ declare const version = "0.3.5";
3214
4240
 
3215
- export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, FlightModel, FluidField2D, FramePassKind, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type ICameraShakeOffset, type ICameraShakeOptions, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, IFrameBudgetWindow, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IPlatformInfo, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type IRippleFieldFlow, type IRippleFieldOptions, type ISceneShape, type ISceneWarning, type ISkeletalMesh3DOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISpanProbeTarget, type ISpanSummary, type ISpanWindow, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, type IStaticTransformCensus, type IStrideReport, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IValidationReport, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LUT_RESOLUTIONS, type LaunchFailureKind, type MatrixWorldMode, MatrixWorldPass, NEUTRAL_FLIGHT_MODIFIERS, type NormaliseAxis, PROBE_VOLUME_MARKER, PathFollow3D, type PlatformFormFactor, type PlatformOS, type PlatformRuntime, ProbeVolume, type ProbeVolumeDensity, RENDERLIST_VALIDATE_FLAG, RENDERLIST_VALIDATE_MARKER, type Recording, RenderListValidator, type ReplayPointer, RippleField, SCENE_WARNING_MARKER, SPANS, SPANS_FLAG, SPANS_MARKER, SPAN_COUNT, SPAN_NAMES, STATIC_TRANSFORM_MARKER, SkeletalMesh3D, SoftBody3D, type SpanId, SpanRecorder, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addInSlices, addSpan, aerodynamicCoefficients, airDensity, aircraftMass, alwaysRender, attachToBone, attitudeAxes, baseGeometryOf, beginSpan, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, describeSceneShape, describeSceneWarning, directionFromSolarPosition, directionalTransmittance, displayPeriodMs, endSpan, formatSceneWarning, formatSpansWindow, formatValidationReport, gearClearance, getPlatform, installSpanProbes, invalidateStatic, isMobile, isNative, isStatic, isTouchscreenAvailable, isWeb, loadAll, markStatic, measureThreePose, mergeParts, normaliseToMetres, onLaunchFailure, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, readVirtualShadowMarker, refreshStaticTransforms, renderListValidationRequested, replay, resetStaticTransforms, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, sceneWarning, setAttitude, setSpanRecorder, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, spanNow, spanRecorder, spansRequested, staticTransformCensus, unmarkStatic, updateAtmosphereParameters, updateClusteredMeshes, updateModelLods, validateWorldMatrices, version, zenithTransmittance };
4241
+ export { ATLAS_PADDING, ATMOSPHERE_LUT_RESOLUTIONS, AnimationComposer, AnimationPlayer, Atmosphere, type AtmosphereDirection, AtmosphereLuts, type AtmosphereRgb, Billboard3D, type BillboardLockAxis, BlendSpace1D, BlendSpace2D, CameraShake, type CameraShakeCurve, ClusteredBatch, ClusteredMesh, Daylight, ENVIRONMENT_TOO_SMALL_MARKER, FlightModel, FluidField2D, FluidParticles3D, FramePassKind, GPUParticles3D, GPUSceneBVH, type GPUSceneBVHTraceFunction, GroundSnap, type IAddInSlicesOptions, type IAddInSlicesProgress, type IAddInSlicesReport, type IAircraftAirframe, type IAnimationComposerOptions, type IAnimationLayer, type IAnimationMask, type IAnimationMotionDelta, type IAnimationPlayOptions, type IAnimationPlayerOptions, type IAnimationRootMotionOptions, type IAtmosphereLutResolution, type IAtmosphereLutResolutions, type IAtmosphereOptions, type IAtmosphereParameterPatch, type IAtmosphereParameters, type IAtmosphereScenePass, type IBillboard3DOptions, type IBoneContactReport, type IBoneLengthDeviation, type IBoneLengthDeviationReport, type IBoneLengthDeviationsOptions, type IBoneLengthSnapshot, type IBonePoseError, type ICameraShakeOffset, type ICameraShakeOptions, type IClipBindingReport, type IClipCoverageReport, type IClipPoseErrorOptions, type IClipPoseErrorReport, type IClipPoseSubject, type IClipTrackBinding, type IClusterTable, type IClusteredBatchBuildOptions, type IClusteredBatchOptions, type IClusteredMeshOptions, type IClusteredPlacement, IComputeDriven$1 as IComputeDriven, type IDaylightOptions, type IEmitParticleRequest, type IFlightAxes, type IFlightControls, type IFlightDeck, type IFlightEnvironment, type IFlightForces, type IFlightModelOptions, type IFlightModifiers, type IFlightQuaternion, type IFlightState, type IFlightVector3, type IFluidBounds, type IFluidCollider, type IFluidFieldOptions, type IFluidFieldSampler, type IFluidFieldVector2, type IFluidParticlesOptions, type IFluidParticlesStats, IFrameBudgetWindow, type IGPUParticles3DOptions, type IGPUParticles3DRuntime, type IGPUParticles3DSpawnBuffers, type IGPUParticles3DSpawnRequest, type IGPUParticles3DStats, IGPUReadbackSample, type IGPUSceneBVHMaterialGroup, type IGPUSceneBVHOptions, IGamePluginHooks, IGamePluginRuntime, type IGroundSnapOptions, type IInstancedBatchBuildOptions, type IInstancedBatchOptions, type IInstancedPlacement, type ILaunchFailure, type ILoadAllOptions, type ILoadAllProgress, type IMatrixWorldReport, type IMeasureThreePoseOptions, type IMergeByMaterialOptions, type IMergePart, type IMergePartsOptions, type INormaliseToMetresOptions, type IPathFollow3DOptions, type IPathFollow3DProjection, type IPathFollow3DSample, type IProbeVolumeBakeProgress, type IProbeVolumeCoefficient, type IProbeVolumeObservation, type IProbeVolumeOptions, type IReplayOptions, type IReplayRecording, type IReplayRecordingSample, type IResolvedAtmosphereParameters, type IRippleFieldFlow, type IRippleFieldOptions, type ISceneShape, type ISceneWarning, type ISkeletalMesh3DOptions, type ISoftBody3DOptions, type ISoftBodyCollision, type ISolarPosition, type ISolarPositionInput, type ISpanProbeTarget, type ISpanSummary, type ISpanWindow, type ISpectralOceanCascade, type ISpectralOceanHeight, type ISpectralOceanOptions, type ISpriteAnimator3DOptions, type ISpriteFrame3D, type IStaticTransformCensus, type IStrideReport, type IThreePoseBounds, type IThreePoseMeasurement, type ITracerPool3DOptions, type ITracerSpawnOptions, type IUnlitFoliageWarning, type IValidationReport, type IVirtualShadowOptions, type IVirtualShadowStats, type IWaterReflectionOptions, type IWaterSurfaceOptions, type IWaveFieldDomainWarp, type IWaveFieldGraphOptions, type IWaveFieldOptions, type IWaveFieldSample, type IWaveFieldWave, InstancedBatch, LUT_RESOLUTIONS, type LaunchFailureKind, type MatrixWorldMode, MatrixWorldPass, NEUTRAL_FLIGHT_MODIFIERS, type NormaliseAxis, OPACITY_IGNORED_MARKER, PROBE_VOLUME_MARKER, PathFollow3D, ProbeVolume, type ProbeVolumeDensity, RENDERLIST_VALIDATE_FLAG, RENDERLIST_VALIDATE_MARKER, type Recording, RenderListValidator, type ReplayPointer, RippleField, SCENE_WARNING_MARKER, SPANS, SPANS_FLAG, SPANS_MARKER, SPAN_COUNT, SPAN_NAMES, STATIC_TRANSFORM_MARKER, SkeletalMesh3D, SoftBody3D, type SpanId, SpanRecorder, SpectralOcean, SpriteAnimator3D, type SpritePlaybackMode, type ThreePoseQuaternion, type ThreePoseVector, TracerPool3D, UNLIT_FOLIAGE_FIX, UNLIT_FOLIAGE_MARKER, VIRTUAL_SHADOW_CASTER_LAYER, VIRTUAL_SHADOW_MARKER, VIRTUAL_SHADOW_MOVER_LAYER, VIRTUAL_SHADOW_WIDE_CASTER_LAYER, VirtualShadowNode, WaterSurface3D, type WaveDirection, WaveField, addInSlices, addSpan, aerodynamicCoefficients, airDensity, aircraftMass, alwaysRender, attachToBone, attitudeAxes, beginSpan, boneContact, boneLengthDeviations, boneLengths, bvhIntersectFirstHit, clipBoneCoverage, clipPoseError, clipTrackBindings, createReplayDriver, debugFlag, describeSceneShape, describeSceneWarning, directionFromSolarPosition, directionalTransmittance, displayPeriodMs, endSpan, exposeDebug, formatSceneWarning, formatSpansWindow, formatUnlitFoliageWarning, formatValidationReport, gearClearance, installSpanProbes, invalidateStatic, isStatic, loadAll, markStatic, measureThreePose, mergeByMaterial, mergeParts, normaliseToMetres, onLaunchFailure, parseReplayRecording, posedBounds, rayStruct, readProbeVolumeObservation, readVirtualShadowMarker, refreshStaticTransforms, renderListValidationRequested, renderTrapAudit, replay, resetStaticTransforms, resolveAtmosphereLutResolutions, resolveAtmosphereParameters, sceneWarning, setAttitude, setSpanRecorder, skeletonBones, softCircleDataTexture, solarPosition, solarPositionAt, spanNow, spanRecorder, spansRequested, staticTransformCensus, unlitFoliageWarning, unmarkStatic, updateAtmosphereParameters, updateClusteredMeshes, validateWorldMatrices, version, zenithTransmittance };