@threenative/core 0.3.4 → 0.3.6

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 (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12437 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +57 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2408 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +574 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +850 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
package/src/index.ts ADDED
@@ -0,0 +1,1536 @@
1
+ /**
2
+ * The version this library reports.
3
+ *
4
+ * It read `0.1.0` while the package published `0.2.0`, and `__tests__/build.spec.ts` asserted the
5
+ * stale literal, so the test held the bug in place rather than catching it. A literal is
6
+ * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
7
+ * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
8
+ */
9
+ export const version = "0.3.6";
10
+
11
+ /**
12
+ * Play a skinned or sprite animation from game code.
13
+ *
14
+ * A locomotion clip's playback rate is matched to the ground the body actually covers, so feet
15
+ * do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and
16
+ * `player.stride` reports the measurement either way. Name the body a game moves as
17
+ * `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and
18
+ * Unreal export, every Mixamo "in place" clip, every stock animal pack — are matched too: their
19
+ * stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.
20
+ * @situation play an animation on a character
21
+ * @situation switch a character between idle and attack clips
22
+ * @situation stop a walking character's feet from sliding or spinning
23
+ * @situation match a walk or run cycle to how fast a character is moving
24
+ * @situation match an in-place walk cycle with no root motion to the body's speed
25
+ * @situation find out what speed an animation clip was authored for
26
+ * @constraint name the body a game moves as strideRoot when the animated rig is a child of it
27
+ * @constraint a one-shot clip always plays at its authored rate; the matched rate re-times loops only
28
+ * @constraint the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so
29
+ * @override strideSync controls whether the matched rate is applied while stride is still measured
30
+ * @example const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
31
+ */
32
+ export { AnimationPlayer } from "./animation.js";
33
+ export type {
34
+ IAnimationPlayerOptions,
35
+ IAnimationPlayOptions,
36
+ IStrideReport,
37
+ } from "./animation.js";
38
+ /**
39
+ * Compose game-authored locomotion and masked actions on one Three.js mixer.
40
+ * @situation synchronize walk/run/strafe clips with different durations
41
+ * @situation reload with the upper body while locomotion continues
42
+ * @situation apply an additive recoil clip with an explicit reference pose
43
+ * @situation route root motion through collision-aware character movement
44
+ * @constraint one base phase, one masked override, at most two additive layers and eight actions
45
+ * @constraint root motion requires a separate rig below the body; advance, CharacterBody3D.move, finish with observed accepted motion after physics, then existing IK
46
+ * @constraint root motion excludes velocity-driven stride sync; unsupported parent transforms throw
47
+ * @constraint source clips remain immutable; dispose at scene exit
48
+ * @example const animation = new AnimationComposer({ root: rig, clips, samples: ["walk", "run"] });
49
+ * animation.setWeights([0.5, 0.5]); animation.update(dt);
50
+ */
51
+ export { AnimationComposer } from "./animation-composition.js";
52
+ export type { IAnimationComposerOptions } from "./animation-composition.js";
53
+ export type { IAnimationLayer, IAnimationMask } from "./animation-layers.js";
54
+ export type {
55
+ IAnimationMotionDelta,
56
+ IAnimationRootMotionOptions,
57
+ } from "./animation-root-motion.js";
58
+ /**
59
+ * Select finite, normalized locomotion weights from sorted thresholds or a fixed triangulation.
60
+ * @situation calculate 1D walk/run blend weights from speed
61
+ * @situation calculate 2D locomotion weights from forward and strafe intent
62
+ * @constraint duplicate samples, collinear triangles and invalid/incomplete triangulations throw at initialization
63
+ * @constraint outside 2D queries project to the nearest boundary subedge; output is borrowed scratch
64
+ * @example const blend = new BlendSpace1D([0, 2]); animation.setWeights(blend.sample(speed));
65
+ */
66
+ export { BlendSpace1D, BlendSpace2D } from "./animation-blend.js";
67
+ /**
68
+ * Shared preparation for an imported rigged character.
69
+ *
70
+ * Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement,
71
+ * validates requested clips against the file and rig at load time, and sets up AnimationPlayer
72
+ * with honest stride-root accounting.
73
+ * @situation put an animated character in the scene
74
+ * @situation my imported character renders deformed
75
+ * @situation instance an imported rigged character
76
+ * @situation validate animation clips on a character rig at load time
77
+ * @situation prepare a skinned character with safe skeleton cloning and stride sync
78
+ * @constraint use strideRoot to name the body moved by game code when the rig is parented under it
79
+ * @constraint requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
80
+ * @override strideSync controls whether locomotion playback rate matches ground covered
81
+ * @override size normalises the instance to real-world metres with skin-aware measurement
82
+ * @example import { SkeletalMesh3D } from "@threenative/core";
83
+ * const character = new SkeletalMesh3D({
84
+ * source: gltf.scene, clips: gltf.animations, requiredClips: ["idle", "walk"],
85
+ * size: { metres: 1.8, axis: "height" }, strideRoot: body,
86
+ * });
87
+ * body.add(character.root); character.play("idle");
88
+ * function update(dt: number): void { character.update(dt); }
89
+ */
90
+ export { SkeletalMesh3D } from "./skeletal-mesh.js";
91
+ export type { ISkeletalMesh3DOptions } from "./skeletal-mesh.js";
92
+ /**
93
+ * Face a game-owned object toward a perspective or orthographic camera.
94
+ * @situation keep a world-space marker or nameplate facing the camera
95
+ * @situation billboard a tree, label, or effect under a rotated parent
96
+ * @constraint call update from the owning scene; no global scene scan is installed
97
+ * @constraint orthographic cameras use their forward direction, and lockAxis restricts world rotation
98
+ * @example const billboard = new Billboard3D(label, { camera });
99
+ * billboard.update();
100
+ */
101
+ export { Billboard3D } from "./billboard.js";
102
+ export type { BillboardLockAxis, IBillboard3DOptions } from "./billboard.js";
103
+ /**
104
+ * Produce a game-authored camera shake offset for a template-owned camera rig.
105
+ * @situation add a hit, explosion, or landing shake to a camera
106
+ * @situation compose a transient camera offset after camera damping
107
+ * @constraint amplitude, rotationAmplitude, frequency, decay, and curve are required game choices
108
+ * @constraint update returns an offset and never writes to a camera
109
+ * @example const shake = new CameraShake({ amplitude, rotationAmplitude, frequency, decay, curve });
110
+ */
111
+ export { CameraShake } from "./camera-shake.js";
112
+ export type { CameraShakeCurve, ICameraShakeOffset, ICameraShakeOptions } from "./camera-shake.js";
113
+ /**
114
+ * Create the portable asset loader a scene also receives as `ctx.assets`.
115
+ * @situation preload models, textures, or audio before a scene enters
116
+ * @situation load assets from a nonstandard base path or a compiled asset manifest
117
+ * @alias different area props
118
+ * @alias first playable screen external assets
119
+ * @constraint reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
120
+ * @example const assets = createAssetLoader({ basePath: "/assets" });
121
+ * const rock = await assets.texture("rock.png");
122
+ */
123
+ export { createAssetLoader } from "./assets.js";
124
+ export { onLaunchFailure } from "./launch-diagnostics.js";
125
+ export { resetAudioCueLedger } from "./audio.js";
126
+ export type { ILaunchFailure, LaunchFailureKind } from "./launch-diagnostics.js";
127
+ export type { IAssetLoader, IAssetLoaderOptions, ITextureOptions } from "./assets.js";
128
+ export type {
129
+ IAudioBusOptions,
130
+ IAudioCompressorOptions,
131
+ IAudioPlayOptions,
132
+ } from "./audio.js";
133
+ /**
134
+ * Route effects through a named audio bus.
135
+ * @situation play a sound effect with a volume bus
136
+ * @situation mute or adjust a category of game audio
137
+ * @situation keep a gunshot audible at 20 metres by tuning positional falloff
138
+ * @situation hold a loud mix below clipping with a compressor on the bus
139
+ * @situation play cannon, wave, and ship sound effects
140
+ * @constraint create buses before playing clips and dispose them with the game
141
+ * @constraint refDistance and rolloffFactor tune positional falloff and apply to playAt only
142
+ * @constraint compressor takes threshold, knee, ratio, attack and release from the game and takes effect on the bus sum
143
+ * @supersedes new Audio(
144
+ * @example const effects = new AudioBus({ camera });
145
+ */
146
+ export { AudioBus } from "./audio.js";
147
+ /**
148
+ * Manage a camera or screen-facing canvas layer.
149
+ * @situation place a HUD layer above the Three.js scene
150
+ * @situation attach a canvas layer to a camera
151
+ * @example const hud = new CanvasLayer(ctx.viewport);
152
+ */
153
+ export { CanvasLayer } from "./canvas-layer.js";
154
+ export type {
155
+ IThreeNativeAudioConfig,
156
+ IThreeNativeAudioLoop,
157
+ IThreeNativeAudioOverride,
158
+ IThreeNativeAudioSpectrum,
159
+ IThreeNativeBootSplash,
160
+ IThreeNativeConfig,
161
+ IThreeNativeIconVariants,
162
+ IThreeNativeLodConfig,
163
+ IThreeNativeLodGenerationConfig,
164
+ IThreeNativeLodOverride,
165
+ IThreeNativeLodRuntimeConfig,
166
+ IThreeNativeTexturesConfig,
167
+ ThreeNativeBackgroundMode,
168
+ ThreeNativeLodMinTrianglesScope,
169
+ ThreeNativeLodPreset,
170
+ ThreeNativeOrientation,
171
+ ThreeNativeUiRenderer,
172
+ } from "./config.js";
173
+ /**
174
+ * Create a deterministic random source for portable gameplay.
175
+ * @situation get a seeded deterministic random number generator — the same mulberry32 a game would hand-roll
176
+ * @situation seed enemy patrol choices
177
+ * @situation reproduce the same procedural level in a playtest
178
+ * @constraint use the returned source instead of Math.random for replayable behavior
179
+ * @supersedes Math.random(
180
+ * @example const random = createRandom(42);
181
+ */
182
+ export { createRandom } from "./random.js";
183
+ export type { IRandom } from "./random.js";
184
+ /**
185
+ * Define the portable game entry shared by web and native.
186
+ * @situation start a ThreeNative game from src/game.ts
187
+ * @situation register physics and gameplay plugins
188
+ * @situation let the player zoom the camera with a wheel, pinch, or gamepad axis
189
+ * @situation frame a camera behind the player
190
+ * @alias nearest target crosshair spawns
191
+ * @alias third-person camera
192
+ * @alias restart run without page reload
193
+ * @alias field of view while aiming
194
+ * @constraint keep DOM and React mounting in src/main.ts
195
+ * @constraint bind scroll or pinch and read the intent with ctx.input.axis(name); do not add a window wheel listener
196
+ * @constraint scroll: true uses the DOM wheel sign on browser and native: negative deltaY toward the user is positive intent
197
+ * @example const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: "Play" });
198
+ */
199
+ export { defineGame } from "./game.js";
200
+ export {
201
+ ATMOSPHERE_LUT_RESOLUTIONS,
202
+ Atmosphere,
203
+ AtmosphereLuts,
204
+ LUT_RESOLUTIONS,
205
+ directionFromSolarPosition,
206
+ directionalTransmittance,
207
+ resolveAtmosphereLutResolutions,
208
+ resolveAtmosphereParameters,
209
+ solarPosition,
210
+ solarPositionAt,
211
+ updateAtmosphereParameters,
212
+ zenithTransmittance,
213
+ } from "./atmosphere/index.js";
214
+ export type {
215
+ AtmosphereDirection,
216
+ AtmosphereRgb,
217
+ IAtmosphereLutResolution,
218
+ IAtmosphereLutResolutions,
219
+ IAtmosphereOptions,
220
+ IAtmosphereParameterPatch,
221
+ IAtmosphereParameters,
222
+ IAtmosphereScenePass,
223
+ IResolvedAtmosphereParameters,
224
+ ISolarPosition,
225
+ ISolarPositionInput,
226
+ } from "./atmosphere/index.js";
227
+ /**
228
+ * Register game-owned IComputeDriven objects with the shared compute lifetime.
229
+ * @situation use IComputeDriven for a cloth, fluid, boid, or other GPU simulation
230
+ * @situation run a cloth or fluid simulation with ordered GPU passes
231
+ * @situation keep IComputeDriven kernels warm before the first visible frame
232
+ * @constraint add the object through ctx.add so it attaches, dispatches, and releases with its scene
233
+ * @example const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);
234
+ */
235
+ export { ComputeDrivenRegistry } from "./compute-driven.js";
236
+ export type { IComputeDriven } from "./compute-driven.js";
237
+ export { SoftBody3D } from "./softbody.js";
238
+ export type { ISoftBody3DOptions, ISoftBodyCollision } from "./softbody.js";
239
+ /**
240
+ * Pack a selected static scene into TSL storage nodes for an upstream BVH ray query.
241
+ * @situation trace thousands of scene rays inside a TSL kernel
242
+ * @situation build a contact-occlusion or visibility query over loaded meshes
243
+ * @constraint call rebuild() after a scene transform or geometry change; the snapshot is static by default
244
+ * @constraint rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray
245
+ * @example const bvh = ctx.add(new GPUSceneBVH(ctx.scene, { include: (object) => object.userData.traceable === true }));
246
+ */
247
+ export { GPUSceneBVH, bvhIntersectFirstHit, rayStruct } from "./gpu-scene-bvh.js";
248
+ export type {
249
+ GPUSceneBVHTraceFunction,
250
+ IGPUSceneBVHMaterialGroup,
251
+ IGPUSceneBVHOptions,
252
+ } from "./gpu-scene-bvh.js";
253
+ /**
254
+ * Collapse many copies of one game-authored shape into a single draw, without counting them first.
255
+ *
256
+ * `new InstancedMesh(geometry, material, count)` needs the count before anything is placed, so a
257
+ * procedural builder ends up walking its layout twice or over-allocating. Place as you go and
258
+ * `build()` once; the shape, the surface and every transform stay the game's, and the built mesh
259
+ * is returned so instances can still be animated by the index `place` and `span` hand back.
260
+ * @situation draw hundreds of repeated props without hundreds of draw calls
261
+ * @situation draw thousands of identical instanced blocks or obstacles in one mesh
262
+ * @situation automatically select instanced prop detail from projected screen error using baked AutoLOD chains
263
+ * @situation place repeated props when the count is not known until the layout has been walked
264
+ * @situation build a chain, railing, cable, or tie rod out of point-to-point segments
265
+ * @alias landmarks points of interest
266
+ * @alias obstacles collectibles increasing pace
267
+ * @constraint geometry and material are required and come from the game; the batch chooses neither
268
+ * @constraint span stretches along +Y, so its geometry must be unit-height and centred on the origin
269
+ * @constraint placing after build() throws, and build() returns undefined when nothing was placed
270
+ * @constraint baked AutoLOD chains survive geometry clone/transform preparation and partition instances automatically into spatially bounded draws in the engine frame loop at 4 px projected error; public instance slots remain stable
271
+ * @constraint unavailable authored levels report TN_INSTANCED_LOD_FAILED once naming the batch; a million-triangle batch with no chain reports TN_INSTANCED_LOD_UNAVAILABLE
272
+ * @override autoLod: false leaves selection to the game; autoLod.maxPixelError and hysteresis override the measured-camera budget; lods supplies authored distance/geometry levels and wins over the baked chain
273
+ * @override castShadow and receiveShadow pass through to the built mesh and default to Three.js's own false
274
+ * @example const curbs = new InstancedBatch({ geometry: new BoxGeometry(1, 1, 1), material });
275
+ * curbs.place({ position: [x, 0.08, z], rotation: [0, angle, 0], scale: [length, 0.18, 0.42] });
276
+ * curbs.build({ castShadow: true, name: "curbs", parent: ctx.scene });
277
+ */
278
+ export { InstancedBatch } from "./instanced-batch.js";
279
+ export type {
280
+ IInstancedBatchBuildOptions,
281
+ IInstancedBatchOptions,
282
+ IInstancedPlacement,
283
+ } from "./instanced-batch.js";
284
+ /**
285
+ * Merge pieces a game authored out of primitives into one buffer, keeping each piece's own look.
286
+ *
287
+ * `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that
288
+ * never move relative to each other — a building, a ship, a character built from boxes, or the
289
+ * static parts of an imported glTF model. Two things go wrong every time and neither is about how
290
+ * any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing,
291
+ * and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other
292
+ * primitive is indexed, so the merge fails at the first piece and the scene never loads. And a
293
+ * merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a
294
+ * flat `color` attribute written before the merge. Both are mechanical. By default every part is
295
+ * stripped to position and the normals are recomputed from the merged buffer; pass `preserve` to
296
+ * keep authored normals and texture UVs while baking each part's object transform. Geometry,
297
+ * placement, colour and the surface it draws with all stay the game's.
298
+ *
299
+ * @situation bake a building, ship or character authored out of primitives into one draw call
300
+ * @situation merge multiple static Three.js meshes into one mesh per material
301
+ * @situation consolidate the static parts of an imported glTF model into one buffer
302
+ * @situation preserve texture UV coordinates and authored normals while baking object transforms
303
+ * @situation merge many small geometries and keep each piece's own colour
304
+ * @situation stop mergeGeometries from silently returning null on an extruded shape
305
+ * @constraint every part is de-indexed; without preserve it is stripped to position and normals are recomputed from the merged buffer
306
+ * @constraint preserve keeps the listed channels, transforming position and normal by the part's placement matrix while UV values are retained unchanged
307
+ * @constraint a part that does not carry a listed preserve channel throws naming the label, the part and the channel
308
+ * @constraint either every part names a color or none does, and a mix throws
309
+ * @constraint an empty part list throws, and a merge three.js refuses throws naming the label
310
+ * @override color is per part and optional; without it no colour attribute is written and the surface alone decides
311
+ * @override preserve is optional and empty by default: position-only merge with recomputed normals, exactly as before
312
+ * @example const wall = new Mesh(mergeParts(pieces, { label: "gatehouse" }), stone);
313
+ * // pieces are meshes, or { geometry, matrix, color } when the colour is per piece:
314
+ * const banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: "banner" });
315
+ * // keep a model's texture UVs and authored normals while baking its transforms:
316
+ * const hull = mergeParts(hullParts, { label: "hull", preserve: ["uv", "normal"] });
317
+ */
318
+ export { mergeParts } from "./merge-parts.js";
319
+ export type { IMergePart, IMergePartsOptions } from "./merge-parts.js";
320
+ /**
321
+ * Bake a hierarchy's static meshes into one mesh per material, with their transforms baked in.
322
+ *
323
+ * @situation collapse a building or ship of dozens of boxes into one draw call per material
324
+ * @situation consolidate the static parts of a group before adding it to the scene
325
+ * @constraint the material is the game's own instance and the split follows the materials the game
326
+ * already made; nothing here decides appearance
327
+ * @constraint the meshes come back in root's local space and unparented, with the originals still in the
328
+ * tree: add them to root and remove the sources yourself, or both draw
329
+ * @constraint a skinned or instanced mesh, and a mesh with several materials, is left out — its
330
+ * vertices are not its own to bake
331
+ * @constraint a group where only some meshes carry uv throws naming the label rather than losing the
332
+ * texture mapping; a missing normal is recomputed
333
+ * @override skip leaves one mesh out of its group and out of the result
334
+ * @example const [hull, deck] = mergeByMaterial(ship, { label: "ship" });
335
+ * // a piece that must keep moving at run time:
336
+ * const [steady] = mergeByMaterial(ship, { label: "ship", skip: (mesh) => mesh.name === "radar" });
337
+ */
338
+ export { mergeByMaterial } from "./merge-parts.js";
339
+ export type { IMergeByMaterialOptions } from "./merge-parts.js";
340
+ /**
341
+ * Read a debug switch from the URL, or from `TN_DEBUG_*` in the environment on a native launch.
342
+ * @situation read a debug toggle from the URL or an environment variable
343
+ * @constraint a name in camelCase becomes UPPER_SNAKE: `debugFlag("freeCam")` reads `?freeCam` or `TN_DEBUG_FREE_CAM`
344
+ * @constraint `0` and `false` are off, so a saved URL cannot turn a switch back on
345
+ * @example import { debugFlag } from "@threenative/core";
346
+ * if (debugFlag("freeCam")) camera.flyMode = true;
347
+ */
348
+ export { debugFlag } from "./debug.js";
349
+ /**
350
+ * Publish one game object under `__THREENATIVE__.debug` for a capture script or the console.
351
+ * @situation expose a game object to a capture script or the console in dev builds
352
+ * @constraint development builds only; a production build publishes nothing
353
+ * @example import { exposeDebug } from "@threenative/core";
354
+ * exposeDebug("player", player);
355
+ * // then from the console: __THREENATIVE__.debug.player
356
+ */
357
+ export { exposeDebug } from "./debug.js";
358
+ /**
359
+ * Draw a model too detailed for the screen to resolve, without submitting the part it cannot.
360
+ *
361
+ * **This is on, and a game does not call it.** Any primitive of 65,536 triangles or more bakes to a
362
+ * cluster DAG in the asset pipeline, the loader returns a `ClusteredMesh` for it, and the engine
363
+ * takes the cut every frame before it renders. Each frame the mesh submits one draw holding only
364
+ * the clusters whose error projects to fewer than `errorPixels` screen pixels; a mesh nothing has
365
+ * cut yet draws in full, so the worst case is an ordinary `Mesh`. Geometry, surface and every
366
+ * appearance parameter stay the game's.
367
+ *
368
+ * @situation draw a model too detailed for the screen to resolve
369
+ * @situation import a scanned or sculpted mesh of millions of triangles and still hold the frame
370
+ * @situation stop a dense rock face or terrain body from costing its full triangle count up close
371
+ * @constraint the bake happens in the asset pipeline, never at run time — there is no runtime flag
372
+ * @constraint the payload costs about 3-4x a baked primitive's bytes; `assets.models.virtual: "none"` opts out and `minSourceTriangles` moves the 65,536 line
373
+ * @constraint needs a perspective camera; a screen-space error has no meaning without one
374
+ * @constraint one shadow cut is chosen at load and does not follow a shadow camera
375
+ * @override errorPixels sets the screen-space error budget, default 1 pixel
376
+ * @override recutDistance sets how far the camera moves before the cut is retaken, default a thousandth of the mesh's radius
377
+ * @example
378
+ * // Nothing to call: the loader returns one of these and the engine cuts it every frame.
379
+ * const face = await ctx.assets.model("quarry-face.glb");
380
+ * ctx.scene.add(face.scene);
381
+ */
382
+ export { ClusteredMesh } from "./clustered-mesh.js";
383
+ /**
384
+ * Draw many copies of one over-detailed body, each at the detail its own distance earns.
385
+ *
386
+ * `InstancedBatch` collapses repeated props into one draw and gives every copy the same triangles.
387
+ * This gives a copy two hundred metres away a coarser cut than one twelve metres away, and still
388
+ * submits one draw per distance group rather than one per copy — which is what makes four hundred
389
+ * scanned boulders affordable. The shape, the surface and every transform stay the game's.
390
+ *
391
+ * @situation draw hundreds of copies of a scanned or sculpted body without hundreds of draw calls
392
+ * @situation stop distant copies of a dense prop from costing their full triangle count
393
+ * @constraint the body's geometry must carry a cluster table from `assets.models.virtual`
394
+ * @constraint every copy is placed before build(); place() after build() throws
395
+ * @override distanceRatio sets how wide one distance group is, default 1.25
396
+ * @override errorPixels sets the screen-space error budget, default 1 pixel
397
+ * @example
398
+ * const boulders = new ClusteredBatch({ geometry, material, table });
399
+ * boulders.place({ position: [x, y, z], rotation: [0, angle, 0] });
400
+ * boulders.build({ name: "boulders", parent: ctx.scene });
401
+ * // in the scene's update, before the render:
402
+ * boulders.update(ctx.camera, ctx.renderer.domElement.height);
403
+ */
404
+ export { ClusteredBatch } from "./clustered-batch.js";
405
+ export type {
406
+ IClusteredBatchBuildOptions,
407
+ IClusteredBatchOptions,
408
+ IClusteredPlacement,
409
+ } from "./clustered-batch.js";
410
+ /**
411
+ * Take every clustered mesh under a root through this frame's cut, before the render.
412
+ *
413
+ * The engine already does this for the scene it renders; reach for it only to cut a subtree the
414
+ * engine does not render, such as one staged for a camera of your own.
415
+ *
416
+ * @situation cut a virtual-geometry subtree the engine does not render itself
417
+ * @example updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);
418
+ */
419
+ export { updateClusteredMeshes } from "./clustered-mesh.js";
420
+ // `VirtualGeometryPlugin`, `selectClusterCut` and `pixelsPerUnit` are deliberately not exported: the
421
+ // loader registers the plugin itself, and the other two are the rule's internals — a game that had
422
+ // to call them would be re-implementing the cut rather than using it.
423
+ export type { IClusteredMeshOptions, IClusterTable } from "./clustered-mesh.js";
424
+ /**
425
+ * Draw a model at the detail its projected geometric error earns, from a chain the asset cook baked.
426
+ *
427
+ * **This is engine-owned, and a game does not call it.** `assets.lod: {}` opts in — the default-on
428
+ * front door opens after qualification — the `model` pass bakes `TN_discrete_lod` into eligible
429
+ * models, the loader registers the reader, and the engine runs the selection every frame before it
430
+ * renders. Each frame the mesh picks the cheapest baked level whose measured error projects to fewer
431
+ * than the resolved pixel budget, taking the camera's own projection, zoom, viewport and a
432
+ * conservative nearest depth into account. Refinement is immediate; coarsening waits for the
433
+ * resolved hysteresis. A mesh with no baked chain draws its full geometry.
434
+ *
435
+ * @situation draw a vehicle or hull built from many small meshes at distance without its full triangles
436
+ * @situation stop a distant model from costing its authored mesh count and triangle count
437
+ * @situation one source model, right detail by default, no hand-authored LOD files
438
+ * @constraint the chain is baked by the asset cook; there is no runtime generation and no runtime flag
439
+ * @constraint `assets.lod: false` opts out globally and `assets.lod.overrides` per asset, with no runtime controller installed
440
+ * @constraint only static indexed triangles are eligible; skinned, morphed, alpha-blended or authored-LOD meshes keep full detail
441
+ * @constraint the real gate is measured benefit: a level must save at least `minSaving` (20% default) of its predecessor, and a mesh that cannot is skipped, not forced
442
+ * @override `assets.lod.generation.maxLevels`, `.minTriangles`, `.minTrianglesScope`, `.minSaving` and `.errorTargets` move the bake's ceiling, pre-filter, its scope, its saving rule and its error ladder; `assets.lod.runtime.maxPixelError` and `.hysteresis` move the runtime budget and coarsen band; all by project, preset or asset
443
+ * @example
444
+ * // Nothing to call: the loader returns a mesh with the chain and the engine selects every frame.
445
+ * const hull = await ctx.assets.model("hull.glb");
446
+ * ctx.scene.add(hull.scene);
447
+ */
448
+ export {
449
+ DISCRETE_LOD_DEFAULT_ERROR_PIXELS,
450
+ DISCRETE_LOD_DEFAULT_HYSTERESIS,
451
+ updateModelLods,
452
+ } from "./model-lod.js";
453
+ /**
454
+ * The full-detail geometry of a mesh the loader gave an automatic LOD chain.
455
+ *
456
+ * Selection swaps `mesh.geometry`, so a ray test or a collision body built from the current geometry
457
+ * would change with the camera. Framework picking and gameplay collide against this instead: the
458
+ * authored LOD0, which never changes as the camera moves.
459
+ *
460
+ * @situation collide or ray-test the authored geometry of a mesh whose render detail changes with distance
461
+ * @example const geometry = baseGeometryOf(mesh);
462
+ */
463
+ export { baseGeometryOf } from "./model-lod.js";
464
+ /**
465
+ * The screen pixels one world unit covers at `depth` for this camera and viewport.
466
+ *
467
+ * Perspective divides the projected scale by the depth; orthographic has no depth term and uses the
468
+ * frustum height instead. This is the number a level of detail is chosen against: multiply a
469
+ * level's world-space error by it and you have the on-screen error a player can see, which is the
470
+ * comparison `updateModelLods` makes from the baked chain.
471
+ *
472
+ * @situation pick a level of detail from an object's projected size in pixels on screen
473
+ * @situation know how many screen pixels a world-space error covers at a given distance
474
+ * @constraint a non-positive viewport height, a non-positive frustum height or an unprojectable camera throws
475
+ * @constraint a non-positive depth has no projected scale and returns Infinity
476
+ * @example const pixels = lodPixelScale(camera, canvas.clientHeight, mesh.position.distanceTo(camera.position));
477
+ */
478
+ export { lodPixelScale } from "./model-lod.js";
479
+ /**
480
+ * Keep an object drawn even when the render camera cannot resolve it.
481
+ *
482
+ * The engine's projected-size gate is on by default: an object whose world bounding sphere
483
+ * projects to fewer than 0.5 raster pixels in the camera about to render it is not submitted, per
484
+ * camera. Mark the player's own cockpit, a nameplate, a quest marker, or anything a game never
485
+ * wants to pop out of the frame. `alwaysRender(object, false)` removes the marker. Camera-attached
486
+ * objects and shadow casters are already kept, and the number of marked objects is reported beside
487
+ * the cull in the `TN_PROJECTION` window rather than hidden. The threshold itself is
488
+ * `renderer.minimumProjectedPixels` — a larger number cuts more aggressively, `false` leaves
489
+ * every object drawn while still measuring.
490
+ *
491
+ * @situation keep a small object drawn when the engine would skip it as too far to resolve
492
+ * @situation stop my cockpit, marker or player model popping out at distance
493
+ * @situation a tiny object disappeared at range and I need it always visible
494
+ * @situation widen or narrow the projected-size cull with a named threshold
495
+ * @constraint the marker is per object and is reported as `exemptMarked` in the projection window
496
+ * @constraint `renderer.minimumProjectedPixels: false` leaves the scene drawn and keeps the measurement on
497
+ * @override renderer.minimumProjectedPixels sets the projected-pixel threshold, default 0.5
498
+ * @example import { alwaysRender } from "@threenative/core";
499
+ * alwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn
500
+ */
501
+ export { alwaysRender } from "./render-camera-cull.js";
502
+ /**
503
+ * Walk the scene graph's world matrices each frame without recursing into a hidden subtree.
504
+ *
505
+ * On by default as `renderer.matrixWorld: "visible"`. three's `updateMatrixWorld` recurses into
506
+ * every child whatever its `visible` flag, so a hidden LOD body, a merged stand-in and a parked
507
+ * model cost a world-matrix multiply each while nothing under them can draw. This pass mirrors
508
+ * three exactly for every visible node and defers a hidden node's subtree until the frame it shows
509
+ * again. A class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a
510
+ * hidden node that holds bones is walked, so no skeleton or view matrix goes stale.
511
+ *
512
+ * @situation update the world matrices of the visible objects each frame instead of the whole scene
513
+ * @situation the per-frame world matrix walk is hot in a profile
514
+ * @situation stop multiplying matrices for hidden models, LOD levels and merged stand-ins
515
+ * @situation a game needs every node walked, exactly as three's own updateMatrixWorld does
516
+ * @constraint a game that reads a hidden object's matrixWorld directly must use getWorldPosition or updateWorldMatrix(true, false) first
517
+ * @constraint `renderer.matrixWorld: "all"` visits every node; `TN_PROJECTION` reports the visited count either way
518
+ * @override renderer.matrixWorld: "all" runs three's full walk instead of the visible-only default
519
+ * @example import { MatrixWorldPass } from "@threenative/core";
520
+ * const pass = new MatrixWorldPass(); // renderer.matrixWorld defaults to "visible"
521
+ */
522
+ export { MatrixWorldPass } from "./matrix-world.js";
523
+ export type { IMatrixWorldReport, MatrixWorldMode } from "./matrix-world.js";
524
+ /**
525
+ * Read where the frame's milliseconds went, per presented frame, on any platform; each
526
+ * `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and
527
+ * triangles each render pass submitted.
528
+ * @situation show an on-screen frame time meter with p50, p95 and p99 percentiles
529
+ * @situation find out why a game runs slowly on a phone
530
+ * @situation attribute a frame to present wait, simulation, three.js render, or overlay
531
+ * @situation tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp
532
+ * @situation split a frame's draw calls and triangles per render pass (main, shadow, reflection)
533
+ * @situation tell a shadow or reflection pass's cost from the main colour pass
534
+ * @situation retain every asynchronous GPU render frame for a complete paired benchmark
535
+ * @constraint on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement
536
+ * @constraint per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main
537
+ * @constraint GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero
538
+ * @constraint `ctx.renderer.observeGpuFrames({ maxFrames, maxQueries })` is opt-in, bounded and fail-closed; `take()` delivers immutable complete render-query groups once, while `status()` reports pending/undrained/queued membership and losses
539
+ * @constraint observation preserves ordinary sampling; a complete benchmark explicitly requests `renderer.gpuTimestampFrameInterval: 1` and joins Three query IDs to actual world renders, including separate overlay IDs
540
+ * @constraint `stop()` fences allocated frames and drains existing resolver work; `dispose()` invalidates late completions, and a failed observation must be disposed before replacement
541
+ * @example defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });
542
+ */
543
+ export {
544
+ FRAME_BUDGET_MARKER,
545
+ FRAME_BUDGET_PHASES,
546
+ FRAME_HITCH_MARKER,
547
+ FrameBudget,
548
+ } from "./frame-budget.js";
549
+ export type {
550
+ FrameBudgetPhase,
551
+ IFrameBudgetOptions,
552
+ IFrameBudgetSimulation,
553
+ IFrameBudgetPassSummary,
554
+ IFrameBudgetSummary,
555
+ IFrameBudgetWindow,
556
+ IFramePhaseSample,
557
+ } from "./frame-budget.js";
558
+ export type { FramePassKind, IRenderPassSample, MainDrawSource } from "./render-pass-budget.js";
559
+ /**
560
+ * Read what frame rate a game gets when its config does not say, and why.
561
+ *
562
+ * `display.maxFps` follows the display — capped at 120 on desktop and web, 60 on mobile — rather
563
+ * than the 60 every template used to ship, and an explicit number still wins with `0` still
564
+ * uncapping. The engine calls this itself; a game calls it when it needs the same number for its
565
+ * own frame-rate-dependent work, and `TN_FRAME_BUDGET` reports the resolved target and its source
566
+ * on every window.
567
+ * @situation my game does frame-rate-dependent work and must not hardcode 60
568
+ * @constraint pass the measured display rate when you have one; without it the answer is the 60 fallback and says so
569
+ * @example resolveTargetFps(config, getPlatform()).targetFps;
570
+ */
571
+ export {
572
+ DEFAULT_TARGET_FPS,
573
+ MAX_TARGET_FPS,
574
+ resolveTargetFps,
575
+ snapRefreshRate,
576
+ } from "./target-fps.js";
577
+ export type { ITargetFps, TargetFpsSource } from "./target-fps.js";
578
+ /**
579
+ * Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks.
580
+ * Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as
581
+ * a residual instead of being filed under "other"; a child that outlives its parent reports a
582
+ * negative residual rather than a clamped zero.
583
+ * @situation find out what inside the render phase is actually costing the frame
584
+ * @situation tell a shadow pass's traversal from the main pass's, with the residual computed
585
+ * @situation price an optimisation against a measured part of the phase rather than the whole of it
586
+ * @constraint off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return
587
+ * @constraint the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames
588
+ * @constraint measurement only: no span changes what is drawn, in what order, or with which renderer
589
+ * @example if (spansRequested()) setSpanRecorder(new SpanRecorder());
590
+ */
591
+ export {
592
+ SPANS,
593
+ SPANS_FLAG,
594
+ SPANS_MARKER,
595
+ SPAN_COUNT,
596
+ SPAN_NAMES,
597
+ SpanRecorder,
598
+ addSpan,
599
+ beginSpan,
600
+ endSpan,
601
+ formatSpansWindow,
602
+ setSpanRecorder,
603
+ spanNow,
604
+ spanRecorder,
605
+ spansRequested,
606
+ } from "./profiling/Spans.js";
607
+ export type { ISpanSummary, ISpanWindow, SpanId } from "./profiling/Spans.js";
608
+ /**
609
+ * Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's
610
+ * `sort`, the per-draw submission, and the scene-graph walk. Installed for you when
611
+ * `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.
612
+ * @situation measure which part of three's render path costs the frame
613
+ * @situation attach the span tree to a renderer a test or a tool constructed itself
614
+ * @constraint returns an uninstall that restores every wrapper, asserted by test
615
+ * @constraint a renderer whose internals have moved loses that span rather than throwing, and it is absent from the report rather than zero
616
+ * @constraint only the outermost `_projectObject` opens a span, because three's recurses per child
617
+ * @example const uninstall = installSpanProbes(renderer.raw, scene);
618
+ */
619
+ export { installSpanProbes } from "./profiling/span-probes.js";
620
+ export type { ISpanProbeTarget } from "./profiling/span-probes.js";
621
+ /**
622
+ * Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless
623
+ * `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing
624
+ * count and a millisecond split describe the same frames.
625
+ * @situation decide whether a CPU-bound frame is paying for the V8-to-host boundary
626
+ * @situation measure how many bytes a frame writes into GPU buffers, and how many commands it issues
627
+ * @constraint counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in
628
+ * @constraint `gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included
629
+ * @constraint `jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it
630
+ * @example const counters = FrameCounters.install(counterDeviceOf(renderer.raw));
631
+ */
632
+ export { FrameCounters, counterDeviceOf } from "./profiling/FrameCounters.js";
633
+ export type { ICounterDevice, IFrameCounters } from "./profiling/FrameCounters.js";
634
+ /**
635
+ * Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its
636
+ * JS render phase is longer than the display's own period is a scene-shape problem, and the engine
637
+ * already has the shape. On by default, printed at most once per reported window as
638
+ * `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
639
+ * @situation find out whether a slow frame is the scene's shape or the device
640
+ * @situation tell an authoring agent what to reduce before it promises a merge
641
+ * @constraint the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant
642
+ * @constraint no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence
643
+ * @constraint the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking
644
+ * @example defineGame({ display: { maxFps: 60 }, scenes: { Play } });
645
+ */
646
+ export {
647
+ SCENE_WARNING_MARKER,
648
+ describeSceneShape,
649
+ describeSceneWarning,
650
+ displayPeriodMs,
651
+ formatSceneWarning,
652
+ sceneWarning,
653
+ } from "./profiling/scene-warning.js";
654
+ export type { ISceneShape, ISceneWarning } from "./profiling/scene-warning.js";
655
+ /**
656
+ * Tell the agent that built the scene that its imported foliage is drawing with no image-based light:
657
+ * an alpha-cutout `MeshStandardMaterial` (or its Node twin) with `scene.environment` unset and no
658
+ * `envMap` of its own gets a hemisphere fill and one flat dark value, which is cardboard. Printed
659
+ * once per scene entry as `TN_UNLIT_FOLIAGE`, after `enter()`, with the fix in the same line.
660
+ * @situation catch the "why does my forest look like cardboard" question before a human plays it
661
+ * @situation audit a scene a game built from imported GLB foliage
662
+ * @constraint derived from the scene graph, not from a constant: cutout PBR with no environment in the scene and none on the material
663
+ * @constraint it changes nothing and never throws — the environment is appearance, so setting it stays the game's decision
664
+ * @override `material.userData.tnUnlitOk = true` on a material a game deliberately renders unlit (the same `userData.tn*` naming the alpha and impostor conventions use)
665
+ * @example defineGame({ scenes: { Forest } }); // one TN_UNLIT_FOLIAGE line when the forest has no sky
666
+ */
667
+ export {
668
+ UNLIT_FOLIAGE_FIX,
669
+ UNLIT_FOLIAGE_MARKER,
670
+ formatUnlitFoliageWarning,
671
+ unlitFoliageWarning,
672
+ } from "./profiling/unlit-foliage-warning.js";
673
+ export type { IUnlitFoliageWarning } from "./profiling/unlit-foliage-warning.js";
674
+ /**
675
+ * Catch scene state that silently loses environment fill or ignores authored opacity.
676
+ * After `enter()` the game first applies the opacity convention: a drawn material with
677
+ * `opacity < 1` turns transparent and one `TN_OPACITY_TRANSPARENT` console warning names it
678
+ * (override: `alphaHash: true`, or `opacity: 1`). It then prints `TN_ENVIRONMENT_TOO_SMALL`
679
+ * as a console error with the fix, so playtest `noConsoleErrors` rejects it.
680
+ * @situation audit an equirectangular sky too narrow for three's WebGPU PMREM
681
+ * @situation find visible opaque materials whose authored opacity is ignored
682
+ * @constraint structural scene reads only, one visible-tree walk per entry, at most five material examples
683
+ * @constraint the audit itself changes no scene state; the game loop's opacity convention is the only writer
684
+ * @example renderTrapAudit(ctx.scene); // marker lines with the fixes, or an empty array
685
+ */
686
+ export {
687
+ ENVIRONMENT_TOO_SMALL_MARKER,
688
+ OPACITY_IGNORED_MARKER,
689
+ renderTrapAudit,
690
+ } from "./profiling/render-trap-audit.js";
691
+ /**
692
+ * Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the
693
+ * subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and
694
+ * `invalidateStatic(object)` announces a write deeper inside one.
695
+ * @situation cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves
696
+ * @situation keep a frozen subtree correct when the game does move it after all
697
+ * @constraint staticness is authored, never guessed; no heuristic watches gameplay and decides for you
698
+ * @constraint it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless
699
+ * @constraint a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
700
+ * @example invalidateStatic(drawbridge);
701
+ */
702
+ export {
703
+ STATIC_TRANSFORM_MARKER,
704
+ invalidateStatic,
705
+ isStatic,
706
+ refreshStaticTransforms,
707
+ resetStaticTransforms,
708
+ staticTransformCensus,
709
+ unmarkStatic,
710
+ } from "./static-transform.js";
711
+ /**
712
+ * Freeze a subtree nobody moves: `markStatic(root)` composes its transforms once and stops the
713
+ * per-frame recompose.
714
+ *
715
+ * It is the call a game makes on scenery, terrain, buildings and props. The engine re-arms a root
716
+ * whose own transform the game changes; a write deeper inside a frozen subtree is announced with
717
+ * `invalidateStatic(object)`.
718
+ *
719
+ * @situation freeze a static mesh or subtree so its matrices are not recomputed every frame
720
+ * @situation stop the engine recomposing the transforms of props, terrain and buildings each frame
721
+ * @constraint staticness is authored, never guessed; no heuristic watches gameplay and decides for you
722
+ * @constraint a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened
723
+ * @example markStatic(island); invalidateStatic(drawbridge);
724
+ */
725
+ export { markStatic } from "./static-transform.js";
726
+ export type { IStaticTransformCensus } from "./static-transform.js";
727
+ /**
728
+ * Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes
729
+ * every world matrix the long way, every frame, and throws on the first element that disagrees
730
+ * with what the frame is about to draw.
731
+ * @situation prove a static freeze did not leave a stale transform on screen
732
+ * @situation gate a scene in CI against silent transform divergence
733
+ * @constraint off by default and expensive by construction — it does the work it is checking, twice
734
+ * @constraint it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads
735
+ * @constraint it proves the frames it ran on and nothing else
736
+ * @example if (renderListValidationRequested()) console.log(formatValidationReport(report));
737
+ */
738
+ export {
739
+ RENDERLIST_VALIDATE_FLAG,
740
+ RENDERLIST_VALIDATE_MARKER,
741
+ RenderListValidator,
742
+ formatValidationReport,
743
+ renderListValidationRequested,
744
+ validateWorldMatrices,
745
+ } from "./profiling/render-list-validate.js";
746
+ export type { IValidationReport } from "./profiling/render-list-validate.js";
747
+ export {
748
+ GEOMETRY_CAPTURE_DEFAULT_LIMIT,
749
+ GEOMETRY_CAPTURE_MAX_LIMIT,
750
+ GEOMETRY_CAPTURE_SORTS,
751
+ GEOMETRY_CAPTURE_TIMEOUT_MS,
752
+ GEOMETRY_CAPTURE_WALK_CAP,
753
+ GEOMETRY_ASSET_KEY,
754
+ } from "./geometry-capture.js";
755
+ export type {
756
+ GeometryCaptureSort,
757
+ IGeometryCaptureAsset,
758
+ IGeometryCaptureMesh,
759
+ IGeometryCapturePass,
760
+ IGeometryCaptureReport,
761
+ IGeometryCaptureRequest,
762
+ IGeometryCaptureRow,
763
+ } from "./geometry-capture.js";
764
+ /**
765
+ * Register work that reads a body or camera after physics has moved it and before this frame draws.
766
+ * The engine owns the phase ordering; a callback cannot be misplaced by plugin-array order.
767
+ * @situation read a body after physics has moved it
768
+ * @situation place a camera or aim from the solved character transform
769
+ * @constraint register from a scene context; callbacks are cleared when that scene exits
770
+ * @example afterPhysics(ctx, (dt) => camera.position.copy(player.mesh.position));
771
+ */
772
+ export { afterPhysics } from "./loop.js";
773
+ export type { AfterPhysicsCallback } from "./loop.js";
774
+ /**
775
+ * Compose game-provided render nodes in a measured, fail-closed chain. Authored stages use an
776
+ * opaque id and anchor before or after a built-in or another supplied stage; the engine does not
777
+ * need to know the effect's visual vocabulary.
778
+ * @situation compose screen-space effects in a canonical order
779
+ * @situation insert a game-authored post stage into the measured render chain
780
+ * @situation report which render tier and velocity route actually ran
781
+ * @constraint stage factories own colour, strength, and all other appearance choices
782
+ * @constraint authored stages declare exactly one before or after anchor
783
+ * @example const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: ["bloom"], tier: "auto" } });
784
+ */
785
+ export {
786
+ RENDER_CHAIN_MARKER,
787
+ RENDER_CHAIN_STAGE_ORDER,
788
+ RENDER_CHAIN_TIERS,
789
+ RenderChain,
790
+ readRenderChainObservation,
791
+ readRenderChainReport,
792
+ } from "./render/chain.js";
793
+ export type {
794
+ IRenderChainApplied,
795
+ IRenderChainBudgetWindow,
796
+ IRenderChainDroppedStage,
797
+ IRenderChainOptions,
798
+ IRenderChainRenderer,
799
+ IRenderChainRequest,
800
+ IRenderChainStage,
801
+ IRenderChainStageContext,
802
+ IRenderChainVelocityMeasurement,
803
+ IRenderChainVelocityResult,
804
+ IRenderChainVelocityReport,
805
+ IRenderChainVelocityRequest,
806
+ RenderChainSource,
807
+ RenderChainStageId,
808
+ RenderChainStageName,
809
+ RenderChainTier,
810
+ RenderChainTierRequest,
811
+ RenderChainVelocitySource,
812
+ } from "./render/chain.js";
813
+ /**
814
+ * Bake static diffuse irradiance that reaches surfaces from outside the camera view.
815
+ * @situation light bouncing from a room I cannot see
816
+ * @situation light a wall with an off-screen emitter
817
+ * @alias readable world lighting
818
+ * @constraint request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting
819
+ * @constraint add the volume with ctx.add() so its incremental work is measured in the render phase
820
+ * @constraint call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
821
+ * @override density, bounds, bakeBudgetMs, and bounces are game-owned choices
822
+ * @example const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
823
+ */
824
+ export {
825
+ ATLAS_PADDING,
826
+ PROBE_VOLUME_MARKER,
827
+ ProbeVolume,
828
+ } from "./render/probe-volume.js";
829
+ /**
830
+ * Read the most recent observation from a probe volume.
831
+ * @situation inspect the latest probe bake observation
832
+ * @constraint the returned observation is a measurement; it does not own lighting or materials
833
+ * @example const observation = readProbeVolumeObservation(probes);
834
+ */
835
+ export { readProbeVolumeObservation } from "./render/probe-volume.js";
836
+ export type {
837
+ IProbeVolumeBakeProgress,
838
+ IProbeVolumeCoefficient,
839
+ IProbeVolumeObservation,
840
+ IProbeVolumeOptions,
841
+ ProbeVolumeDensity,
842
+ } from "./render/probe-volume.js";
843
+ /**
844
+ * Provision screen-space motion data for temporal nodes and keep per-instance history at the
845
+ * frame boundary.
846
+ * @situation keep a skinned character or instanced crowd stable in a temporal stage
847
+ * @situation add the velocity output to a Three.js scene pass
848
+ * @constraint call `VelocityTracker.update()` before the render and `commit()` after it
849
+ * @constraint a pass is only given a velocity target when a temporal stage consumes it
850
+ * @example
851
+ * const scenePass = pass(scene, camera);
852
+ * ensureVelocityOutput(scenePass);
853
+ * renderer.setOutputNode(scenePass);
854
+ * const tracker = new VelocityTracker();
855
+ * tracker.update(scene);
856
+ * renderer.render(scene, camera);
857
+ * tracker.commit(scene);
858
+ */
859
+ export {
860
+ VELOCITY_OUTPUT_NAME,
861
+ VELOCITY_PREVIOUS_BONE_MATRICES,
862
+ VELOCITY_PREVIOUS_INSTANCE_MATRICES,
863
+ VELOCITY_PREVIOUS_WORLD_MATRIX,
864
+ VelocityTracker,
865
+ ensureVelocityOutput,
866
+ readVelocityPreviousBoneMatrices,
867
+ readVelocityPreviousMatrices,
868
+ readVelocityPreviousWorldMatrix,
869
+ velocityTexture,
870
+ withVelocityContext,
871
+ } from "./render/velocity.js";
872
+ export type { IVelocityRenderPass } from "./render/velocity.js";
873
+ /**
874
+ * One directional shadow for a whole open world: camera-centred clip levels, each snapped to its
875
+ * own texel grid and re-rendered only when its window moves. Tracked casters draw into a
876
+ * per-level mover map every frame, so animated casters do not invalidate the cached levels after
877
+ * the one refresh caused by tracking or untracking them.
878
+ * Plugs into three's own `light.shadow.shadowNode` slot, so every material receives it.
879
+ * @situation crisp shadows close to the player across a large outdoor level
880
+ * @situation shadow map too coarse over a big terrain
881
+ * @situation one directional light shadow for a whole open world
882
+ * @situation shadows shimmer when the camera moves
883
+ * @constraint the light must be a DirectionalLight with `castShadow` and a target in the scene
884
+ * @constraint clipExtents are half-widths in world units, finest first, strictly increasing
885
+ * @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
886
+ * @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
887
+ * @constraint call `object.layers.set(VIRTUAL_SHADOW_CASTER_LAYER)` for a mesh that exists only to cast; the level cameras already render that layer and the main camera never does
888
+ * @override bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement
889
+ * @example
890
+ * const sun = new DirectionalLight(0xffffff, 3);
891
+ * sun.castShadow = true;
892
+ * sun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });
893
+ */
894
+ export {
895
+ VIRTUAL_SHADOW_CASTER_LAYER,
896
+ VIRTUAL_SHADOW_MARKER,
897
+ VIRTUAL_SHADOW_MOVER_LAYER,
898
+ VIRTUAL_SHADOW_WIDE_CASTER_LAYER,
899
+ VirtualShadowNode,
900
+ } from "./render/virtual-shadow.js";
901
+ export { readVirtualShadowMarker } from "./render/virtual-shadow.js";
902
+ /**
903
+ * An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye,
904
+ * hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.
905
+ *
906
+ * @situation daytime sky, sun and shadows for a large outdoor map
907
+ * @situation distant terrain should fade into the sky instead of a coloured wall
908
+ * @situation match a Blender look-dev scene's sun, sky and exposure in the game
909
+ * @constraint every value is required; there is no default sun, sky, haze or exposure
910
+ * @constraint `skySize` must keep the sky box's corners inside the camera's far plane
911
+ * @constraint shadowExtents follow `VirtualShadowNode`: half-widths, finest first, strictly increasing
912
+ * @override sky uniforms stay live on `daylight.sky`; the light and fill are `daylight.sun` and `daylight.fill`
913
+ * @example
914
+ * 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 });
915
+ * ctx.add(daylight);
916
+ */
917
+ export { Daylight } from "./render/daylight.js";
918
+ export type { IDaylightOptions } from "./render/daylight.js";
919
+ export type { IVirtualShadowOptions, IVirtualShadowStats } from "./render/virtual-shadow.js";
920
+ /**
921
+ * Attach hundreds of built objects to the scene in slices, presenting a frame between each.
922
+ * @situation add hundreds of built objects to the scene without one multi-second frame
923
+ * @situation stream a detail tier in behind a loading curtain without the page looking hung
924
+ * @constraint the objects, and where each one goes, stay the game's; this decides only when each joins the graph
925
+ * @constraint input order is the attach order and cannot be changed
926
+ * @constraint a false `while` stops the run and is reported as `stopped`, never thrown
927
+ * @override a slice ends on an 8 ms budget unless the game gives `sliceSize`, and the reported sliceSize is then the measured average; `marker: false` silences the TN_ADD_SLICES line, not the report
928
+ * @example const report = await addInSlices(objects, (object) => ctx.add(object), {
929
+ * onProgress: ({ added, total }) => setProgress(added / total),
930
+ * while: () => generation.live,
931
+ * });
932
+ */
933
+ export { addInSlices } from "./streaming.js";
934
+ export type {
935
+ IAddInSlicesOptions,
936
+ IAddInSlicesProgress,
937
+ IAddInSlicesReport,
938
+ } from "./streaming.js";
939
+ /**
940
+ * Load a list with bounded concurrency, returning results in the input's order.
941
+ * @situation load many models or textures in parallel instead of one at a time
942
+ * @situation keep a loading screen moving while a list of assets downloads
943
+ * @constraint results are written to each item's own index and never appended, so a positional lookup finds the same asset on every load
944
+ * @constraint the first rejection rejects the call and no lane starts a load it had not begun
945
+ * @override concurrency defaults to 6; `marker: false` silences the TN_LOAD_ALL line, not onProgress
946
+ * @example const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));
947
+ */
948
+ export { loadAll } from "./streaming.js";
949
+ export type { ILoadAllOptions, ILoadAllProgress } from "./streaming.js";
950
+ export { warmUpScene } from "./warmup.js";
951
+ export type {
952
+ IWarmUpCacheOptions,
953
+ IWarmUpOptions,
954
+ IWarmUpProgress,
955
+ IWarmUpRenderer,
956
+ IWarmUpReport,
957
+ IWarmUpObservation,
958
+ WarmUpCacheStatus,
959
+ WarmUpObservationStatus,
960
+ } from "./warmup.js";
961
+ export type {
962
+ IGame,
963
+ IGameObservationContribution,
964
+ IGameObservationSampleRequest,
965
+ IGamePluginHooks,
966
+ IGamePluginRuntime,
967
+ IGamePlatformSource,
968
+ } from "./game.js";
969
+ /**
970
+ * Simulate a spectral ocean — cascaded wave spectra inverse-transformed on the GPU each frame.
971
+ * @situation make an ocean whose surface is the view rather than a background
972
+ * @situation float a boat on waves the GPU is drawing
973
+ * @situation drive a water material from a wave simulation without writing an FFT
974
+ * @situation sail a ship on simulated ocean waves with buoyancy
975
+ * @constraint it draws nothing; the game supplies the mesh, the material and every colour
976
+ * @constraint CPU height is a throttled copy carrying staleFrames, never this frame and never exact
977
+ * @constraint an exact free CPU height needs an analytic wave field instead; that is a different contract
978
+ * @constraint cascades are ordered largest patchSize first and every tuning number is required
979
+ * @example const sea = ctx.add(new SpectralOcean(oceanOptions));
980
+ */
981
+ export { SpectralOcean } from "./ocean/spectral.js";
982
+ export type {
983
+ ISpectralOceanCascade,
984
+ ISpectralOceanHeight,
985
+ ISpectralOceanOptions,
986
+ } from "./ocean/spectral.js";
987
+ /**
988
+ * Copy a GPU buffer back to the CPU on a throttle, and report how old each sample is.
989
+ * @situation read a GPU simulation on the CPU without stalling the frame
990
+ * @situation float a body on a wave field whose height only exists on the GPU
991
+ * @situation count GPU-side survivors for a diagnostic without blocking drawing
992
+ * @situation keep a ship floating on simulated ocean waves
993
+ * @constraint the copy is asynchronous, so every sample carries staleFrames and is never this frame
994
+ * @constraint WebGPU only; the seam throws on a WebGL2 renderer rather than returning nothing
995
+ * @constraint one copy is in flight at a time and requests made during one are dropped, not queued
996
+ * @example const heights = new GPUReadback({ attribute: field.value, everyFrames: 4 });
997
+ */
998
+ export { GPUReadback } from "./gpu-readback.js";
999
+ export type { IGPUReadbackOptions, IGPUReadbackSample } from "./gpu-readback.js";
1000
+ /**
1001
+ * Dispatch a game-owned particle surface and process function through a pooled system.
1002
+ * @situation emit sparks, smoke, or other transient effects
1003
+ * @situation update many small visual particles
1004
+ * @situation trail dust, exhaust, or spray behind a moving object
1005
+ * @situation emit cannon smoke and muzzle flash particles
1006
+ * @situation fire a cannonball projectile with cannon smoke particles
1007
+ * @situation splash spray droplets with lifetime and gravity
1008
+ * @situation spawn water droplets, mist, or foam bubbles above a fluid surface
1009
+ * @situation falling snowflakes, rain or ash around the player that thicken into a windy storm or blizzard
1010
+ * @situation kick up a spray of powder snow or dust where a foot or a ball lands
1011
+ * @situation a hit, impact or explosion burst that starts at the point and moment it is asked for, and a second hit that must not move the first hit's live particles
1012
+ * @situation emitParticle a burst of GPU particles at a world position with its own free slots
1013
+ * @constraint geometry, color, and timing remain supplied by the game
1014
+ * @constraint a `spawn` kernel makes bursts requests: `emitParticle({ count, origin })` reserves ring slots, the engine stamps `buffers.births` and `process` reads age as `runtime.time - births[i]`; there is no readback
1015
+ * @constraint a spawn emitter is world space (identity world matrix); `localCoords: true` follows the parent
1016
+ * @constraint requests over `amount` or `maxSpawnPerFrame` clamp, add to `stats.clamped` and warn once; `stats.recycledLive` is `undefined` without the `lifetime` option
1017
+ * @constraint the emitter measures its own bounds and stops computing and drawing after graceSeconds outside the camera view
1018
+ * @constraint a game needs no emitting = visible gate, and an emitter with no measured bounds is never culled for leaving the view
1019
+ * @constraint when measured GPU cost passes the frame budget, the smallest projected emitters pause first, and cull.reason reads outside-view or over-budget
1020
+ * @override localCoords, maxSpawnPerFrame and lifetime tune a spawn emitter; `restart()` kills every particle and rewinds the ring
1021
+ * @override onCull: "clear" restarts a returning effect, the default "pause" resumes it with buffers intact
1022
+ * @override bounds supplies a fixed local Box3 and skips GPU measurement, padding enlarges the world box, boundsEveryFrames sets the measurement cadence
1023
+ * @override graceSeconds sets the seconds outside the view before culling, and Infinity disables view culling
1024
+ * @example const particles = new GPUParticles3D(particleOptions);
1025
+ * particles.emitParticle({ count: 220, origin: hit.position });
1026
+ */
1027
+ export { GPUParticles3D } from "./particles.js";
1028
+ export type {
1029
+ IEmitParticleRequest,
1030
+ IGPUParticles3DOptions,
1031
+ IGPUParticles3DRuntime,
1032
+ IGPUParticles3DSpawnBuffers,
1033
+ IGPUParticles3DSpawnRequest,
1034
+ IGPUParticles3DStats,
1035
+ } from "./particles.js";
1036
+ /**
1037
+ * Simulate a deterministic 2D velocity-and-dye field on the GPU while exposing its data to game-owned rendering.
1038
+ * @situation simulate smoke, fire, fog, wind, or fluid response on a grid
1039
+ * @situation inject a touch, pointer, or gameplay impulse into a fluid field
1040
+ * @situation sample fluid dye or velocity in a game-owned render node
1041
+ * @situation simulate ocean currents and wind affecting a sailing ship
1042
+ * @situation simulate ocean fluid dynamics and currents that affect a ship
1043
+ * @constraint add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
1044
+ * @constraint `dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code
1045
+ * @constraint the conformance sample measures mean absolute velocity divergence at 0.001732 after four 32² steps with pressureIterations 2, below the 0.0025 threshold
1046
+ * @override pressureIterations, viscosity, vorticity, and splatRadius tune the solver without changing its pass order
1047
+ * @example const field = new FluidField2D({ resolution: 256, pressureIterations: 20 });
1048
+ * ctx.add(field);
1049
+ * field.splat({ x: 0.5, y: 0.5 }, { x: 0.2, y: 0 }, 1);
1050
+ */
1051
+ export { FluidField2D } from "./fluid-field.js";
1052
+ export type { IFluidFieldOptions, IFluidFieldSampler, IFluidFieldVector2 } from "./fluid-field.js";
1053
+ /**
1054
+ * Simulate liquid as GPU particles (pour, splash, dam break, waterfall) and expose positions, a density volume and a surface height while the game owns every look.
1055
+ * @situation pour, splash, or dam-break water that fills a container and flows around obstacles
1056
+ * @situation simulate water or another liquid as particles in a fluid simulation
1057
+ * @situation drop a ball or box into liquid and let it displace and float on the water
1058
+ * @situation emit a stream or waterfall of particle fluid and drain it somewhere else
1059
+ * @situation sample particle-fluid density or surface height in a game-owned render node
1060
+ * @constraint add the fluid through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic
1061
+ * @constraint a renderer without WebGPU compute throws a named error at attach; it never draws nothing
1062
+ * @constraint `emit` recycles the oldest slot once `capacity` slots have been used; `fill` stops at capacity
1063
+ * @constraint `sample` and `stats` read a throttled GPU copy and report `staleFrames`; they are never live
1064
+ * @override iterations, viscosity, cohesion, vorticity, gravity and maxSpeed tune the solver without changing its pass order
1065
+ * @example const water = new FluidParticles3D({ capacity: 6000 });
1066
+ * ctx.add(water);
1067
+ * water.fill([-2.8, 0.1, -1.5], [-0.6, 3, 1.5]);
1068
+ */
1069
+ export { FluidParticles3D } from "./fluid-particles.js";
1070
+ export type {
1071
+ IFluidBounds,
1072
+ IFluidCollider,
1073
+ IFluidParticlesOptions,
1074
+ IFluidParticlesStats,
1075
+ } from "./fluid-particles.js";
1076
+ /**
1077
+ * Propagate a disturbance across a patch of water surface and let it fade.
1078
+ * @situation make a splash or explosion ripple outward across water
1079
+ * @situation show the sea reacting to a bomb, shell, or torpedo hitting it
1080
+ * @situation leave a foam trail behind something moving through water
1081
+ * @situation disturb a water surface the player can see respond
1082
+ * @situation spread and drift foam on a water surface over time
1083
+ * @constraint it draws nothing; the game supplies the mesh, the material and every colour
1084
+ * @constraint add its height to an analytic swell, never in place of one
1085
+ * @constraint the patch is finite and its rim absorbs; call recenter to keep it over the action
1086
+ * @constraint there is no obstacle mask, because a mask is only correct for a body that never moves
1087
+ * @override speed, damping, foamHalfLife, current, step and maxSteps tune the solve; the default
1088
+ * step is 1/60s or the CFL stability limit for the given resolution and speed, whichever is smaller
1089
+ * @example const ripples = new RippleField({ resolution: 128, size: 400 });
1090
+ * ripples.impulse(hit.x, hit.z, 6, -40, 0.5);
1091
+ * ripples.advance(dt);
1092
+ * const lift = ripples.heightAt(boat.x, boat.z);
1093
+ */
1094
+ export { RippleField } from "./ripple-field.js";
1095
+ export type { IRippleFieldFlow, IRippleFieldOptions } from "./ripple-field.js";
1096
+ /**
1097
+ * Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.
1098
+ * @situation float a boat on waves
1099
+ * @situation make water move
1100
+ * @situation find the water surface height at a point
1101
+ * @constraint supply every wave amplitude, wavelength, direction, speed and warp value
1102
+ * @constraint call setTime for the default graph clock when the game advances its own time
1103
+ * @constraint sample allocates a result and a normal vector; ask heightAt when only the height is
1104
+ * wanted, and the warp jacobian, every slope and both allocations are skipped
1105
+ * @example const field = new WaveField({ waves });
1106
+ * const { height, normal } = field.sample(x, z, elapsed);
1107
+ * const lift = field.heightAt(x, z, elapsed);
1108
+ */
1109
+ export { WaveField } from "./wave-field.js";
1110
+ export type {
1111
+ IWaveFieldDomainWarp,
1112
+ IWaveFieldGraphOptions,
1113
+ IWaveFieldOptions,
1114
+ IWaveFieldSample,
1115
+ IWaveFieldWave,
1116
+ WaveDirection,
1117
+ } from "./wave-field.js";
1118
+ /**
1119
+ * Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres
1120
+ * of water between them.
1121
+ * @situation reflect the sky and the shoreline in a lake, pond or river
1122
+ * @situation see the bed through the water and have the shallows fade at the shore
1123
+ * @situation know how deep the water is under a pixel without a second render pass
1124
+ * @situation stop a water surface repeating in visible bands or stripes
1125
+ * @situation keep a crowd of small actors out of the water's reflection so the frame can afford it
1126
+ * @situation stop the water reflection redrawing the whole world every frame
1127
+ * @situation automatically reflect terrain and large casters without redrawing instanced small props
1128
+ * @constraint it draws nothing; the game supplies the mesh, the material and every colour
1129
+ * @constraint the material must be transparent so the frame beneath it is already drawn
1130
+ * @constraint thickness is metres, saturating at maxThickness; sky behind the surface reads deep
1131
+ * @constraint one reflection is a second draw of the world; resolutionScale is its pixels only
1132
+ * @constraint omitted reflection.layers automatically reflects terrain-sized surfaces and large non-instanced casters, excluding instanced/skinned props; TN_WATER_REFLECTION_DEFAULT reports the set once
1133
+ * @override reflection.layers is an explicit Three Layers mask and wins over automatic filtering, including layer-0 mask 1; reflection.minSize overrides the default 10 metre minimum extent
1134
+ * @constraint reflection.refreshInterval is in presented frames; 1 is every frame, and the default
1135
+ * @constraint the mirror plane is level, from level alone; do not parent target to a scaled mesh
1136
+ * @example const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });
1137
+ * material.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);
1138
+ */
1139
+ export { WaterSurface3D } from "./water-surface.js";
1140
+ export type { IWaterReflectionOptions, IWaterSurfaceOptions } from "./water-surface.js";
1141
+ /**
1142
+ * Build a soft round sprite as pixel data instead of painting a canvas.
1143
+ * @situation give smoke, flash, or glow sprites a radial alpha falloff
1144
+ * @situation generate sprite images that render identically under every backend
1145
+ * @constraint canvas-painted images sample black under WebGPURenderer; write sprites as pixel data there
1146
+ * @example const puff = softCircleDataTexture(64, 0.25);
1147
+ */
1148
+ export { softCircleDataTexture } from "./textures.js";
1149
+ /**
1150
+ * Pool travelling bullet-streak meshes for hitscan shots.
1151
+ * @situation show where a hitscan round went
1152
+ * @situation show each round a weapon fires, one tracer per trigger press
1153
+ * @situation draw incoming fire without spawning projectiles
1154
+ * @constraint the surface comes from the game; pooling, travel, and fading belong to the engine
1155
+ * @constraint update once per frame and dispose with the owning scene
1156
+ * @example const tracers = new TracerPool3D(ctx.scene, tracerOptions);
1157
+ * tracers.spawn(muzzle, shotDirection, hit.distance);
1158
+ */
1159
+ export { TracerPool3D } from "./tracers.js";
1160
+ export type { ITracerPool3DOptions, ITracerSpawnOptions } from "./tracers.js";
1161
+ /**
1162
+ * Move an object along a Three.js curve with Godot-style path following.
1163
+ * @situation move an enemy or prop along a patrol path
1164
+ * @situation sample a racing line from a curve
1165
+ * @example const follower = new PathFollow3D({ points: patrolPoints, loop: true, speed: 3 });
1166
+ */
1167
+ export { PathFollow3D } from "./path-follow.js";
1168
+ /**
1169
+ * Keep a rendered model's feet on a surface while preserving an auditable override.
1170
+ * @situation keep a character's feet on the floor
1171
+ * @situation correct visual grounding after an animation update
1172
+ * @constraint import from `@threenative/core`; this moves the rendered model, not its physics collider
1173
+ * @override enabled controls whether correction is applied while clearance is still measured
1174
+ * @example import { GroundSnap } from "@threenative/core";
1175
+ * const snap = new GroundSnap(character, { enabled: true });
1176
+ */
1177
+ export { GroundSnap } from "./grounding.js";
1178
+ /**
1179
+ * Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.
1180
+ * @situation fly an airplane with lift, drag, stall and control authority
1181
+ * @situation launch an aircraft off a moving carrier deck
1182
+ * @situation apply component damage or a loadout to an aircraft's performance
1183
+ * @constraint every mass, area, power and inertia value comes from the game's airframe
1184
+ * @constraint damage, stores and configuration arrive as the game's own modifier sample
1185
+ * @example const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });
1186
+ * model.step(1 / 60, { turn: -1, pitch: 0.4 });
1187
+ */
1188
+ export {
1189
+ FlightModel,
1190
+ NEUTRAL_FLIGHT_MODIFIERS,
1191
+ aerodynamicCoefficients,
1192
+ airDensity,
1193
+ aircraftMass,
1194
+ attitudeAxes,
1195
+ gearClearance,
1196
+ setAttitude,
1197
+ } from "./flight.js";
1198
+ export type {
1199
+ IAircraftAirframe,
1200
+ IFlightAxes,
1201
+ IFlightControls,
1202
+ IFlightDeck,
1203
+ IFlightEnvironment,
1204
+ IFlightForces,
1205
+ IFlightModelOptions,
1206
+ IFlightModifiers,
1207
+ IFlightQuaternion,
1208
+ IFlightState,
1209
+ IFlightVector3,
1210
+ } from "./flight.js";
1211
+ export type { IGroundSnapOptions } from "./grounding.js";
1212
+ /**
1213
+ * Measure a Three.js pose for grounded or attachment-aware checks.
1214
+ * @situation inspect a skinned model's posed bounds
1215
+ * @situation verify a character's visual pose
1216
+ * @constraint precise per-vertex measurement is opt-in and not for frame loops
1217
+ * @example const measurement = measureThreePose(model);
1218
+ */
1219
+ export { measureThreePose, posedBounds } from "./pose-measure.js";
1220
+ export type {
1221
+ IMeasureThreePoseOptions,
1222
+ IThreePoseBounds,
1223
+ IThreePoseMeasurement,
1224
+ ThreePoseQuaternion,
1225
+ ThreePoseVector,
1226
+ } from "./pose-measure.js";
1227
+ export type {
1228
+ IPathFollow3DOptions,
1229
+ IPathFollow3DProjection,
1230
+ IPathFollow3DSample,
1231
+ } from "./path-follow.js";
1232
+ /**
1233
+ * Dispatch portable pointer events from the game surface to registered Three.js objects.
1234
+ * @situation let the player click on a thing in the world
1235
+ * @situation show a 3D object while a pointer hovers over it
1236
+ * @situation handle touch and mouse taps on a loaded model without naming its child meshes
1237
+ * @situation drag a crate or prop with the mouse or a finger
1238
+ * @constraint listeners are side-table registrations; Three.js prototypes are never patched
1239
+ * @constraint one raycast serves each active pointer and no raycast runs when nothing is registered
1240
+ * @example ctx.pointer.on(tile, "tapped", (event) => place(event.point));
1241
+ */
1242
+ export { PointerEvents3D } from "./pointer-events.js";
1243
+ export type {
1244
+ IPointerDragHandle,
1245
+ IPointerEvent3D,
1246
+ IPointerEvents3D,
1247
+ IPointerEvents3DOptions,
1248
+ IPointerEvents3DPicker,
1249
+ IPointerState,
1250
+ PointerEvent3DListener,
1251
+ PointerEvent3DType,
1252
+ } from "./pointer-events.js";
1253
+ /**
1254
+ * Read the host platform without reaching for browser globals.
1255
+ * @situation branch a portable game on web or native
1256
+ * @situation choose touch controls for a mobile device
1257
+ * @situation can I raytrace on native
1258
+ * @constraint only use the returned platform facts; native globals are host-owned
1259
+ * @constraint ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result
1260
+ * @example if (isMobile()) showTouchControls();
1261
+ */
1262
+ export { getPlatform, isMobile, isNative, isTouchscreenAvailable, isWeb } from "./platform.js";
1263
+ export type {
1264
+ IPlatformInfo,
1265
+ PlatformFormFactor,
1266
+ PlatformOS,
1267
+ PlatformRuntime,
1268
+ } from "./platform.js";
1269
+ /**
1270
+ * Raycast the game scene using the framework's picker.
1271
+ * @situation select an object under the pointer
1272
+ * @situation interact with the first collider or mesh hit
1273
+ * @supersedes new Raycaster(
1274
+ * @example const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });
1275
+ */
1276
+ export { ScenePicker } from "./picking.js";
1277
+ export type { IRaycastOptions, IScenePickerOptions } from "./picking.js";
1278
+ /**
1279
+ * Record or replay deterministic game input and state.
1280
+ * @situation reproduce a gameplay bug from recorded input
1281
+ * @situation run a deterministic replay in a playtest
1282
+ * @alias fixed seed fixed-step simulation
1283
+ * @constraint use a seeded random source and fixed-step simulation for meaningful replays
1284
+ * @example const driver = createReplayDriver(recording, ctx.renderer.domElement);
1285
+ */
1286
+ export { createReplayDriver, replay } from "./replay.js";
1287
+ export type { IReplayOptions, Recording } from "./replay.js";
1288
+ /**
1289
+ * Validate and parse a replay recording file.
1290
+ * @situation validate a recording before replaying it in another host
1291
+ * @constraint recordings are version 1; the parser fails closed with TN_REPLAY_* codes
1292
+ * @example const recording = parseReplayRecording(rawRecording);
1293
+ */
1294
+ export { parseReplayRecording } from "./replay-protocol.js";
1295
+ export type {
1296
+ IReplayRecording,
1297
+ IReplayRecordingSample,
1298
+ ReplayPointer,
1299
+ } from "./replay-protocol.js";
1300
+ /**
1301
+ * Schedule delayed and repeating callbacks or tween numeric properties with game-owned cleanup.
1302
+ * @situation delay an enemy patrol transition
1303
+ * @situation run a callback every simulation tick
1304
+ * @situation tween a numeric property with a game-owned curve
1305
+ * @situation a countdown timer: end the level when its time limit runs out
1306
+ * @alias tower defense game
1307
+ * @alias spawn waves
1308
+ * @constraint dispose returned handles when the owning scene exits
1309
+ * @constraint ease receives progress in the range 0 to 1 and its return value is the interpolation factor
1310
+ * @example const door = { y: 0 };
1311
+ * await ctx.tween(door, { y: 2.4 }, 0.5, { ease: (t) => 1 - (1 - t) ** 3 });
1312
+ */
1313
+ export { Scheduler } from "./schedule.js";
1314
+ export type { ITweenOptions, ScheduleHandle } from "./schedule.js";
1315
+ /**
1316
+ * Implement a portable Godot-shaped game scene lifecycle.
1317
+ * @situation add a playable level or menu scene
1318
+ * @situation move scene setup and per-frame gameplay out of the entry point
1319
+ * @situation run scene work once per actual world draw, after the frame's last fixed update and before the projection packs
1320
+ * @constraint scene code must stay portable across web and native
1321
+ * @example class Play extends Scene { update(ctx, dt) {} }
1322
+ * @example ctx.beforeRender(() => packBatches()); // cleared on scene change and stop, like ctx.afterPhysics
1323
+ */
1324
+ export { Scene } from "./scene.js";
1325
+ export type { ICtx, SceneFrame } from "./scene.js";
1326
+ /**
1327
+ * Advance a game-owned non-uniform sprite atlas on the fixed step.
1328
+ * @situation play an animated pickup or sprite-sheet effect
1329
+ * @situation sequence atlas frames with different authored durations
1330
+ * @constraint the game supplies the atlas texture, surface, filtering, layout, and every frame duration
1331
+ * @constraint update is driven by the scene fixed step; no wall clock or default frame rate is used
1332
+ * @example const animator = new SpriteAnimator3D({ texture: atlas, frames, mode: "pingPong" });
1333
+ */
1334
+ export { SpriteAnimator3D } from "./sprite-animator.js";
1335
+ export type {
1336
+ ISpriteAnimator3DOptions,
1337
+ ISpriteFrame3D,
1338
+ SpritePlaybackMode,
1339
+ } from "./sprite-animator.js";
1340
+ /**
1341
+ * Keep transient render surfaces in the renderer's pipeline cache before first use.
1342
+ * @situation prewarm a projectile, tracer, particle, or other transient effect
1343
+ * @situation avoid a long first-use frame for a newly visible effect
1344
+ * @constraint keep the surface visible with zero opacity; do not hide it with `visible = false`
1345
+ * @supersedes .visible = false
1346
+ * @example prewarm(tracerPool);
1347
+ */
1348
+ export { prewarm } from "./renderer.js";
1349
+ /**
1350
+ * Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.
1351
+ * @situation inspect shader and pipeline creation work during a real launch
1352
+ * @situation correlate pipeline creation with material, object, pass, and shader identities
1353
+ * @constraint the capture is bounded and incomplete when the backend cannot expose an observation
1354
+ * @example const capture = game.runtime.pipelineCensus?.();
1355
+ * // The game normally reaches this through `runtime.pipelineCensus`; direct construction exists
1356
+ * // for renderer adapters and contract tests, not for gameplay.
1357
+ */
1358
+ export {
1359
+ DEFAULT_PIPELINE_CENSUS_LIMIT,
1360
+ PIPELINE_CENSUS_CAPABILITY,
1361
+ PIPELINE_CENSUS_VERSION,
1362
+ createPipelineCensus,
1363
+ PipelineCensus,
1364
+ } from "./pipeline-census.js";
1365
+ export type {
1366
+ IPipelineCensus,
1367
+ IPipelineCensusCounts,
1368
+ IPipelineCensusEvent,
1369
+ IPipelineCensusOptions,
1370
+ IPipelineProvenance,
1371
+ IPipelineShaderObservation,
1372
+ PipelineCensusMode,
1373
+ PipelineCensusStatus,
1374
+ } from "./pipeline-census.js";
1375
+ /**
1376
+ * Scale an asset to a real-world measurement and return the applied factor.
1377
+ * @situation make a character exactly 1.8 metres tall
1378
+ * @situation normalize a prop or weapon to a known longest axis
1379
+ * @constraint skinned height uses a crown bone; game-specific asset expectations stay in render code
1380
+ * @supersedes new Box3().setFromObject(
1381
+ * @example normaliseToMetres(character, { metres: 1.8, axis: "height" });
1382
+ */
1383
+ export { normaliseToMetres } from "./scale.js";
1384
+ export type { INormaliseToMetresOptions, NormaliseAxis } from "./scale.js";
1385
+ /**
1386
+ * Repair an exported rig whose animation clips are z-mirrored against its own bind pose.
1387
+ * @situation find out why a skinned character renders deformed
1388
+ * @situation repair an imported character that walks backwards with its spine folded
1389
+ * @situation load a rigged GLB through a custom loader and keep the framework's repair
1390
+ * @constraint the model loader already applies this automatically; only a game loading GLBs around it needs the call
1391
+ * @constraint detection votes per tracked bone and converts only on an overwhelming signature; a file that does not carry it is left byte-identical
1392
+ * @example import { reconcileMirroredClips } from "@threenative/core";
1393
+ * if (reconcileMirroredClips(gltf.scene, gltf.animations)) console.info("clips were z-mirrored; repaired");
1394
+ */
1395
+ export { reconcileMirroredClips } from "./assets.js";
1396
+ /**
1397
+ * Attach a game-owned object to a named skeleton bone.
1398
+ * @situation put a weapon in a character's hand
1399
+ * @situation hold a rifle in a character's right hand
1400
+ * @situation add an enemy that patrols the level, chases the player when it sees them, and holds a rifle in its right hand
1401
+ * @situation attach an accessory to a skinned model
1402
+ * @situation equip crew with swords and pistols
1403
+ * @situation put a sword or pistol in a crew member's hand
1404
+ * @constraint when a request is to hold or attach a weapon to a hand, import and call `attachToBone` from `@threenative/core`; do not manually parent, position, or rotate the rifle
1405
+ * @constraint if a stock visual has no skeleton, add a portable Three.js Bone named `RightHand` under the character, then call `attachToBone`; do not replace the helper with manual parenting
1406
+ * @example import { attachToBone } from "@threenative/core";
1407
+ * attachToBone(character, "RightHand", rifle);
1408
+ */
1409
+ export { attachToBone } from "./skeleton.js";
1410
+ /**
1411
+ * List the names of every bone in a character hierarchy.
1412
+ * @situation inspect the available bones before attaching a game-owned object
1413
+ * @situation debug a missing skeleton bone name
1414
+ * @example import { skeletonBones } from "@threenative/core";
1415
+ * const bones = skeletonBones(character);
1416
+ */
1417
+ export { skeletonBones } from "./skeleton.js";
1418
+ /**
1419
+ * Measure whether a named bone reaches the object it is supposed to be touching, in metres.
1420
+ * @situation check that a seated character's hands reach the keyboard
1421
+ * @situation check that a character's hips meet the chair it is sitting on
1422
+ * @situation turn "the character is not touching the prop" into a number a scenario can assert
1423
+ * @constraint this walks the target's vertices; call it on a check or a debug sample, not every frame
1424
+ * @example import { boneContact } from "@threenative/core";
1425
+ * const contact = boneContact(worker, "hand_r", keyboard);
1426
+ */
1427
+ export { boneContact } from "./skeleton.js";
1428
+ export type { IBoneContactReport } from "./skeleton.js";
1429
+ /**
1430
+ * Score a retargeted clip against the source it came from, per bone, in degrees.
1431
+ * @situation find out why a retargeted animation looks wrong on a character
1432
+ * @situation tell a fixed retarget from one that merely moved
1433
+ * @situation catch a retarget that rolled every limb about its own axis
1434
+ * @constraint each bone is compared as a whole quaternion relative to its own rig's bind pose, so the two rigs never have to share a bind convention; a bone-direction check reports zero on the roll this catches
1435
+ * @constraint both rigs must face the same way in world space, and both are driven and then restored to the transforms they arrived with
1436
+ * @override bones maps one rig's bone names onto the other's when they differ; samples sets how many poses are compared
1437
+ * @example import { clipPoseError } from "@threenative/core";
1438
+ * const report = clipPoseError({ root: rig, clip: retargeted }, { root: source, clip: original });
1439
+ */
1440
+ export { clipPoseError } from "./clip-audit.js";
1441
+ /**
1442
+ * Report which of a clip's tracks bind to nothing on a character.
1443
+ * @situation find out why a character plays its bind pose instead of the animation
1444
+ * @situation check that a loaded clip actually drives the model it was written for
1445
+ * @constraint the reason is Three.js's own, captured off its console hook so a scenario's console assertions stay clean
1446
+ * @example import { clipTrackBindings } from "@threenative/core";
1447
+ * const bindings = clipTrackBindings(character, clip);
1448
+ */
1449
+ export { clipTrackBindings } from "./clip-audit.js";
1450
+ /**
1451
+ * Report which bones of a character a clip does not drive.
1452
+ * @situation find out why a character keeps the previous animation's hand shape
1453
+ * @situation check how much of a rig a clip covers before shipping it
1454
+ * @constraint a track that binds nothing counts as driving nothing
1455
+ * @example import { clipBoneCoverage } from "@threenative/core";
1456
+ * const coverage = clipBoneCoverage(character, clip);
1457
+ */
1458
+ export { clipBoneCoverage } from "./clip-audit.js";
1459
+ export type {
1460
+ IBonePoseError,
1461
+ IClipBindingReport,
1462
+ IClipCoverageReport,
1463
+ IClipPoseErrorOptions,
1464
+ IClipPoseErrorReport,
1465
+ IClipPoseSubject,
1466
+ IClipTrackBinding,
1467
+ } from "./clip-audit.js";
1468
+ /**
1469
+ * Measure a rig's parent→child bone distances, in world space, as it stands right now.
1470
+ * @situation capture a rig's bind-pose bone lengths before any clip plays
1471
+ * @situation measure a skeleton for the bone-length invariance check
1472
+ * @constraint the baseline and the later comparison must come from the same rig under the same ancestor transform, so a uniform scale cancels
1473
+ * @example import { boneLengths } from "@threenative/core";
1474
+ * const baseline = boneLengths(character);
1475
+ */
1476
+ export { boneLengths } from "./bone-lengths.js";
1477
+ /**
1478
+ * Compare a rig's bone distances now against a captured snapshot and name every bone that moved.
1479
+ * @situation find out why a skinned character renders deformed
1480
+ * @situation check that an animated pose keeps the skeleton rigid
1481
+ * @situation name the bone that breaks a posed skeleton without taking a screenshot
1482
+ * @constraint a rigid skeleton preserves every parent→child distance under any pose; a named bone is a defect with an address
1483
+ * @constraint this is a diagnostic — it reports numbers and names; it moves nothing and decides no appearance
1484
+ * @example import { boneLengths, boneLengthDeviations } from "@threenative/core";
1485
+ * const report = boneLengthDeviations(character, boneLengths(character));
1486
+ * if (!report.rigid && report.worst !== null) console.log(report.worst.bone, report.worst.ratio);
1487
+ */
1488
+ export { boneLengthDeviations } from "./bone-lengths.js";
1489
+ export type {
1490
+ IBoneLengthDeviation,
1491
+ IBoneLengthDeviationReport,
1492
+ IBoneLengthDeviationsOptions,
1493
+ IBoneLengthSnapshot,
1494
+ } from "./bone-lengths.js";
1495
+ export type {
1496
+ ContextMenuPolicy,
1497
+ IInputAction,
1498
+ IInputGamepad,
1499
+ InputBindings,
1500
+ InputPlatformSource,
1501
+ IRawInputPointer,
1502
+ IRawInputPointerEdge,
1503
+ IRawInputState,
1504
+ } from "./input.js";
1505
+ /**
1506
+ * The map a game reads input through: named actions, 2D vectors and scalar axes resolved from
1507
+ * keyboard, gamepad, mouse, wheel, pinch and touch.
1508
+ *
1509
+ * `defineGame({ input })` builds one and hands it to the running game as `ctx.input`, so the usual
1510
+ * route is a binding in the config and `ctx.input.axis("move")` in the update. Construct one
1511
+ * directly to drive a menu, a replay or a test outside a running game.
1512
+ *
1513
+ * @situation map WASD keys to a movement axis instead of reading the held key set in the update loop
1514
+ * @situation read a jump, a fire or a reload as one named action bound to key, gamepad button and mouse button together
1515
+ * @situation read mouse look, wheel zoom or a two-finger pinch as an axis the frame loop already ticks
1516
+ * @constraint `buttons` is the gamepad and `mouseButtons` the mouse; `up`/`down`/`left`/`right` are the directions of `vector(name)`, not the keys that press it
1517
+ * @constraint scroll, pinch and pointer-relative sources are declared on the binding and read through `axis(name)`; a game adds no window listener of its own
1518
+ * @example const game = defineGame({ input: { move: { up: ["KeyW"], down: ["KeyS"], left: ["KeyA"], right: ["KeyD"] } }, scenes: { Play } });
1519
+ * // inside the scene, per frame: ctx.input.axis("move") is 0 at rest and 1 at full tilt
1520
+ */
1521
+ export { InputMap } from "./input.js";
1522
+ /**
1523
+ * Lock the pointer to the game's surface: the capture every first-person mouse look needs.
1524
+ *
1525
+ * A browser grants capture only from a user gesture, so call it from a click or a pointerdown
1526
+ * handler. A relative binding such as `look: { pointerRelative: true }` already requests capture on
1527
+ * the first canvas click; this is the same request for a game that starts capture from another
1528
+ * named gesture, and `ctx.input.captureMouse()` is the map's own way to ask.
1529
+ *
1530
+ * @situation lock the mouse pointer so first-person mouse look keeps the cursor out of the way
1531
+ * @situation stop the cursor leaving the window in the middle of a turn
1532
+ * @constraint the browser grants capture only from a user gesture and a refusal is reported, never swallowed
1533
+ * @constraint a relative binding requests capture on canvas click unless `captureOnClick: false` opts out
1534
+ * @example canvas.addEventListener("click", () => captureMouse(canvas));
1535
+ */
1536
+ export { captureMouse } from "./input.js";