@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
@@ -1,5 +1,13 @@
1
- import { Object3D, Camera } from 'three';
2
- import { I as IRendererLike } from './renderer-CfsS2hxi.js';
1
+ import { Camera, Object3D, Mesh, BufferGeometry } from 'three';
2
+ import { I as IRendererLike, a as IFrameBudgetWindow, b as IFrameBudgetSimulation } from './renderer-9yEo9hPa.js';
3
+
4
+ /** One simulation that can yield its compute work. */
5
+ interface IBudgetCandidate {
6
+ /** Return projected size, or undefined when this simulation costs nothing. */
7
+ significance(camera: Camera): number | undefined;
8
+ /** Pause or resume without changing the simulation's buffers. */
9
+ yield(yielded: boolean): void;
10
+ }
3
11
 
4
12
  /**
5
13
  * The lifecycle contract for a game-owned GPU simulation.
@@ -17,6 +25,14 @@ interface IComputeDriven {
17
25
  * existing behavior of consumers whose simulation is intentionally tied to presentation.
18
26
  */
19
27
  readonly processCadence?: "fixed" | "render";
28
+ /** Render admission needed to settle a startup hold, after initial compilation. */
29
+ readonly processDuringStartup?: boolean;
30
+ /**
31
+ * Yield simulation work in order of projected size when measured GPU compute exceeds budget.
32
+ * @situation Let the render loop pause low-significance particle emitters under GPU pressure.
33
+ * @constraint Only live render-cadence objects participate; missing measurements never shed.
34
+ */
35
+ readonly budget?: IBudgetCandidate;
20
36
  /**
21
37
  * Dispatched once per fixed step, in scene-add order unless render cadence is declared.
22
38
  *
@@ -24,8 +40,11 @@ interface IComputeDriven {
24
40
  * the view — a streamed world narrowing its instanced windows to what the frustum covers — can do
25
41
  * it from the driver that runs every frame rather than from a draw three will not submit. An
26
42
  * implementation that does not need it simply declares one parameter.
43
+ *
44
+ * `covered` is true while the startup cover hides the world and readiness is still pending, so
45
+ * a streamed world may spend more of the frame admitting the spawn it is waiting on.
27
46
  */
28
- process(renderer: IRendererLike, camera?: Camera): void;
47
+ process(renderer: IRendererLike, camera?: Camera, covered?: boolean, view?: undefined, simulatedSeconds?: number): void;
29
48
  detach(): void;
30
49
  readonly released: boolean;
31
50
  }
@@ -41,11 +60,13 @@ declare class ComputeDrivenRegistry {
41
60
  get warmupNodes(): readonly unknown[];
42
61
  /** Dispatch fixed-step objects once; detached scene children are released before dispatch. */
43
62
  process(renderer: IRendererLike): void;
63
+ /** Forward a measured frame window to the particle budget coordinator. */
64
+ observeBudget(window: Pick<IFrameBudgetWindow, "frames" | "presented" | "gpuMs" | "gpuCompute" | "targetFps" | "simulatedSeconds">): void;
44
65
  /**
45
66
  * Dispatch render-cadence objects once with the frame's render camera; detached scene children are
46
67
  * released before dispatch.
47
68
  */
48
- processRender(renderer: IRendererLike, camera?: Camera): void;
69
+ processRender(renderer: IRendererLike, camera?: Camera, startupOnly?: boolean, simulation?: IFrameBudgetSimulation): void;
49
70
  /** Release every registered object, continuing after a failure so no resource is stranded. */
50
71
  clear(): void;
51
72
  }
@@ -119,4 +140,58 @@ declare class GPUReadback {
119
140
  dispose(): void;
120
141
  }
121
142
 
122
- export { ComputeDrivenRegistry as C, GPUReadback as G, type IComputeDriven as I, type IGPUReadbackSample as a, type IGPUReadbackOptions as b };
143
+ interface ILodView {
144
+ readonly camera: Camera;
145
+ /** Drawing-buffer height in actual raster pixels; a CSS height is the wrong number. */
146
+ readonly viewportHeight: number;
147
+ /**
148
+ * Conservative nearest view-space depth of the object's bounding sphere, in world units. A caller
149
+ * that has not measured the bounds passes the distance to the origin, which is never closer and
150
+ * therefore never over-refines.
151
+ */
152
+ readonly depth: number;
153
+ /**
154
+ * True when the camera is at or inside the object's near plane, where a projected error has no
155
+ * meaning. The finest level is selected instead of dividing by ~zero.
156
+ */
157
+ readonly degenerate: boolean;
158
+ /**
159
+ * A view that must not drop below the finest level regardless of budget. Recorded as data so a
160
+ * pass-local caller can prove it honoured the rule.
161
+ */
162
+ readonly finest?: boolean;
163
+ }
164
+ /**
165
+ * Pixels a one-world-unit error at `depth` covers, for this camera and viewport.
166
+ *
167
+ * Perspective divides the projected scale by the depth; orthographic has no depth term and uses the
168
+ * frustum height instead. A non-positive depth or an unprojectable camera throws rather than
169
+ * returning a plausible-looking wrong scale.
170
+ */
171
+ declare function lodPixelScale(camera: Camera, viewportHeight: number, depth: number): number;
172
+ /** Default screen-space error budget, in pixels, when no resolved policy reaches the loader. */
173
+ declare const DISCRETE_LOD_DEFAULT_ERROR_PIXELS = 1;
174
+ /** Default coarsen hysteresis when no resolved policy reaches the loader. */
175
+ declare const DISCRETE_LOD_DEFAULT_HYSTERESIS = 0.15;
176
+ /** Resolved runtime policy the loader stamps onto a controller, from the manifest. */
177
+ interface IModelLodPolicy {
178
+ readonly hysteresis: number;
179
+ readonly maxPixelError: number;
180
+ }
181
+ /** The LOD0 geometry of a mesh under a discrete chain, or the mesh's own geometry otherwise. */
182
+ declare function baseGeometryOf(mesh: Mesh): BufferGeometry;
183
+ /**
184
+ * Takes every discrete-LOD mesh under `root` through this frame's selection.
185
+ *
186
+ * The engine calls this itself, once a frame, after matrices are synced and before the render.
187
+ * Multi-view callers that need the finest level across passes use {@link selectLodLevel} directly;
188
+ * this entry point selects for the one camera it is handed — which is the main view, and is at
189
+ * least as fine as a shadow pass of lower resolution needs.
190
+ *
191
+ * @returns triangles the managed meshes will submit this frame.
192
+ */
193
+ declare function updateModelLods(root: {
194
+ traverse(callback: (object: object) => void): void;
195
+ }, camera: Camera, viewportHeight: number): number;
196
+
197
+ export { ComputeDrivenRegistry as C, DISCRETE_LOD_DEFAULT_ERROR_PIXELS as D, GPUReadback as G, type IComputeDriven as I, type ILodView as a, type IModelLodPolicy as b, type IGPUReadbackSample as c, type IBudgetCandidate as d, DISCRETE_LOD_DEFAULT_HYSTERESIS as e, type IGPUReadbackOptions as f, baseGeometryOf as g, lodPixelScale as l, updateModelLods as u };
@@ -1,10 +1,11 @@
1
1
  import { JsonValue, JsonPrimitive } from '@threenative/playtest/protocol';
2
- import { b as IGamePluginHooks } from './game-CljaDv4D.js';
2
+ export { PLAYTEST_CLOCK_GLOBAL } from '@threenative/playtest/protocol';
3
+ import { a as IGamePluginHooks } from './game-Jz4Fdoeb.js';
3
4
  import './assets-CqvE429w.js';
4
5
  import 'three';
5
- import './renderer-CfsS2hxi.js';
6
+ import './renderer-9yEo9hPa.js';
6
7
  import 'three/webgpu';
7
- import './canvas-layer-DDmC_VVF.js';
8
+ import './canvas-layer-C1-5CviZ.js';
8
9
  import 'zustand/vanilla';
9
10
 
10
11
  /**
@@ -31,12 +32,7 @@ declare const PLAYTEST_ATTACH_TIMEOUT_MS = 30000;
31
32
  */
32
33
  /** The global a playtest runner sets before the page loads, so a game can tell one is coming. */
33
34
  declare const PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
34
- /**
35
- * The clock a consumer asks this game to run on, named in the protocol's own vocabulary. Set before
36
- * the game module evaluates — a production profile does it in the instrumentation it injects ahead
37
- * of the bundle, on the browser and on native alike.
38
- */
39
- declare const PLAYTEST_CLOCK_GLOBAL = "__THREENATIVE_PLAYTEST_CLOCK__";
35
+
40
36
  interface IPlaytestOptions {
41
37
  readonly events?: () => JsonValue[];
42
38
  /**
@@ -69,4 +65,4 @@ interface IPlaytestTransition {
69
65
  to: JsonPrimitive;
70
66
  }
71
67
 
72
- export { type IPlaytestOptions, type IPlaytestTransition, PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_CLOCK_GLOBAL, PLAYTEST_RUNNER_EXPECTED_GLOBAL, PLAYTEST_TRANSITION_LOG_LIMIT, playtest };
68
+ export { type IPlaytestOptions, type IPlaytestTransition, PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, PLAYTEST_TRANSITION_LOG_LIMIT, playtest };
package/dist/playtest.js CHANGED
@@ -1,4 +1,5 @@
1
- import { assertJsonSafe, PLAYTEST_PROTOCOL_LIMITS } from '@threenative/playtest/protocol';
1
+ import { requestedPlaytestClockMode, assertJsonSafe, PLAYTEST_PROTOCOL_LIMITS } from '@threenative/playtest/protocol';
2
+ export { PLAYTEST_CLOCK_GLOBAL } from '@threenative/playtest/protocol';
2
3
  import { installThreePlaytestBridge } from '@threenative/playtest/three';
3
4
  import { Sphere, Vector3, Object3D } from 'three';
4
5
 
@@ -42,7 +43,7 @@ new Vector3();
42
43
  new Vector3();
43
44
 
44
45
  // src/version.ts
45
- var CORE_VERSION = "0.3.4";
46
+ var CORE_VERSION = "0.3.6";
46
47
 
47
48
  // src/pipeline-census.ts
48
49
  var PIPELINE_CENSUS_CAPABILITY = "runtime.pipelineCensus";
@@ -92,7 +93,7 @@ function playtest(options = {}) {
92
93
  setup: async (ctx, runtime) => {
93
94
  readTick = runtime?.tick;
94
95
  const seed = runtime?.seed ?? null;
95
- const clockMode = requestedClockMode();
96
+ let clockMode = requestedPlaytestClockMode() ?? (runtime === void 0 ? void 0 : "fixed-step");
96
97
  const wallClock = clockMode === "wall-clock";
97
98
  const replayRuntime = runtime?.seed === null || runtime?.seed === void 0 ? void 0 : {
98
99
  agent: currentAgent,
@@ -101,7 +102,9 @@ function playtest(options = {}) {
101
102
  rapier: runtime.rapier ?? null,
102
103
  step: runtime.step
103
104
  };
104
- const installation = installThreePlaytestBridge({
105
+ const clockRuntime = runtime;
106
+ const liveAdvance = runtime === void 0 ? void 0 : wallClockAdvance(runtime);
107
+ const bridgeOptions = {
105
108
  camera: ctx.camera,
106
109
  ...clockMode === void 0 ? {} : { clockMode },
107
110
  entities: () => bridgeEntities(ctx),
@@ -109,10 +112,23 @@ function playtest(options = {}) {
109
112
  // The live clock has to be driven by the host's own frame pump, so a live run's `advance`
110
113
  // waits the span of wall time the count names and reports the ticks that pump ran.
111
114
  ...runtime === void 0 ? {} : {
112
- fixedStep: wallClock ? wallClockAdvance(runtime) : runtime.fixedStep,
115
+ fixedStep: async (ticks, options2) => {
116
+ await runtime.sceneTransition?.();
117
+ if (clockMode === "wall-clock" && liveAdvance !== void 0)
118
+ return liveAdvance(ticks);
119
+ let ran = runtime.fixedStep(ticks, options2);
120
+ while (ran > 0 && ran < ticks) {
121
+ await runtime.sceneTransition?.();
122
+ ran += runtime.fixedStep(ticks - ran, options2);
123
+ }
124
+ return ran;
125
+ },
113
126
  tick: runtime.tick
114
127
  },
115
128
  ...runtime?.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: runtime.runtimeDiagnosticsSeries },
129
+ // A driven native loop presents nothing between ticks; the render-only operation lets a
130
+ // desktop screenshot draw the standing world without spending a simulation step.
131
+ ...runtime?.renderCurrent === void 0 ? {} : { renderCurrent: () => runtime.renderCurrent?.() },
116
132
  ...options.events === void 0 ? {} : { events: options.events },
117
133
  gameplay: () => gameplayObservations(ctx, contactHistory, seed, replayRuntime, watcher),
118
134
  gameplayChannels: () => gameplayChannels(),
@@ -130,7 +146,7 @@ function playtest(options = {}) {
130
146
  velocity: { ...observation.velocity }
131
147
  };
132
148
  },
133
- resources: stateResources(ctx),
149
+ resources: stateResources(ctx, runtime),
134
150
  scene: ctx.scene,
135
151
  // A runner advances ticks far faster than a launch completes, and compute dispatch and
136
152
  // the first world present are both held behind an opaque loading layer. Published so the
@@ -144,7 +160,28 @@ function playtest(options = {}) {
144
160
  // of reading it off a console marker after the fact.
145
161
  ...runtime?.startupTimeline === void 0 ? {} : { timeline: runtime.startupTimeline() }
146
162
  })
147
- });
163
+ };
164
+ const installation = installThreePlaytestBridge(bridgeOptions);
165
+ let clockDisposed = false;
166
+ const clockControl = {
167
+ _clockEpoch: 0,
168
+ _setClockMode: (mode) => {
169
+ if (clockDisposed) throw new Error("Playtest clock is disposed.");
170
+ if (mode !== "fixed-step" && mode !== "wall-clock")
171
+ throw new Error("Unknown clock mode.");
172
+ clockRuntime?._setClockMode?.(mode);
173
+ if (mode !== clockMode) clockControl._clockEpoch += 1;
174
+ clockMode = mode;
175
+ bridgeOptions.clockMode = mode;
176
+ return { mode, tick: runtime?.tick(), epoch: clockControl._clockEpoch };
177
+ }
178
+ };
179
+ if (clockRuntime?._setClockMode !== void 0) {
180
+ Object.assign(installation.bridge, { _setClockMode: clockControl._setClockMode });
181
+ Object.defineProperty(installation.bridge, "_clockEpoch", {
182
+ get: () => clockControl._clockEpoch
183
+ });
184
+ }
148
185
  const pipelineCensus = runtime?.pipelineCensus;
149
186
  if (runtime !== void 0 && pipelineCensus !== void 0) {
150
187
  disposePipelineCensus = runtime.observations.contribute({
@@ -169,6 +206,9 @@ function playtest(options = {}) {
169
206
  dispose = installation.dispose;
170
207
  attached = holdUntilAttached(installation.bridge, options, () => startSceneEntered);
171
208
  const cleanup = () => {
209
+ if (!clockDisposed && clockRuntime?._setClockMode !== void 0)
210
+ clockControl._setClockMode("fixed-step");
211
+ clockDisposed = true;
172
212
  disposePipelineCensus?.();
173
213
  disposePipelineCensus = void 0;
174
214
  disposeGeometryCapture?.();
@@ -198,24 +238,15 @@ function playtest(options = {}) {
198
238
  }
199
239
  var PLAYTEST_ATTACH_TIMEOUT_MS = 3e4;
200
240
  var PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
201
- var PLAYTEST_CLOCK_GLOBAL = "__THREENATIVE_PLAYTEST_CLOCK__";
202
- function requestedClockMode() {
203
- const requested = globalThis[PLAYTEST_CLOCK_GLOBAL];
204
- if (requested === void 0) return void 0;
205
- if (requested === "wall-clock") return "wall-clock";
206
- throw new Error(
207
- `TN_PLAYTEST_CLOCK_UNSUPPORTED: '${PLAYTEST_CLOCK_GLOBAL}' is ${JSON.stringify(requested)}; this protocol knows 'wall-clock' and nothing else.`
208
- );
209
- }
210
- var WALL_CLOCK_PUMP_STEPS = 4;
241
+ var WALL_CLOCK_PUMP_TIMEOUT_MS = 1e3;
211
242
  var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
212
243
  function wallClockAdvance(runtime) {
213
244
  const stepMs = runtime.step * 1e3;
214
245
  return async (ticks) => {
215
246
  const before = runtime.tick();
216
247
  await sleep(ticks * stepMs);
217
- for (let waited = 0; waited < WALL_CLOCK_PUMP_STEPS && runtime.tick() === before; waited += 1)
218
- await sleep(stepMs / 2);
248
+ const deadline = Date.now() + WALL_CLOCK_PUMP_TIMEOUT_MS;
249
+ while (runtime.tick() === before && Date.now() < deadline) await sleep(stepMs / 2);
219
250
  return runtime.tick() - before;
220
251
  };
221
252
  }
@@ -261,8 +292,9 @@ function holdUntilAttached(bridge, options, startSceneEntered) {
261
292
  if (applySetup !== void 0) {
262
293
  bridge.applySetup = async (request) => {
263
294
  try {
264
- await applySetup(request);
295
+ const confirmation = await applySetup(request);
265
296
  release();
297
+ return confirmation;
266
298
  } catch (error) {
267
299
  fail(error);
268
300
  throw error;
@@ -392,7 +424,7 @@ function drainContacts(ctx, history, tick) {
392
424
  for (const value of objectGraphValues(registered))
393
425
  if (!idsByEntity.has(value)) idsByEntity.set(value, id);
394
426
  });
395
- ctx.entities.forEach((id, registered) => {
427
+ ctx.entities.forEach((_id, registered) => {
396
428
  for (const source of entitySources(registered)) {
397
429
  for (const event of source.drainContacts()) {
398
430
  const entity = idsByEntity.get(event.body);
@@ -490,7 +522,7 @@ function componentObservations(snapshot) {
490
522
  }
491
523
  return components;
492
524
  }
493
- function stateResources(ctx) {
525
+ function stateResources(ctx, runtime) {
494
526
  return {
495
527
  read: () => {
496
528
  ctx.state.flush();
@@ -505,7 +537,8 @@ function stateResources(ctx) {
505
537
  // Where every asset was actually served from, on every target and not only in a browser
506
538
  // console log: a game whose manifest never loaded runs on the uncompiled source directory
507
539
  // and looks healthy, and without this nothing observable says so.
508
- ["assets", assetResolutions(ctx.assets)]
540
+ ["assets", assetResolutions(ctx.assets)],
541
+ ...runtime?.frameCounts === void 0 ? [] : [["__threenativeFrameCounts", runtime.frameCounts()]]
509
542
  ]);
510
543
  }
511
544
  };
@@ -534,4 +567,4 @@ function cloneJsonValue(value) {
534
567
  return value;
535
568
  }
536
569
 
537
- export { PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_CLOCK_GLOBAL, PLAYTEST_RUNNER_EXPECTED_GLOBAL, PLAYTEST_TRANSITION_LOG_LIMIT, playtest };
570
+ export { PLAYTEST_ATTACH_TIMEOUT_MS, PLAYTEST_RUNNER_EXPECTED_GLOBAL, PLAYTEST_TRANSITION_LOG_LIMIT, playtest };
@@ -0,0 +1,62 @@
1
+ import { ReactNode } from 'react';
2
+
3
+ /**
4
+ * A React host that renders standard JSX to a native CSS engine, with no DOM in the process.
5
+ *
6
+ * The vocabulary is the HTML a game already writes: `div`, `section`, `button`, `className`,
7
+ * `style`, `data-*`, `aria-*`. That is the whole point — the same component can mount through
8
+ * `react-dom` on the web and through here on a phone, so a game does not keep two UI trees.
9
+ *
10
+ * What crosses the UI bridge is not a tree but a stream of mutations, one frame per React commit,
11
+ * exactly what `packages/runtime-native/native/css-ui` replays. This half owns no layout, no style
12
+ * resolution and no Tailwind knowledge: a `class` attribute crosses byte-for-byte and the CSS engine
13
+ * decides what it means, which is the only arrangement in which `hover:bg-brand/80` behaves the
14
+ * same on a phone as in a browser. Nothing here imports `react-dom` or touches `document`.
15
+ *
16
+ * Fail closed: a tag the CSS engine cannot build throws naming it and the allowed list rather than
17
+ * mounting a subtree with a hole in it. Props outside the supported list — the tag list above, the
18
+ * pass-through and renamed attribute sets, the `on*` map and the supported style properties — are
19
+ * ignored rather than throwing, so a component shared with `react-dom` still mounts here.
20
+ */
21
+ /** The one frame type this host sends. The native CSS engine keys on it. */
22
+ declare const CSS_UI_MESSAGE = "tn:css";
23
+ /**
24
+ * Every host tag the native CSS engine can build. Closed on purpose: an unknown tag is a missing
25
+ * element, not a different-looking one, and a UI that quietly drops half its tree is the failure
26
+ * this refuses to have.
27
+ */
28
+ declare const CSS_UI_TAGS: readonly ["div", "section", "aside", "header", "footer", "main", "nav", "article", "h1", "h2", "h3", "h4", "h5", "h6", "p", "span", "button", "img", "ul", "ol", "li", "a", "label", "strong", "em", "b", "i", "small"];
29
+ interface ICssUiRootOptions {
30
+ /** The realm the bridge installs into. Defaults to `globalThis`; injected by tests and by hosts. */
31
+ readonly scope?: Record<string, unknown>;
32
+ /**
33
+ * Called with any error React could not recover from — an unsupported tag, an unresolvable prop.
34
+ * The default logs it; nothing swallows it, because a UI that silently lost half its tree and a
35
+ * UI that was never asked for both look like an empty screen.
36
+ */
37
+ readonly onError?: (error: Error) => void;
38
+ }
39
+ interface ICssUiRoot {
40
+ /** Mount or update the tree. Synchronous, so the caller can assert on the frame immediately. */
41
+ render(element: ReactNode): void;
42
+ /** Unmount the tree, publish the removal, and stop listening to the bridge. */
43
+ dispose(): void;
44
+ /** How many mutation ops this root has sent. For budgets and tests. */
45
+ readonly opCount: number;
46
+ /** How many frames this root has posted. A commit that changed nothing posts nothing. */
47
+ readonly postCount: number;
48
+ }
49
+ /**
50
+ * Mount React into a native CSS engine.
51
+ *
52
+ * @situation mount a React HUD on the desktop host with no DOM in the runtime
53
+ * @situation write one React component and run it on the web and on the desktop host
54
+ * @constraint desktop only, and the game host must be built with the CSS backend (`TN_ENABLE_CSS_UI=1`); Android, iOS and web phones render a React HUD in a web overlay instead
55
+ * @constraint import `react`, never `react-dom`, from a native entry
56
+ * @constraint styling is CSS resolved by the native engine; JS only mirrors the element tree
57
+ * @example const root = createCssUiRoot();
58
+ * @example root.render(createElement("section", { className: "fixed inset-0 bg-zinc-900/90" }, "READY"));
59
+ */
60
+ declare function createCssUiRoot(options?: ICssUiRootOptions): ICssUiRoot;
61
+
62
+ export { CSS_UI_MESSAGE, CSS_UI_TAGS, type ICssUiRoot, type ICssUiRootOptions, createCssUiRoot };