@threenative/core 0.3.4 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (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-Bj8G1wmD.d.ts} +102 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12423 -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 +47 -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 +2390 -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 +564 -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 +839 -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
@@ -1,7 +1,39 @@
1
1
  import { AudioListener, Object3D, Audio, Vector3, PositionalAudio } from 'three';
2
2
 
3
+ /**
4
+ * Bus-level dynamics compression, every value the game's.
5
+ *
6
+ * All five are required and none has an engine default: a compressor is a mix decision, and a
7
+ * bus that filled in the threshold itself would be deciding how loud the game is. The ranges are
8
+ * Web Audio's own — threshold -100 to 0 dBFS, knee 0–40 dB, ratio 1–20, attack and release
9
+ * 0–1 s, where 0 is an instant response — and anything outside them throws rather than being
10
+ * quietly clamped into a mix the game did not ask for.
11
+ */
12
+ interface IAudioCompressorOptions {
13
+ /** Level above which the bus is compressed, in dBFS. Must be finite and between -100 and 0. */
14
+ readonly threshold: number;
15
+ /** Width of the soft transition around `threshold`, in dB. Must be finite and 0–40. */
16
+ readonly knee: number;
17
+ /** Input:output ratio above the threshold. Must be finite and 1–20. */
18
+ readonly ratio: number;
19
+ /** Seconds to reach full compression once a peak arrives. Must be finite and 0–1. */
20
+ readonly attack: number;
21
+ /** Seconds to return to unity once the mix falls back. Must be finite and 0–1. */
22
+ readonly release: number;
23
+ }
3
24
  interface IAudioBusOptions {
4
25
  readonly camera: Object3D;
26
+ /**
27
+ * A compressor on this bus's master, holding a loud mix below clipping.
28
+ *
29
+ * Every voice sums into it before the bus's volume gain, so it sees the mix rather than each
30
+ * cue alone — which is the whole point: three cues that are each fine and add up to a clipped
31
+ * master is a defect no per-voice option can see, and a compressor that sat after the gain
32
+ * would be working on a level the bus volume had already moved. Opt in, and every value comes
33
+ * from the game. A runtime with no dynamics node reports `compressor` in `unsupported` rather
34
+ * than playing on uncompressed and quiet about it.
35
+ */
36
+ readonly compressor?: IAudioCompressorOptions;
5
37
  readonly gestureTarget?: EventTarget;
6
38
  readonly listener?: AudioListener;
7
39
  readonly source?: () => EventTarget | undefined;
@@ -85,8 +117,8 @@ interface IAudioRuntimeSnapshot {
85
117
  /**
86
118
  * Cue-shaping options this runtime accepted and could not honour, sorted and de-duplicated.
87
119
  *
88
- * The native host binds neither a biquad filter nor a schedulable `detune`, so `lowpassHz` and
89
- * `detune` are silently dropped there. A mix tuned on the web and shipped to a phone is flat in
120
+ * The native host binds a biquad filter and a compressor but no schedulable `detune`, so
121
+ * `detune` is silently dropped there. A mix tuned on the web and shipped to a phone is flat in
90
122
  * a way nothing else reports, and a build can be failed on this.
91
123
  */
92
124
  readonly unsupported: readonly string[];
@@ -117,6 +149,14 @@ declare class AudioBus {
117
149
  get volume(): number;
118
150
  /** @see IAudioRuntimeSnapshot.unsupported */
119
151
  get unsupported(): readonly string[];
152
+ /**
153
+ * The compressor on this bus's master, or `undefined` when the bus has none — either because
154
+ * the game did not ask for one or because this runtime has no dynamics node.
155
+ *
156
+ * Exposed so a game can read `reduction` off it, which is the only observation that answers
157
+ * "is the compressor doing anything", and so a playtest can assert on it.
158
+ */
159
+ get compressor(): DynamicsCompressorNode | undefined;
120
160
  /**
121
161
  * The whole bus's level, which is what a volume slider and a duck both move.
122
162
  *
@@ -184,4 +224,4 @@ declare class AudioBus {
184
224
  }
185
225
  declare function audioRuntimeSnapshot(): IAudioRuntimeSnapshot;
186
226
 
187
- export { AudioBus as A, type IAudioBusOptions as I, audioRuntimeSnapshot as a, type IAudioPlayOptions as b, resetAudioCueLedger as r };
227
+ export { AudioBus as A, type IAudioBusOptions as I, audioRuntimeSnapshot as a, type IAudioCompressorOptions as b, type IAudioPlayOptions as c, resetAudioCueLedger as r };
@@ -1,6 +1,6 @@
1
1
  import * as three from 'three';
2
2
  import { Camera, Vector2, Vector3, Scene, OrthographicCamera } from 'three';
3
- import { I as IRendererLike } from './renderer-CfsS2hxi.js';
3
+ import { I as IRendererLike } from './renderer-9yEo9hPa.js';
4
4
 
5
5
  interface IViewportSize {
6
6
  readonly aspect: number;
@@ -53,6 +53,10 @@ declare class CanvasLayer {
53
53
  readonly camera: OrthographicCamera;
54
54
  /** Declares that this layer covers the framebuffer, allowing the world pass to be skipped. */
55
55
  opaque: boolean;
56
+ /** Keep preparing/drawing the world behind an opaque loading cover, including scene changes. */
57
+ keepWorldRendering: boolean;
58
+ /** Allow first-use world draws during startup; render-cadence admission runs independently. */
59
+ renderWorldDuringStartup: boolean;
56
60
  constructor(viewport: Pick<Viewport, "onResize" | "size">);
57
61
  dispose(): void;
58
62
  /** Subscribe to drawable-size changes after this layer has updated its camera. */
@@ -1,12 +1,12 @@
1
1
  import { I as IAssetLoader, a as IAssetLoaderOptions } from './assets-CqvE429w.js';
2
- import { F as FramePassKind, K as IRenderPassSample, n as IFramePhaseSample, o as IPipelineCensus, I as IRendererLike, as as IRendererOptions, a as IFrameBudgetWindow, j as IFrameBudgetOptions } from './renderer-CfsS2hxi.js';
2
+ import { F as FramePassKind, c as IRenderPassSample, d as IFramePhaseSample, e as IPipelineCensus, I as IRendererLike, f as IRendererOptions, a as IFrameBudgetWindow, g as IFrameBudgetOptions } from './renderer-9yEo9hPa.js';
3
3
  import { Vector2, Vector3, Object3D, Camera, Intersection, Scene as Scene$1 } from 'three';
4
- import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-DDmC_VVF.js';
4
+ import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-C1-5CviZ.js';
5
5
  import { StoreApi } from 'zustand/vanilla';
6
6
 
7
7
  type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
8
8
  /** Which renderer draws a game's `src/ui/`. @see IThreeNativeConfig.ui */
9
- type ThreeNativeUiRenderer = "native" | "web";
9
+ type ThreeNativeUiRenderer = "native" | "native-css" | "web";
10
10
  /** What the native host does with the render loop while the app is off-screen. */
11
11
  type ThreeNativeBackgroundMode = "continue" | "pause";
12
12
  interface IThreeNativeIconVariants {
@@ -81,8 +81,13 @@ interface IThreeNativeAudioConfig {
81
81
  }
82
82
  /** Texture compression options for the asset compile step; `"none"` ships sources verbatim. */
83
83
  interface IThreeNativeTexturesConfig {
84
- /** Integer at least 4; caps the longest edge, preserving aspect and 4x4 alignment; never upscales. */
85
- readonly maxSize?: number;
84
+ /** Automatic compression floor; omitted fields default to SSIM 0.95 and mean ΔE00 3. */
85
+ readonly floor?: {
86
+ readonly ssim?: number;
87
+ readonly meanDeltaE00?: number;
88
+ };
89
+ /** Scalar or glTF slot map (e.g. baseColorTexture/normalTexture). Integer at least 4; caps the longest edge, preserving aspect and 4x4 alignment; never upscales. */
90
+ readonly maxSize?: number | Readonly<Record<string, number>>;
86
91
  readonly overrides?: readonly {
87
92
  readonly codec: "etc1s" | "none" | "uastc";
88
93
  readonly glob: string;
@@ -144,7 +149,12 @@ interface IThreeNativeModelsConfig {
144
149
  * blocks, and never upscales.
145
150
  */
146
151
  readonly textures?: "none" | {
147
- readonly maxSize?: number;
152
+ readonly floor?: {
153
+ readonly ssim?: number;
154
+ readonly meanDeltaE00?: number;
155
+ };
156
+ /** Scalar or glTF slot map; unlisted slots retain the 2048 default. Shared images use the largest cap. */
157
+ readonly maxSize?: number | Readonly<Record<string, number>>;
148
158
  readonly quality?: number;
149
159
  readonly overrides?: readonly {
150
160
  readonly slot: string;
@@ -292,6 +302,12 @@ type ThreeNativeFramePhase = "hostGap" | "overlay" | "render" | "residual" | "up
292
302
  /** The render-pass kinds a per-pass budget bounds. */
293
303
  type ThreeNativeRenderPassKind = "main" | "shadow" | "reflection" | "nested";
294
304
  interface IThreeNativeConfig {
305
+ /**
306
+ * The engine that draws the game on web and desktop. Defaults to ThreeNative's own C++ engine
307
+ * (`"threenative"`): compiled to Wasm on web, the V8 engine player on desktop. `"threejs"` is the named
308
+ * override: it keeps upstream Three.js on web and the legacy host on desktop. Android and iOS still run the legacy host.
309
+ */
310
+ readonly engine?: "threejs" | "threenative";
295
311
  readonly app?: {
296
312
  readonly id?: string;
297
313
  readonly name?: string;
@@ -319,7 +335,8 @@ interface IThreeNativeConfig {
319
335
  * What the native host does when the player leaves the app — presses the power button,
320
336
  * switches away, minimizes the window. `"pause"` (the default) stops running frames and
321
337
  * suspends audio until the app comes back; `"continue"` keeps rendering off-screen, which a
322
- * server-shaped or split-screen game may genuinely want.
338
+ * server-shaped or split-screen game may genuinely want. On Android the operating system
339
+ * stops the app whatever this says, so `"continue"` takes effect on desktop only.
323
340
  *
324
341
  * Turning the pause off does not turn the reporting off: `TN_LIFECYCLE` markers are emitted
325
342
  * either way and name the mode that executed.
@@ -401,6 +418,12 @@ interface IThreeNativeConfig {
401
418
  */
402
419
  readonly lod?: boolean | IThreeNativeLodConfig;
403
420
  readonly models?: "none" | IThreeNativeModelsConfig;
421
+ /**
422
+ * Also emit the native cooked package (`<output>/native/assets.tnpk`, TNPK v1) beside the
423
+ * existing outputs, for a native-engine build that loads its assets without a JS `GLTFLoader`.
424
+ * Absent or `false` leaves the output set unchanged.
425
+ */
426
+ readonly nativePackage?: boolean;
404
427
  readonly output?: string;
405
428
  readonly source?: string;
406
429
  readonly targets?: {
@@ -459,8 +482,14 @@ interface IThreeNativeConfig {
459
482
  * it when a game would rather pay the per-frame cost than accept the bound.
460
483
  *
461
484
  * Any other value throws at startup rather than falling back to a default nobody asked for.
485
+ *
486
+ * `"js"` names the mirror on a host that would not build one. The native engine player batches
487
+ * the authored scene in its own renderer and reports `hostProjected`, so core builds no mirror and
488
+ * reads no object across the boundary. `"js"` forces the mirror there anyway (for a comparison, or
489
+ * a game that depends on it), and the report states `path: "js"` and `pathOverridden: true`. On
490
+ * three the mirror is the only path, so `"js"` changes nothing.
462
491
  */
463
- readonly projection?: boolean | {
492
+ readonly projection?: boolean | "js" | {
464
493
  readonly materialChecks?: "spread" | "everyFrame";
465
494
  };
466
495
  /**
@@ -524,6 +553,10 @@ interface IThreeNativeConfig {
524
553
  * view, or zero extra processes — and own the appearance difference, which is the trade
525
554
  * being made rather than something to discover in a screenshot.
526
555
  *
556
+ * `"native-css"` runs the same React tree in the game's own JS realm — no web view, no second
557
+ * process — with a native CSS engine painting it and the stylesheet coming from the same Vite +
558
+ * Tailwind build the web renderer uses. Desktop only, experimental, and opt-in.
559
+ *
527
560
  * Which surface `"web"` lands on is the platform's business and never a game's: no config,
528
561
  * type or document names the engine underneath.
529
562
  */
@@ -860,6 +893,10 @@ interface IRenderPerformanceMetrics {
860
893
  }
861
894
  interface IRenderPerformanceSample extends IRenderPerformanceMetrics {
862
895
  readonly frameMs: number;
896
+ /** Successful render-callback completion ID; absolute across clears and retention. */
897
+ readonly sequence?: number;
898
+ /** Completion boundary from the monotonic phase clock, not the rAF timestamp or render-body cost. */
899
+ readonly completedAtMs?: number;
863
900
  /** Where this frame's milliseconds went. Present whenever a frame budget is installed. */
864
901
  readonly phases?: IFramePhaseSample;
865
902
  }
@@ -1103,8 +1140,18 @@ interface IWarmUpOptions {
1103
1140
  * How long the whole warm-up may take before it stops and lets the game start. Default 15000 ms.
1104
1141
  *
1105
1142
  * The launch must never be *worse* for having tried to optimize it.
1143
+ *
1144
+ * It bounds compilation only, and starts once the scene's environment is prepared: a
1145
+ * full-quality PMREM bake is lighting the first frame needs, not compile work, and on a software
1146
+ * adapter it alone outlasts this budget (about 20 s on 3-CPU SwiftShader).
1106
1147
  */
1107
1148
  readonly budgetMs?: number;
1149
+ /**
1150
+ * How long the scene environment's PMREM preparation may take before warm-up gives up on it and
1151
+ * compiles anyway. Default `STARTUP_HOLD_BUDGET_MS` (45000 ms), the startup bound for a game's own
1152
+ * launch work.
1153
+ */
1154
+ readonly environmentBudgetMs?: number;
1108
1155
  /**
1109
1156
  * How the scene is handed to the renderer. Default `"scene"`.
1110
1157
  *
@@ -1149,6 +1196,8 @@ interface IWarmUpOptions {
1149
1196
  * `visibilityForced`, so a game can see how much of its scene the render had to un-hide.
1150
1197
  */
1151
1198
  readonly includeHidden?: boolean;
1199
+ /** The scene that supplies lights and environment when `scene` is an unattached object. */
1200
+ readonly targetScene?: Object3D;
1152
1201
  }
1153
1202
  /** What the warm-up did, so a caller can report it rather than assume it. */
1154
1203
  type WarmUpObservationStatus = "complete" | "incomplete" | "unavailable";
@@ -1234,6 +1283,15 @@ interface IWarmUpRenderer {
1234
1283
  compileAsync?: (scene: Object3D, camera: Camera, targetScene?: Object3D) => Promise<void>;
1235
1284
  computeAsync?: (node: unknown) => Promise<void>;
1236
1285
  pipelineCensus?: () => IPipelineCensus;
1286
+ /**
1287
+ * Performs one covered output-pipeline render without marking first present.
1288
+ *
1289
+ * May settle later than it returns: a renderer whose pipeline creation is asynchronous
1290
+ * (Three's `createRenderPipelineAsync` with its pending/skip draw check) starts the work here
1291
+ * and resolves once every requested pipeline exists, so the warm-up can wait instead of
1292
+ * compiling on the main thread.
1293
+ */
1294
+ warmUpWorldPass?: (scene: Object3D, camera: Camera, targetScene?: Object3D) => void | Promise<void>;
1237
1295
  /** The renderer's own render path, used to build every pass's pipelines once. */
1238
1296
  render?: (scene: Object3D, camera: Camera) => void;
1239
1297
  raw?: unknown;
@@ -1362,11 +1420,28 @@ interface IStartupStatus {
1362
1420
  * Throws on an empty or duplicate label, and on a hold registered after startup already
1363
1421
  * resolved — each means the caller believes it is gating something it is not.
1364
1422
  *
1423
+ * `progress` optionally observes monotonically completed work units (textures, placements or
1424
+ * cells), so a fixed display percentage cannot falsely report a stall. Use completed work,
1425
+ * never time or frame counts. Regressing/invalid values receive no credit, settlement freezes
1426
+ * the count, and the hold's original deadline still applies.
1427
+ * `work` may instead be a predicate, polled once per rendered frame until it returns true, for a
1428
+ * readiness the game measures rather than awaits (spawn cells loaded). It needs no simulation
1429
+ * step, so it also settles under a playtest's deterministic clock, which advances no fixed step
1430
+ * while startup is held. A throwing predicate counts as settled.
1431
+ *
1365
1432
  * @situation hold the loading screen until the game's own asset tier has landed
1366
1433
  */
1367
- hold(label: string, work: Promise<unknown>, budgetMs?: number): void;
1434
+ hold(label: string, work: Promise<unknown> | (() => boolean), budgetMs?: number, progress?: () => number): void;
1368
1435
  }
1369
1436
  interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined> {
1437
+ /** Fraction of the next simulation tick accumulated for the presented frame, in [0, 1). */
1438
+ readonly alpha: number;
1439
+ /** The current frame callback timestamp in milliseconds, shared by web and native. */
1440
+ readonly frameTime: number;
1441
+ /** Opt a transform into draw-only fixed-step interpolation; returns scene-owned removal. */
1442
+ readonly interpolate: (object: Object3D) => () => void;
1443
+ /** Reset history after a game-driven teleport. */
1444
+ readonly resetInterpolation: (object: Object3D) => void;
1370
1445
  readonly fps: number;
1371
1446
  readonly renderer: IRendererLike;
1372
1447
  readonly viewport: Viewport;
@@ -1440,7 +1515,14 @@ interface IGameRuntimeObservations {
1440
1515
  contributions(): readonly IGameObservationContribution[];
1441
1516
  }
1442
1517
  interface IGamePluginRuntime {
1443
- readonly fixedStep: (ticks: number) => number;
1518
+ readonly fixedStep: (ticks: number, options?: {
1519
+ render?: boolean;
1520
+ }) => number;
1521
+ /** Completed scene updates and primary world render requests, independent of budget windows. */
1522
+ readonly frameCounts?: () => {
1523
+ updates: number;
1524
+ renders: number;
1525
+ };
1444
1526
  /**
1445
1527
  * Announces that a diagnostics consumer is going to read render metrics, turning per-frame
1446
1528
  * sample collection on for the rest of the run. Optional: a runtime without collection
@@ -1458,6 +1540,13 @@ interface IGamePluginRuntime {
1458
1540
  * used to land. Optional: a runtime without a clock just never freezes one.
1459
1541
  */
1460
1542
  readonly freezeClock?: () => void;
1543
+ /**
1544
+ * Draw the current world once without advancing it, for a screenshot taken while the loop is
1545
+ * driven by `fixedStep` and presents nothing between ticks. Optional: a runtime without a frozen
1546
+ * render loop just never draws a standing frame. The runner asks for it only when the bridge
1547
+ * advertises it and the capture cannot otherwise see a present.
1548
+ */
1549
+ readonly renderCurrent?: () => number;
1461
1550
  /**
1462
1551
  * Hold start-scene entry until `gate` settles.
1463
1552
  *
@@ -1567,6 +1656,8 @@ interface IGameConfig<TState extends Record<string, unknown> = Record<string, un
1567
1656
  * Maximum simulation steps per rendered frame. Default 5. Caps the catch-up burst after a
1568
1657
  * stall so a slow frame cannot cascade into a spiral of longer frames.
1569
1658
  */
1659
+ /** Smooth physics objects and the camera between fixed ticks. Default true. */
1660
+ readonly physicsInterpolation?: boolean;
1570
1661
  readonly maxSteps?: number;
1571
1662
  readonly platform?: IGamePlatformSource;
1572
1663
  readonly plugins?: readonly GamePlugin<TState, TPhysics>[];
@@ -1655,4 +1746,4 @@ interface IGame<TState extends Record<string, unknown> = Record<string, unknown>
1655
1746
  }
1656
1747
  declare function defineGame<TState extends Record<string, unknown>, TPhysics = undefined>(config: IGameConfig<TState, TPhysics>): IGame<TState, TPhysics>;
1657
1748
 
1658
- export { type IWarmUpRenderer as $, type AfterPhysicsCallback as A, type IRandom as B, type ContextMenuPolicy as C, type IRawInputPointer as D, type IRawInputPointerEdge as E, type IRawInputState as F, GEOMETRY_ASSET_KEY as G, type IRaycastOptions as H, type IGame as I, type IScenePickerOptions as J, type IThreeNativeAudioConfig as K, type IThreeNativeAudioLoop as L, type IThreeNativeAudioOverride as M, type IThreeNativeAudioSpectrum as N, type IThreeNativeBootSplash as O, type IThreeNativeConfig as P, type IThreeNativeIconVariants as Q, type IThreeNativeLodConfig as R, type IThreeNativeLodGenerationConfig as S, type IThreeNativeLodOverride as T, type IThreeNativeLodRuntimeConfig as U, type IThreeNativeTexturesConfig as V, type ITweenOptions as W, type IWarmUpCacheOptions as X, type IWarmUpObservation as Y, type IWarmUpOptions as Z, type IWarmUpProgress as _, type IGamePluginRuntime as a, type IWarmUpReport as a0, type InputBindings as a1, InputMap as a2, type InputPlatformSource as a3, type PointerEvent3DListener as a4, type PointerEvent3DType as a5, PointerEvents3D as a6, Scene as a7, type SceneFrame as a8, ScenePicker as a9, type ScheduleHandle as aa, Scheduler as ab, type ThreeNativeBackgroundMode as ac, type ThreeNativeLodMinTrianglesScope as ad, type ThreeNativeLodPreset as ae, type ThreeNativeOrientation as af, type ThreeNativeUiRenderer as ag, type WarmUpCacheStatus as ah, type WarmUpObservationStatus as ai, afterPhysics as aj, captureMouse as ak, createRandom as al, defineGame as am, warmUpScene as an, type IGamePluginHooks as b, GEOMETRY_CAPTURE_DEFAULT_LIMIT as c, GEOMETRY_CAPTURE_MAX_LIMIT as d, GEOMETRY_CAPTURE_SORTS as e, GEOMETRY_CAPTURE_TIMEOUT_MS as f, GEOMETRY_CAPTURE_WALK_CAP as g, type GeometryCaptureSort as h, type ICtx as i, type IGameObservationContribution as j, type IGameObservationSampleRequest as k, type IGamePlatformSource as l, type IGeometryCaptureAsset as m, type IGeometryCaptureMesh as n, type IGeometryCapturePass as o, type IGeometryCaptureReport as p, type IGeometryCaptureRequest as q, type IGeometryCaptureRow as r, type IInputAction as s, type IInputGamepad as t, type IPointerDragHandle as u, type IPointerEvent3D as v, type IPointerEvents3D as w, type IPointerEvents3DOptions as x, type IPointerEvents3DPicker as y, type IPointerState as z };
1749
+ export { type IWarmUpRenderer as $, type AfterPhysicsCallback as A, type IRandom as B, type ContextMenuPolicy as C, type IRawInputPointer as D, type IRawInputPointerEdge as E, type IRawInputState as F, GEOMETRY_ASSET_KEY as G, type IRaycastOptions as H, type IGame as I, type IScenePickerOptions as J, type IThreeNativeAudioConfig as K, type IThreeNativeAudioLoop as L, type IThreeNativeAudioOverride as M, type IThreeNativeAudioSpectrum as N, type IThreeNativeBootSplash as O, type IThreeNativeConfig as P, type IThreeNativeIconVariants as Q, type IThreeNativeLodConfig as R, type IThreeNativeLodGenerationConfig as S, type IThreeNativeLodOverride as T, type IThreeNativeLodRuntimeConfig as U, type IThreeNativeTexturesConfig as V, type ITweenOptions as W, type IWarmUpCacheOptions as X, type IWarmUpObservation as Y, type IWarmUpOptions as Z, type IWarmUpProgress as _, type IGamePluginHooks as a, type IWarmUpReport as a0, type InputBindings as a1, InputMap as a2, type InputPlatformSource as a3, type PointerEvent3DListener as a4, type PointerEvent3DType as a5, PointerEvents3D as a6, Scene as a7, type SceneFrame as a8, ScenePicker as a9, type ScheduleHandle as aa, Scheduler as ab, type ThreeNativeBackgroundMode as ac, type ThreeNativeLodMinTrianglesScope as ad, type ThreeNativeLodPreset as ae, type ThreeNativeOrientation as af, type ThreeNativeUiRenderer as ag, type WarmUpCacheStatus as ah, type WarmUpObservationStatus as ai, afterPhysics as aj, captureMouse as ak, createRandom as al, defineGame as am, warmUpScene as an, type IGamePluginRuntime as b, GEOMETRY_CAPTURE_DEFAULT_LIMIT as c, GEOMETRY_CAPTURE_MAX_LIMIT as d, GEOMETRY_CAPTURE_SORTS as e, GEOMETRY_CAPTURE_TIMEOUT_MS as f, GEOMETRY_CAPTURE_WALK_CAP as g, type GeometryCaptureSort as h, type ICtx as i, type IGameObservationContribution as j, type IGameObservationSampleRequest as k, type IGamePlatformSource as l, type IGeometryCaptureAsset as m, type IGeometryCaptureMesh as n, type IGeometryCapturePass as o, type IGeometryCaptureReport as p, type IGeometryCaptureRequest as q, type IGeometryCaptureRow as r, type IInputAction as s, type IInputGamepad as t, type IPointerDragHandle as u, type IPointerEvent3D as v, type IPointerEvents3D as w, type IPointerEvents3DOptions as x, type IPointerEvents3DPicker as y, type IPointerState as z };
package/dist/hot.d.ts CHANGED
@@ -1,10 +1,10 @@
1
- import { a as audioRuntimeSnapshot } from './audio-7i3Xl0l3.js';
2
- import { I as IGame } from './game-CljaDv4D.js';
1
+ import { a as audioRuntimeSnapshot } from './audio-DIJE5HTr.js';
2
+ import { I as IGame } from './game-Bj8G1wmD.js';
3
3
  import 'three';
4
4
  import './assets-CqvE429w.js';
5
- import './renderer-CfsS2hxi.js';
5
+ import './renderer-9yEo9hPa.js';
6
6
  import 'three/webgpu';
7
- import './canvas-layer-DDmC_VVF.js';
7
+ import './canvas-layer-C1-5CviZ.js';
8
8
  import 'zustand/vanilla';
9
9
 
10
10
  interface IHotDiagnostics {