@threenative/core 0.3.6 → 0.3.9

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 (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
package/src/grounding.ts CHANGED
@@ -4,7 +4,12 @@ import { measureThreePose, posedBounds } from "./pose-measure.js";
4
4
  export interface IGroundSnapOptions {
5
5
  /** Whether to apply the correction. Measurement and `clearance` continue when this is false. */
6
6
  readonly enabled?: boolean;
7
- /** Maximum correction speed in metres per second. Unset follows the authored pose exactly. */
7
+ /**
8
+ * Maximum downward correction speed in metres per second. Unset follows the authored pose
9
+ * exactly. A pose below the surface is still raised at once: the rate stops the snap pulling a
10
+ * run cycle's flight phase onto the floor, where the leading foot skates, and never lets a foot
11
+ * sink through it.
12
+ */
8
13
  readonly maxRate?: number;
9
14
  /** Visual meshes to measure. Defaults to every mesh below `model`. */
10
15
  readonly meshes?: readonly Object3D[];
@@ -50,7 +55,7 @@ export class GroundSnap {
50
55
 
51
56
  const desired = surfaceY - before.min[1];
52
57
  const correction =
53
- this.maxRate === undefined ? desired : clamp(desired, -this.maxRate * dt, this.maxRate * dt);
58
+ this.maxRate === undefined || desired > 0 ? desired : Math.max(desired, -this.maxRate * dt);
54
59
  if (this.enabled) this.applyWorldCorrection(group, correction);
55
60
 
56
61
  // Re-read after the move. The group may be under a scaled or rotated parent, so the local
@@ -94,7 +99,3 @@ function validateMaxRate(maxRate: number | undefined): void {
94
99
  throw new Error("GroundSnap maxRate must be finite and non-negative.");
95
100
  }
96
101
  }
97
-
98
- function clamp(value: number, min: number, max: number): number {
99
- return Math.min(max, Math.max(min, value));
100
- }
package/src/hot.ts CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { audioRuntimeSnapshot } from "./audio.js";
4
4
  import type { IGame } from "./game.js";
5
+ import { hostDocument, hostWindow } from "./platform.js";
5
6
  export interface IHotDiagnostics {
6
7
  readonly reloads: number;
7
8
  readonly entities: number;
@@ -15,6 +16,8 @@ type HotData = {
15
16
  readonly reloads: number;
16
17
  /** The scene the session was in. Absent for data written before scene resume existed. */
17
18
  readonly sceneName?: string | undefined;
19
+ /** The session's startup had lifted its cover, so its HUD was showing. */
20
+ readonly revealed?: boolean;
18
21
  };
19
22
  const isDev =
20
23
  (import.meta as ImportMeta & { env?: Record<"DEV", boolean | undefined> }).env?.DEV === true;
@@ -48,16 +51,22 @@ export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics
48
51
  // game and boots it at `config.start` — so a session that was playing came back holding its own
49
52
  // state on the main menu, with every entity and its physics world gone, and the store insisting
50
53
  // the screen was still "playing". Resuming the scene is what makes the restored state true.
54
+ // Whether this session's HUD is showing: carried from a restart that kept it, else this
55
+ // startup's own reveal. One save can update the module twice, the second before this startup
56
+ // is ready, and that update must not cover a HUD the player is looking at.
57
+ let revealed = false;
51
58
  if (carried?.sceneName !== undefined) {
52
59
  try {
53
- game.resumeScene(carried.sceneName);
60
+ game.resumeScene(carried.sceneName, { revealed: carried.revealed === true });
61
+ revealed = carried.revealed === true;
54
62
  } catch {
55
63
  // A scene that no longer exists in the updated module is not a reason to lose the reload;
56
64
  // the game boots at its start scene, which is what it would have done anyway.
57
65
  }
58
66
  }
59
- if (isDev && typeof window !== "undefined") {
60
- const host = window as unknown as Record<string, unknown> &
67
+ const page = hostWindow();
68
+ if (isDev && page !== undefined) {
69
+ const host = page as unknown as Record<string, unknown> &
61
70
  Partial<Record<"__THREENATIVE__", Record<string, unknown> & { hot?: () => IHotDiagnostics }>>;
62
71
  host.__THREENATIVE__ = {
63
72
  ...host.__THREENATIVE__,
@@ -73,7 +82,12 @@ export function acceptHotUpdate<TState extends Record<string, unknown>, TPhysics
73
82
  game.state.flush();
74
83
  const state = game.state.getState();
75
84
  assertPortableState(state);
76
- data.threenative = { reloads: reloads + 1, sceneName: game.sceneName, state };
85
+ data.threenative = {
86
+ reloads: reloads + 1,
87
+ revealed: revealed || game.ctx?.startup.phase === "ready",
88
+ sceneName: game.sceneName,
89
+ state,
90
+ };
77
91
  } catch (error) {
78
92
  data.threenative = undefined;
79
93
  hot.invalidate(error instanceof Error ? error.message : String(error));
@@ -115,7 +129,7 @@ function diagnostics<TState extends Record<string, unknown>, TPhysics>(
115
129
  reloads,
116
130
  entities: ctx === undefined ? 0 : Object.keys(ctx.entities.snapshot()).length,
117
131
  sceneObjects,
118
- canvases: typeof document === "undefined" ? 0 : document.querySelectorAll("canvas").length,
132
+ canvases: hostDocument()?.querySelectorAll("canvas").length ?? 0,
119
133
  audio: audioRuntimeSnapshot(),
120
134
  physics: typeof physics?.numBodies === "function" ? physics.numBodies() : null,
121
135
  };
package/src/index.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * unavoidable here — core is bundled for browsers and cannot read `package.json` at runtime — so
7
7
  * the spec now asserts this equals the manifest instead of asserting a number somebody typed.
8
8
  */
9
- export const version = "0.3.6";
9
+ export const version = "0.3.9";
10
10
 
11
11
  /**
12
12
  * Play a skinned or sprite animation from game code.
@@ -16,23 +16,39 @@ export const version = "0.3.6";
16
16
  * `player.stride` reports the measurement either way. Name the body a game moves as
17
17
  * `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and
18
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.
19
+ * stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so. A mesh counts
20
+ * at its lowest geometry point, so a boot's origin may sit anywhere; an in-place clip with no
21
+ * foot plant reports `inPlace: true` and `clipGroundSpeed: 0`, and stride sync stays off.
22
+ * Evaluation is automatic by default: `updateRate: "auto"` follows measured camera visibility
23
+ * and projected size. `updateRate: 1` evaluates every frame; another positive safe integer names
24
+ * that frame interval. `updateRateReport` reports the effective rate, whether a named override is
25
+ * active, and whether the latest update evaluated. One-shots and fades stay full-rate; root-motion
26
+ * `AnimationComposer` advances every tick, and auto camera-ray targets and camera-parented rigs
27
+ * stay full-rate. A public `mixer` `"loop"` listener promotes the player to full-rate and observes
28
+ * only loop events after registration, so skipped pre-registration cycles are not replayed;
29
+ * `updateRateReport` reports that effective rate.
20
30
  * @situation play an animation on a character
21
31
  * @situation switch a character between idle and attack clips
22
32
  * @situation stop a walking character's feet from sliding or spinning
23
33
  * @situation match a walk or run cycle to how fast a character is moving
24
34
  * @situation match an in-place walk cycle with no root motion to the body's speed
25
35
  * @situation find out what speed an animation clip was authored for
36
+ * @situation reduce animation CPU for distant characters
37
+ * @situation inspect the effective animation evaluation rate
26
38
  * @constraint name the body a game moves as strideRoot when the animated rig is a child of it
27
39
  * @constraint a one-shot clip always plays at its authored rate; the matched rate re-times loops only
40
+ * @constraint a foot mesh is measured at its lowest geometry point (the sole), never its origin; a skinned mesh is measured through its bones
41
+ * @constraint `stride.inPlace: true` with `clipGroundSpeed: 0` means no foot plant was found and stride sync is not active; the playtest `stride` observation carries `inPlace`
28
42
  * @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
43
  * @override strideSync controls whether the matched rate is applied while stride is still measured
44
+ * @override updateRate: "auto" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `"loop"` listener promotes effective evaluation to 1 to preserve event timing
30
45
  * @example const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });
31
46
  */
32
47
  export { AnimationPlayer } from "./animation.js";
33
48
  export type {
34
49
  IAnimationPlayerOptions,
35
50
  IAnimationPlayOptions,
51
+ IAnimationUpdateRateReport,
36
52
  IStrideReport,
37
53
  } from "./animation.js";
38
54
  /**
@@ -70,15 +86,25 @@ export { BlendSpace1D, BlendSpace2D } from "./animation-blend.js";
70
86
  * Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement,
71
87
  * validates requested clips against the file and rig at load time, and sets up AnimationPlayer
72
88
  * with honest stride-root accounting.
89
+ * Animation evaluation inherits AnimationPlayer's automatic camera-based `updateRate: "auto"`
90
+ * default; `updateRate: 1` evaluates every frame, another positive safe integer requests that
91
+ * interval, and `updateRateReport` exposes the effective rate, override status and latest result.
92
+ * One-shots and fades stay full-rate; root-motion `AnimationComposer` advances every tick, and
93
+ * auto camera-ray targets and camera-parented rigs stay full-rate. A public `mixer` `"loop"`
94
+ * listener promotes effective evaluation to 1 and observes only loop events after registration,
95
+ * so skipped pre-registration cycles are not replayed.
73
96
  * @situation put an animated character in the scene
74
97
  * @situation my imported character renders deformed
75
98
  * @situation instance an imported rigged character
76
99
  * @situation validate animation clips on a character rig at load time
77
100
  * @situation prepare a skinned character with safe skeleton cloning and stride sync
101
+ * @situation reduce animation CPU for a crowd of imported rigs
102
+ * @situation inspect an imported rig's effective animation evaluation rate
78
103
  * @constraint use strideRoot to name the body moved by game code when the rig is parented under it
79
104
  * @constraint requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks
80
105
  * @override strideSync controls whether locomotion playback rate matches ground covered
81
106
  * @override size normalises the instance to real-world metres with skin-aware measurement
107
+ * @override updateRate: "auto" chooses the camera-based interval; 1 is full evaluation, and another positive safe integer requests that interval; a public `mixer` `"loop"` listener promotes effective evaluation to 1 to preserve event timing
82
108
  * @example import { SkeletalMesh3D } from "@threenative/core";
83
109
  * const character = new SkeletalMesh3D({
84
110
  * source: gltf.scene, clips: gltf.animations, requiredClips: ["idle", "walk"],
@@ -113,10 +139,17 @@ export type { CameraShakeCurve, ICameraShakeOffset, ICameraShakeOptions } from "
113
139
  /**
114
140
  * Create the portable asset loader a scene also receives as `ctx.assets`.
115
141
  * @situation preload models, textures, or audio before a scene enters
142
+ * @situation keep downloaded web assets on disk between visits
143
+ * @situation download the next scene before the player gets there
144
+ * @situation free the disk cache from a settings menu
145
+ * @situation prefetch assets into the Cache Storage disk cache of a large web game
116
146
  * @situation load assets from a nonstandard base path or a compiled asset manifest
117
147
  * @alias different area props
118
148
  * @alias first playable screen external assets
119
149
  * @constraint reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches
150
+ * @constraint await everything the spawn camera sees before the reveal; `ctx.assets.prefetch` and the background fill are for content out of view, or the player spawns into a half-built world
151
+ * @constraint web only: a native host reads installed files, so `ctx.assets.cache` reports `enabled: false` with the reason and `prefetch` resolves at once
152
+ * @override `assets.cache: false` turns the disk cache off and `assets.backgroundFill: false` turns the post-reveal fill off; both are reported on `ctx.assets.cache`
120
153
  * @example const assets = createAssetLoader({ basePath: "/assets" });
121
154
  * const rock = await assets.texture("rock.png");
122
155
  */
@@ -124,7 +157,15 @@ export { createAssetLoader } from "./assets.js";
124
157
  export { onLaunchFailure } from "./launch-diagnostics.js";
125
158
  export { resetAudioCueLedger } from "./audio.js";
126
159
  export type { ILaunchFailure, LaunchFailureKind } from "./launch-diagnostics.js";
127
- export type { IAssetLoader, IAssetLoaderOptions, ITextureOptions } from "./assets.js";
160
+ export type {
161
+ IAssetCacheState,
162
+ IAssetLoader,
163
+ IAssetLoaderOptions,
164
+ IAssetPrefetchProgress,
165
+ IAssetRequestOptions,
166
+ ITextureOptions,
167
+ } from "./assets.js";
168
+ export type { AssetPriority, IAssetCacheReport } from "./asset-cache.js";
128
169
  export type {
129
170
  IAudioBusOptions,
130
171
  IAudioCompressorOptions,
@@ -224,6 +265,15 @@ export type {
224
265
  ISolarPosition,
225
266
  ISolarPositionInput,
226
267
  } from "./atmosphere/index.js";
268
+ /**
269
+ * Capture game-owned sky radiance into a sun-triggered, frame-budgeted environment map.
270
+ * @situation light a scene from a procedural sky when its sun moves
271
+ * @constraint use an initialized WebGPURenderer; the game supplies the sky and assigns the texture
272
+ * @example const capture = new SkyCapture(renderer, skyNode); if (capture.update(sun)) scene.environment = capture.texture;
273
+ */
274
+ export { SkyCapture, SkyCaptureSchedule } from "./render/sky-capture.js";
275
+ export type { ISkyCaptureOptions } from "./render/sky-capture.js";
276
+
227
277
  /**
228
278
  * Register game-owned IComputeDriven objects with the shared compute lifetime.
229
279
  * @situation use IComputeDriven for a cloth, fluid, boid, or other GPU simulation
@@ -250,6 +300,31 @@ export type {
250
300
  IGPUSceneBVHMaterialGroup,
251
301
  IGPUSceneBVHOptions,
252
302
  } from "./gpu-scene-bvh.js";
303
+ /**
304
+ * Reflection rays against the scene's triangles, in TSL. For a smooth surface, a ray finds what the screen cannot
305
+ * show (a room behind the camera, the far side of an object) and returns the hit's position, normal and material.
306
+ * The game lights the hit in its own stage. The kernel is plain TSL: float textures and a loop, no storage buffer.
307
+ * @situation reflect what is behind the camera in a mirror or a chrome sphere
308
+ * @situation make a glossy or wet floor reflect objects that are off screen
309
+ * @situation trace a shadow ray from a reflected surface toward the sun
310
+ * @situation split a surface's specular by roughness into traced, radiance-cache and diffuse-GI shares
311
+ * @alias lumen reflections
312
+ * @alias dedicated reflection rays
313
+ * @constraint the pack is a snapshot of the static triangles taken when the object is built: build a new one after geometry moves
314
+ * @constraint instanced, skinned, batched and morphing meshes are not in the pack; report.skippedMoving counts them
315
+ * @constraint trace only pixels at or below maxRoughnessToTrace (0.4, Unreal's cut-off): each ray walks the tree
316
+ * @constraint a ray visits at most maxSteps tree nodes, then reports a miss; hit light, the miss colour and the blend with the frame stay in the game's src/render/
317
+ * @constraint the pack needs a device with float32-filterable
318
+ * @override maxRoughnessToTrace, roughnessFadeLength, maxRoughnessToEvaluateRoughSpecular, roughSpecularFadeLength and maxSteps are game-owned choices
319
+ * @example const traced = new TracedReflections(ctx.scene); const hit = traced.trace({ origin, direction, far: 30 }); // light hit.albedo at hit.position in the stage
320
+ */
321
+ export { TracedReflections } from "./render/traced-reflections.js";
322
+ export type {
323
+ IReflectionRoute,
324
+ ITracedHit,
325
+ ITracedRay,
326
+ ITracedReflectionsOptions,
327
+ } from "./render/traced-reflections.js";
253
328
  /**
254
329
  * Collapse many copies of one game-authored shape into a single draw, without counting them first.
255
330
  *
@@ -556,6 +631,117 @@ export type {
556
631
  IFramePhaseSample,
557
632
  } from "./frame-budget.js";
558
633
  export type { FramePassKind, IRenderPassSample, MainDrawSource } from "./render-pass-budget.js";
634
+ /**
635
+ * Read the GPU milliseconds of each named render pass of the newest resolved frame, such as `SSGI`
636
+ * or `AO`, with the whole frame's total.
637
+ * @situation read the GPU cost of one post-processing stage
638
+ * @situation tell which render pass takes the GPU time
639
+ * @constraint absent before a whole frame resolves and on an adapter without timestamp queries; the frame number counts each reading once
640
+ * @example const reading = stageGpuReading(renderer); const ssgiMs = reading?.stages.SSGI;
641
+ */
642
+ export { stageGpuReading } from "./render-pass-budget.js";
643
+ export type { IStageGpuReading } from "./render-pass-budget.js";
644
+ /**
645
+ * A cost ladder for one render stage: the whole GPU frame against the frame period moves it, by
646
+ * Unreal's DynamicRenderScaling rule. A frame over the period for 2 frames in a row steps the level
647
+ * down at once, a frame over the period less 10% headroom steps it down after the 8-frame change
648
+ * period, and a frame with room steps it up. A stage steps only when it could absorb the overage at
649
+ * zero cost, and a level that failed is retried after a growing wait. It decides when to move; the
650
+ * game applies the move.
651
+ * @situation step a render stage down when the GPU frame goes over the frame period
652
+ * @situation pick a quality level from measured GPU time without oscillating
653
+ * @constraint levels are listed cheapest first, and the frame period is the game's own display target
654
+ * @constraint a frame without a resolved GPU reading never moves the level
655
+ * @override explicit: true keeps the level and only reports a frame over the target
656
+ * @example const ladder = new BudgetLadder({ levels: ["low", "high"], framePeriodMs: 1000 / 60, start: "high" }); const window = ladder.observe(stageMs, frameMs);
657
+ */
658
+ export { BudgetLadder } from "./render/budget-ladder.js";
659
+ export type { BudgetVerdict, IBudgetLadderOptions, IBudgetWindow } from "./render/budget-ladder.js";
660
+ /**
661
+ * Reports what a game's global illumination costs against the frame period: the GI share of the GPU
662
+ * frame and whether the frame fits its period less 10% headroom. The method (`none`,
663
+ * `irradianceField`, `screenProbeGather`) holds its level while the game runs, as Unreal's Lumen
664
+ * does: a frame over its period gets cheaper through the primary resolution scale, and the GI pass
665
+ * follows the lower resolution. The budget is the frame period, never a GI time in milliseconds,
666
+ * because a stage reading moves with the GPU clock.
667
+ * @situation global illumination costs too much on a weak GPU
668
+ * @situation see what share of the GPU frame the bounce light takes
669
+ * @situation quality tier for indirect lighting that follows the hardware
670
+ * @constraint the method never changes while the game runs: the primary resolution scale is the run-time lever
671
+ * @constraint the GPU time of a pass is read by the scene name three or the game gave it, so name every GI pass in `stages`
672
+ * @constraint timestamp queries are needed: without them every window is unobserved
673
+ * @alias lumen scalability
674
+ * @alias sg.GlobalIlluminationQuality
675
+ * @alias final gather method
676
+ * @example
677
+ * const gi = new GIBudget({ method: "screenProbeGather", stages: ["SSGI"], framePeriodMs: 1000 / 60 });
678
+ * ctx.beforeRender(() => gi.observeRenderer(ctx.renderer.raw));
679
+ */
680
+ export { GI_METHODS, GIBudget } from "./render/gi-budget.js";
681
+ /**
682
+ * Shows the indirect diffuse light of a frame by itself, the counterpart of Unreal's Lumen
683
+ * `Visualize IndirectDiffuse` mode, so a lighting gap against a reference can be told apart from a scene gap.
684
+ * The game's chain builds the term; this class selects it and fails when the term is missing.
685
+ * @situation see only the bounce light of a frame
686
+ * @situation compare indirect lighting alone against Unreal
687
+ * @situation debug global illumination by looking at the indirect diffuse term
688
+ * @constraint the game's render chain builds the indirectDiffuse node (gathered and cached light times albedo); this class draws nothing else
689
+ * @constraint a mode whose term the chain did not build throws instead of showing the finished frame
690
+ * @override mode: "off" returns the finished frame unchanged
691
+ * @alias lumen visualize
692
+ * @alias indirect diffuse only
693
+ * @alias r.Lumen.Visualize.IndirectDiffuse
694
+ * @example
695
+ * const view = new GIVisualize({ mode: "indirectDiffuse", beauty: frame, indirectDiffuse: albedo.mul(bounce) });
696
+ * pipeline.outputNode = view.node;
697
+ */
698
+ export { GI_VISUALIZE_MODES, GIVisualize } from "./render/gi-visualize.js";
699
+ export type { GIVisualizeMode, IGIVisualizeOptions } from "./render/gi-visualize.js";
700
+ /**
701
+ * Steps a game's soft-shadow tier down (`low`, `medium`, `high`) when the whole GPU frame stays over
702
+ * the frame period, and back up when the frame has room, by the settings of Unreal's virtual shadow
703
+ * map budget (a linear model, 5% headroom). A frame that is slow for another reason keeps its
704
+ * shadows: the tier steps only when the shadow passes could absorb the overage. The game owns the
705
+ * sample counts of each tier and rebuilds its filter on each step; the tiers follow Unreal's
706
+ * `sg.ShadowQuality` Low, Medium and Epic.
707
+ * @situation soft shadow filter costs too much on a weak GPU
708
+ * @situation step the shadow quality tier when the GPU frame goes over the frame period
709
+ * @situation shadow quality tier that follows the hardware
710
+ * @constraint the game rebuilds its filter with the tier's sample counts on each step; this class draws nothing
711
+ * @constraint timestamp queries are needed: without them every window is unobserved and the tier holds
712
+ * @constraint the rule reads the whole GPU frame and the `Shadow` stage, which the receiver filter inside the colour pass is not part of
713
+ * @override explicit: true keeps the game's own sample counts and reports an over-budget frame
714
+ * @alias virtual shadow map scalability
715
+ * @alias sg.ShadowQuality
716
+ * @example
717
+ * const filter = new ShadowFilterBudget({ tier: "high", framePeriodMs: 1000 / 60, onStep: (tier) => { light.shadow.filterNode = filterFor(tier); } });
718
+ * ctx.beforeRender(() => filter.observeRenderer(ctx.renderer.raw));
719
+ */
720
+ export {
721
+ SHADOW_FILTER_TIERS,
722
+ SHADOW_STAGES,
723
+ ShadowFilterBudget,
724
+ } from "./render/shadow-filter-budget.js";
725
+ /**
726
+ * Parse a `TN_SHADOW_TIER` console line back into its report, or `undefined`.
727
+ * @situation inspect which shadow filter tier ran and why it stepped
728
+ * @constraint non-marker lines and malformed markers return `undefined`
729
+ * @example const report = readShadowTierMarker(line); if (report?.stepped) console.log(report.reason);
730
+ */
731
+ export { readShadowTierMarker } from "./render/shadow-filter-budget.js";
732
+ export type {
733
+ IShadowFilterBudgetOptions,
734
+ IShadowFilterReport,
735
+ ShadowFilterTier,
736
+ } from "./render/shadow-filter-budget.js";
737
+ /**
738
+ * Parse a `TN_GI` console line back into its report, or `undefined`.
739
+ * @situation inspect which global illumination method ran and what the frame cost
740
+ * @constraint non-marker lines and malformed markers return `undefined`
741
+ * @example const report = readGIMarker(line); if (report?.verdict === "over") console.log(report.reason);
742
+ */
743
+ export { readGIMarker } from "./render/gi-budget.js";
744
+ export type { GIMethod, IGIBudgetOptions, IGIBudgetReport } from "./render/gi-budget.js";
559
745
  /**
560
746
  * Read what frame rate a game gets when its config does not say, and why.
561
747
  *
@@ -634,8 +820,8 @@ export type { ICounterDevice, IFrameCounters } from "./profiling/FrameCounters.j
634
820
  /**
635
821
  * Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its
636
822
  * 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.
823
+ * already has the shape. On by default in a debug launch, printed at most once per reported window
824
+ * as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.
639
825
  * @situation find out whether a slow frame is the scene's shape or the device
640
826
  * @situation tell an authoring agent what to reduce before it promises a merge
641
827
  * @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
@@ -814,10 +1000,14 @@ export type {
814
1000
  * Bake static diffuse irradiance that reaches surfaces from outside the camera view.
815
1001
  * @situation light bouncing from a room I cannot see
816
1002
  * @situation light a wall with an off-screen emitter
1003
+ * @situation glass or fog inside a room takes the room's bounce light
817
1004
  * @alias readable world lighting
1005
+ * @alias lumen translucency volume
1006
+ * @alias translucency gi
818
1007
  * @constraint request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting
819
1008
  * @constraint add the volume with ctx.add() so its incremental work is measured in the render phase
820
1009
  * @constraint call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour
1010
+ * @constraint a translucent material or a fog sample has no side that faces the light: it reads sampleNonDirectional(position), one atlas fetch, the same in every direction (divide by pi for a radiance)
821
1011
  * @override density, bounds, bakeBudgetMs, and bounces are game-owned choices
822
1012
  * @example const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);
823
1013
  */
@@ -826,6 +1016,39 @@ export {
826
1016
  PROBE_VOLUME_MARKER,
827
1017
  ProbeVolume,
828
1018
  } from "./render/probe-volume.js";
1019
+ /**
1020
+ * The Surface Cache: what a traced global-illumination ray reads where it hits a surface. A material atlas
1021
+ * (base colour and emissive maps reduced to small tiles) answers the albedo and the glow at the hit UV; a flat
1022
+ * material keeps its colour. `SurfaceLights` adds the scene's point and spot lamps at the hit, the brightest eight.
1023
+ * @situation give a traced bounce ray the texture colour and glow of the surface it hits
1024
+ * @alias lumen surface cache
1025
+ * @alias lumen scene
1026
+ * @alias mesh cards
1027
+ * @constraint the materials are fixed when the cache is built; build a new one when a material or a map changes
1028
+ * @constraint a map whose image the runtime does not show to JavaScript (the owned engine's glTF maps) returns the flat colour and is listed in `report.fallbacks`; the `images` option hands over its pixels
1029
+ * @constraint the cache owns no colour, texture or light; the game's materials and lamps are the only source
1030
+ * @override atlasSize and cardTexelDensityScale size the atlas; images supplies the pixels of a map the runtime hides
1031
+ * @example const cache = SurfaceCache.from(materials); cache.albedo(slot, hit.uv.x, hit.uv.y, out);
1032
+ */
1033
+ export { SurfaceCache } from "./render/surface-cache.js";
1034
+ /**
1035
+ * The local lamps at the hit of a traced ray: the point and spot lights whose range reaches it, the brightest eight,
1036
+ * one shadow ray each. The Surface Cache gives the hit its colour; this gives it the lamps.
1037
+ * @situation light the hit of a traced ray with the scene's point and spot lamps
1038
+ * @constraint the cap skips the ninth-brightest lamp and every one after it, and counts them in `skipped`
1039
+ * @constraint the caller answers each shadow ray; the class owns no scene
1040
+ * @override maxLights caps the lamps evaluated at one hit
1041
+ * @example const lamps = new SurfaceLights(lights); lamps.shade(point, normal, albedo, out, (i) => !occluded(i));
1042
+ */
1043
+ export { SurfaceLights } from "./render/surface-cache.js";
1044
+ export type {
1045
+ ISurfaceCacheMaterial,
1046
+ ISurfaceCacheOptions,
1047
+ ISurfaceCacheReport,
1048
+ ISurfaceCacheTexture,
1049
+ ISurfaceLight,
1050
+ ISurfaceLightsOptions,
1051
+ } from "./render/surface-cache.js";
829
1052
  /**
830
1053
  * Read the most recent observation from a probe volume.
831
1054
  * @situation inspect the latest probe bake observation
@@ -899,6 +1122,60 @@ export {
899
1122
  VirtualShadowNode,
900
1123
  } from "./render/virtual-shadow.js";
901
1124
  export { readVirtualShadowMarker } from "./render/virtual-shadow.js";
1125
+ export {
1126
+ LAMP_SHADOW_MARKER,
1127
+ lampShadowMarker,
1128
+ readLampShadowMarker,
1129
+ } from "./render/virtual-shadow.js";
1130
+ export type { ILampShadowStats } from "./render/virtual-shadow.js";
1131
+ /**
1132
+ * Source-angle blocker search and variable-radius PCF on three's shadow map.
1133
+ * @situation soften a directional shadow as the caster-receiver gap grows
1134
+ * @constraint sourceAngleRad is required, in radians in [0, PI/2); orthographic depth shadows only, not VSM
1135
+ * @example sun.shadow.filterNode = sourceAngleShadowFilter({ sourceAngleRad: angle });
1136
+ */
1137
+ export { sourceAngleShadowFilter } from "./render/soft-shadow.js";
1138
+ /**
1139
+ * Source-radius blocker search and variable-radius PCF on a spot or point light's shadow map.
1140
+ * @situation soften a lamp's shadow by the lamp's size, as Unreal's SourceRadius does
1141
+ * @constraint sourceRadius is required, in metres, 0 or more (0 is one hard tap); penumbraScale, the share of the geometric penumbra kept, is in (0, 4] and defaults to 0.6, the width Unreal's lamp ray test resolves; forward-depth maps only
1142
+ * @alias PCSS soft shadows
1143
+ * @override penumbraScale: 1 gives the geometric penumbra of a disk lamp
1144
+ * @example lamp.shadow.filterNode = sourceRadiusShadowFilter({ sourceRadius: 0.05 });
1145
+ */
1146
+ export { sourceRadiusShadowFilter } from "./render/soft-shadow.js";
1147
+ /**
1148
+ * A lamp's penumbra radius in tangent units at a receiver, from the lamp's source radius and the blocker and receiver distances.
1149
+ * @situation measure a lamp shadow's penumbra width without a GPU
1150
+ * @constraint sourceRadius is 0 or more; both distances are positive metres; the result is the geometric tangent, before penumbraScale
1151
+ * @example const tangent = lampPenumbraTangent(0.05, 2, 3);
1152
+ */
1153
+ export { lampPenumbraTangent } from "./render/soft-shadow.js";
1154
+ /**
1155
+ * Convert world-space caster gap to a shadow UV radius, floored at one texel.
1156
+ * @situation measure a source-angle shadow's filter radius without a GPU
1157
+ * @constraint inputs must be finite and non-negative; sizes must be positive and angle < PI/2 radians
1158
+ * @example const radius = penumbraUv(10, angle, 40, 2048);
1159
+ */
1160
+ export { penumbraUv } from "./render/soft-shadow.js";
1161
+ /**
1162
+ * Adds subsurfaceColor times the far-face irradiance to a Two Sided Foliage leaf's emissive node.
1163
+ * @situation add bounce light to the far face of a two sided foliage leaf
1164
+ * @constraint the material needs the foliage marker and subsurfaceColor, else nothing is added and false is returned; call once per material
1165
+ * @example addFoliageBackLight(leaf, backIrradiance);
1166
+ */
1167
+ export { addFoliageBackLight } from "./render/two-sided-foliage.js";
1168
+ export type { ISourceAngleShadowInputs, ISourceAngleShadowOptions } from "./render/soft-shadow.js";
1169
+ /**
1170
+ * Unreal's Substrate rough diffuse (EON) on standard and physical materials, so direct sun and lamp light meets a rough surface
1171
+ * the way Unreal shades it. The same `roughDiffuse` flag works on three's WebGPU renderer and on the owned engine.
1172
+ * @situation shade rough surfaces under a sun or a lamp the way Unreal's Substrate does, not as flat Lambert
1173
+ * @constraint direct light only, indirect light stays Lambert; standard and physical materials; a lamp's `sourceRadius` in metres fades the effect to Lambert at 20 cm; a material changed after its first draw needs `needsUpdate`
1174
+ * @alias Substrate EON, Diffuse_EON, Diffuse_GGX_Rough, rough diffuse, Oren-Nayar
1175
+ * @override material.roughDiffuse = false, or useRoughDiffuse(root, false), puts Lambert back
1176
+ * @example useRoughDiffuse(scene);
1177
+ */
1178
+ export { useRoughDiffuse } from "./render/rough-diffuse.js";
902
1179
  /**
903
1180
  * An outdoor daylight rig: physical sky, one sun with open-world shadows that follow the eye,
904
1181
  * hemisphere fill, sky-coloured haze and the AgX tone curve. Every value is the game's.
@@ -915,7 +1192,103 @@ export { readVirtualShadowMarker } from "./render/virtual-shadow.js";
915
1192
  * ctx.add(daylight);
916
1193
  */
917
1194
  export { Daylight } from "./render/daylight.js";
1195
+ /**
1196
+ * Unreal 5.8.3's tone curve, the default tone mapping of `createRenderer` and `Game`: a filmic curve in ACEScg
1197
+ * (slope 0.88, toe 0.55, shoulder 0.26) after the gamut expansion and blue correction of Unreal's colour LUT.
1198
+ * `installFilmicToneMapping` registers it as three's custom tone mapping.
1199
+ *
1200
+ * @situation the frame should tone map the way a fresh Unreal project does
1201
+ * @constraint WebGPU renderers only: a renderer without a node library keeps ACES and reports `TN_TONEMAP`
1202
+ * @override `createRenderer({ toneMapping: "aces" | "agx" | "neutral" | "none" })` or `game.renderer.toneMapping` in the game config; setting `renderer.raw.toneMapping` later wins
1203
+ * @example const renderer = await createRenderer({ toneMapping: "aces" }); // the named override
1204
+ */
1205
+ export { installFilmicToneMapping } from "./look/filmic-tone-mapping.js";
1206
+ export type { RendererToneMapping } from "./look/default-tone-mapping.js";
1207
+ /**
1208
+ * Auto exposure with Unreal 5.8.3's metering: a 64-bin histogram of log2 luminance (the darkest and brightest 10%
1209
+ * ignored), key 0.18 x 2, -10 to +20 EV100, 3 stops/s brighter and 1 stop/s darker. `AutoExposureNode` meters a colour
1210
+ * texture and outputs the adapted exposure; `exposureSettings` holds the defaults.
1211
+ *
1212
+ * @situation the frame should expose itself the way a fresh Unreal project does as the sun and the view change
1213
+ * @constraint WebGPU renderers only: a renderer without WebGPU keeps the fixed exposure and says so
1214
+ * @override every `IExposureSettings` field, spread over `exposureSettings` and passed to `AutoExposureNode`, replaces the Unreal default
1215
+ * @override `setExposureBias(stops)` is Unreal's Exposure Compensation, live: the game changes it per place or weather (`WorldEnvironment.apply` returns the node as `exposure`)
1216
+ * @situation a white snowfield or a bright storm should not meter to middle grey, and the compensation changes with the weather
1217
+ * @example const slow = { ...exposureSettings, rateDown: 0.5 }; const node = new AutoExposureNode(input, slow, 1);
1218
+ */
1219
+ export { AutoExposureNode } from "./look/auto-exposure.js";
1220
+ export { exposureSettings } from "./look/exposure-settings.js";
1221
+ export type { IExposureSettings } from "./look/exposure-settings.js";
1222
+ /**
1223
+ * The node that says which lighting effects a scene runs and how strong they are, with a fresh Unreal 5.8.3 project's
1224
+ * defaults: the filmic tone curve, Unreal-metered auto exposure, screen-space GI and ambient occlusion, SMAA, Unreal's
1225
+ * bloom and local exposure. It builds the post chain through `renderer.createRenderChain()` and prints `TN_RENDER_CHAIN`
1226
+ * naming every stage as applied or refused with a reason. Property names are Godot's `Environment` where it has one.
1227
+ *
1228
+ * @situation a scene should light and tone map like a fresh Unreal level without wiring each post stage by hand
1229
+ * @situation turn one lighting effect off, or pick a cheaper tier, for a weak GPU or a stylised look
1230
+ * @constraint post stages run on WebGPU only: a renderer without it keeps the fixed exposure and reports `TN_AUTO_EXPOSURE_REFUSED`, and a missing node library keeps ACES and reports `TN_TONEMAP`
1231
+ * @constraint an unknown option value throws instead of becoming the default
1232
+ * @override every option on `IWorldEnvironmentOptions`: `tonemapMode: "aces" | "agx" | "neutral"`, `autoExposureEnabled: false` with a fixed `exposure`, `bloomEnabled`, `gtaoEnabled`, `ssgiEnabled`, `screenSpaceAA`
1233
+ * @example const world = new WorldEnvironment({ tonemapMode: "aces", autoExposureEnabled: false, exposure: 0.8 }); world.apply(renderer, scene, view);
1234
+ */
1235
+ export { WorldEnvironment } from "./look/world-environment.js";
1236
+ export type {
1237
+ ChainStage,
1238
+ IWorldEnvironmentOptions,
1239
+ IWorldEnvironmentStageContext,
1240
+ IWorldEnvironmentTarget,
1241
+ OutputRenderer,
1242
+ ScreenSpaceAA,
1243
+ SsgiQuality,
1244
+ TonemapMode,
1245
+ } from "./look/world-environment.js";
1246
+ /**
1247
+ * The diagnosis switches of the calibration harness for the look (ladder layer, the alpha-squeeze BEFORE arm, a denoise
1248
+ * pass count, the film curve's channel clip, a GI visualisation). A game never sets them; the defaults are the shipped look.
1249
+ *
1250
+ * @situation a calibration capture needs one look effect off or one GI term alone
1251
+ * @constraint set them before the `WorldEnvironment` is built; the layer is 0 to 9 and 9 is everything on
1252
+ * @override each field of `lookDiagnostics`
1253
+ * @example lookDiagnostics.layer = 6; // no gather, no reflections
1254
+ */
1255
+ export { lookDiagnostics } from "./look/look-diagnostics.js";
1256
+ /**
1257
+ * The quality tiers of the Unreal 5.8.3 look: what `high` (a desktop, Unreal's Epic), `medium` and `low` (a phone) turn
1258
+ * on, how a GPU family picks its start tier, and the global illumination and shadow filter settings per tier named
1259
+ * after Unreal's scalability levels. A `WorldEnvironment` with no options starts from `high`.
1260
+ *
1261
+ * `qualityTiers` holds the tier tables: `resolve` picks a start tier from a GPU class, `gi` and `shadow` read a tier's settings.
1262
+ *
1263
+ * @situation pick a start tier for the GPU class and read what that tier costs the look
1264
+ * @situation build a `WorldEnvironment` for a weaker device from a named tier
1265
+ * @constraint an unknown tier name throws with the names it expected
1266
+ * @override pass any `IWorldEnvironmentOptions` field after `qualityPreset(tier)`, or an explicit `tier` to `qualityTiers.resolve`
1267
+ * @example const world = new WorldEnvironment({ ...qualityPreset(qualityTiers.resolve({ gpuClass: renderer.gpuClass })), bloomEnabled: false });
1268
+ */
1269
+ export { EPIC_SSGI, qualityPreset, qualityTiers } from "./look/quality.js";
1270
+ export type {
1271
+ FinalGatherMethod,
1272
+ IGiTier,
1273
+ IShadowFilter,
1274
+ IShadowTier,
1275
+ QualityTier,
1276
+ } from "./look/quality.js";
918
1277
  export type { IDaylightOptions } from "./render/daylight.js";
1278
+ /**
1279
+ * Photometric exposure units: EV100 to the renderer multiplier and back, a physical camera's
1280
+ * EV100, and a meter reading. Conversion only; the exposure and the light values are the game's.
1281
+ *
1282
+ * @situation expose a frame lit in lux and nits with a physical camera exposure value
1283
+ * @constraint arguments must be finite; multipliers, apertures, shutter times, ISO and luminance must be > 0
1284
+ * @example renderer.toneMappingExposure = exposureFromEv100(ev100FromCamera(4, 1 / 60, 100));
1285
+ */
1286
+ export {
1287
+ ev100FromCamera,
1288
+ ev100FromExposure,
1289
+ ev100FromLuminance,
1290
+ exposureFromEv100,
1291
+ } from "./render/exposure-units.js";
919
1292
  export type { IVirtualShadowOptions, IVirtualShadowStats } from "./render/virtual-shadow.js";
920
1293
  /**
921
1294
  * Attach hundreds of built objects to the scene in slices, presenting a frame between each.
@@ -1256,7 +1629,9 @@ export type {
1256
1629
  * @situation choose touch controls for a mobile device
1257
1630
  * @situation can I raytrace on native
1258
1631
  * @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
1632
+ * @constraint image 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
1633
+ * @constraint a native desktop host with ray tracing hardware traces ray batches with `mystralRT.traceRayBatch`, which writes hit records into a typed array you own; read `mystralRT.capabilities().rayBatch` first, and keep the software BVH trace for the web and every other host
1634
+ * @constraint when `mystralRT.capabilities().sharedTransport` is true, `mystralRT.traceRayBatchGpu({ tlas, rays, hits, rayCount })` traces between two GPUBuffers with no copy through CPU memory; `rays` needs the CopySrc usage and `hits` the CopyDst usage, and each call costs CPU time, so measure it against the software trace for your batch size
1260
1635
  * @example if (isMobile()) showTouchControls();
1261
1636
  */
1262
1637
  export { getPlatform, isMobile, isNative, isTouchscreenAvailable, isWeb } from "./platform.js";