@threenative/core 0.3.3 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -0,0 +1,197 @@
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
+ }
11
+
12
+ /**
13
+ * The lifecycle contract for a game-owned GPU simulation.
14
+ *
15
+ * A compute-driven object owns its kernels, buffers, and appearance. The framework only attaches
16
+ * the active renderer, warms the kernels before the world is shown, dispatches process calls at
17
+ * the object's declared cadence, and releases the object when its scene ends.
18
+ */
19
+ interface IComputeDriven {
20
+ /** Kernels to compile before the world is shown. Read once, at attach. */
21
+ readonly warmupNodes: readonly unknown[];
22
+ attachRenderer(renderer: IRendererLike): void;
23
+ /**
24
+ * The loop phase that dispatches `process`. Defaults to fixed-step; render cadence preserves the
25
+ * existing behavior of consumers whose simulation is intentionally tied to presentation.
26
+ */
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;
36
+ /**
37
+ * Dispatched once per fixed step, in scene-add order unless render cadence is declared.
38
+ *
39
+ * `camera` is the frame's render camera, handed over at render cadence so a consumer that culls by
40
+ * the view — a streamed world narrowing its instanced windows to what the frustum covers — can do
41
+ * it from the driver that runs every frame rather than from a draw three will not submit. An
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.
46
+ */
47
+ process(renderer: IRendererLike, camera?: Camera, covered?: boolean, view?: undefined, simulatedSeconds?: number): void;
48
+ detach(): void;
49
+ readonly released: boolean;
50
+ }
51
+ /** The ordered registry used by the game loop for all compute-driven scene objects. */
52
+ declare class ComputeDrivenRegistry {
53
+ #private;
54
+ get size(): number;
55
+ /** Attach and remember one object. Re-adding the same object is idempotent. */
56
+ add(object: Object3D & IComputeDriven, renderer: IRendererLike): void;
57
+ /** Release one object without disturbing the order of the remaining objects. */
58
+ remove(driven: IComputeDriven): void;
59
+ /** Kernels in the same order as their objects were added to the scene. */
60
+ get warmupNodes(): readonly unknown[];
61
+ /** Dispatch fixed-step objects once; detached scene children are released before dispatch. */
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;
65
+ /**
66
+ * Dispatch render-cadence objects once with the frame's render camera; detached scene children are
67
+ * released before dispatch.
68
+ */
69
+ processRender(renderer: IRendererLike, camera?: Camera, startupOnly?: boolean, simulation?: IFrameBudgetSimulation): void;
70
+ /** Release every registered object, continuing after a failure so no resource is stranded. */
71
+ clear(): void;
72
+ }
73
+
74
+ interface IGPUReadbackOptions {
75
+ /** The GPU storage attribute to copy — a TSL storage node's `.value`. */
76
+ readonly attribute: unknown;
77
+ /**
78
+ * Frames between readback requests. `1` asks every frame; larger values throttle.
79
+ *
80
+ * A copy off the GPU costs a queue submission and a mapped buffer, so a game reading a field it
81
+ * only consults for physics asks for it every few frames and pays the staleness instead.
82
+ */
83
+ readonly everyFrames: number;
84
+ }
85
+ /** A landed copy of GPU memory, with the age of the frame that produced it. */
86
+ interface IGPUReadbackSample {
87
+ readonly data: Float32Array;
88
+ /**
89
+ * Frames between the frame whose GPU state these bytes hold and the frame reading them.
90
+ *
91
+ * This is the number a caller must not be allowed to ignore. A buoyancy solver that treats a
92
+ * 4-frame-old surface as this frame's surface floats a hull through the water it is drawn on,
93
+ * and nothing in the frame says so.
94
+ */
95
+ readonly staleFrames: number;
96
+ }
97
+ /**
98
+ * A throttled, fire-and-forget copy of a GPU buffer into CPU memory.
99
+ *
100
+ * Every sample it hands back carries its own age. That is the whole point: the copy is
101
+ * asynchronous, so the bytes are always some frames behind the GPU, and a class that hid that
102
+ * would let a caller mistake stale data for live data with no way to find out.
103
+ *
104
+ * `request()` never awaits and never blocks the frame. One copy is in flight at a time; requests
105
+ * made while one is pending are dropped rather than queued, because a backlog of copies of a field
106
+ * that has already moved on is latency with no information in it.
107
+ */
108
+ declare class GPUReadback {
109
+ #private;
110
+ readonly everyFrames: number;
111
+ constructor(options: IGPUReadbackOptions);
112
+ get released(): boolean;
113
+ /** True while a copy is in flight. A game that wants to pace its own work can read it. */
114
+ get pending(): boolean;
115
+ /** The newest landed bytes, or `undefined` before the first copy lands. */
116
+ get data(): Float32Array | undefined;
117
+ /**
118
+ * How many frames old the landed bytes are.
119
+ *
120
+ * Before anything has landed this is the number of frames since construction, which grows
121
+ * without bound on purpose: "no data yet" and "data from frame zero" must not read the same.
122
+ */
123
+ get staleFrames(): number;
124
+ /** The newest bytes with their age attached, or `undefined` before the first copy lands. */
125
+ get sample(): IGPUReadbackSample | undefined;
126
+ /** Requests, landings and failures, for a report that has to say why a sample is old. */
127
+ get stats(): {
128
+ readonly requests: number;
129
+ readonly lands: number;
130
+ readonly failures: number;
131
+ };
132
+ /**
133
+ * Advances the frame clock and starts a copy when the throttle allows one.
134
+ *
135
+ * Safe to call every frame. It returns before the GPU has answered — awaiting it is the one
136
+ * thing that would turn this class into the stall it exists to avoid.
137
+ */
138
+ request(renderer: IRendererLike): void;
139
+ /** Drops the attribute reference and the landed bytes. Further requests throw. */
140
+ dispose(): void;
141
+ }
142
+
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-D_6r-k4Y.js';
3
- import './assets-CYKk2WTu.js';
2
+ export { PLAYTEST_CLOCK_GLOBAL } from '@threenative/playtest/protocol';
3
+ import { a as IGamePluginHooks } from './game-Bj8G1wmD.js';
4
+ import './assets-CqvE429w.js';
4
5
  import 'three';
5
- import './renderer-Cy4qeBOA.js';
6
+ import './renderer-9yEo9hPa.js';
6
7
  import 'three/webgpu';
7
- import './canvas-layer-C1SnMoJ-.js';
8
+ import './canvas-layer-C1-5CviZ.js';
8
9
  import 'zustand/vanilla';
9
10
 
10
11
  /**
@@ -31,6 +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__";
35
+
34
36
  interface IPlaytestOptions {
35
37
  readonly events?: () => JsonValue[];
36
38
  /**
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.3";
46
+ var CORE_VERSION = "0.3.5";
46
47
 
47
48
  // src/pipeline-census.ts
48
49
  var PIPELINE_CENSUS_CAPABILITY = "runtime.pipelineCensus";
@@ -92,6 +93,8 @@ function playtest(options = {}) {
92
93
  setup: async (ctx, runtime) => {
93
94
  readTick = runtime?.tick;
94
95
  const seed = runtime?.seed ?? null;
96
+ let clockMode = requestedPlaytestClockMode() ?? (runtime === void 0 ? void 0 : "fixed-step");
97
+ const wallClock = clockMode === "wall-clock";
95
98
  const replayRuntime = runtime?.seed === null || runtime?.seed === void 0 ? void 0 : {
96
99
  agent: currentAgent,
97
100
  core: CORE_VERSION,
@@ -99,12 +102,23 @@ function playtest(options = {}) {
99
102
  rapier: runtime.rapier ?? null,
100
103
  step: runtime.step
101
104
  };
102
- const installation = installThreePlaytestBridge({
105
+ const clockRuntime = runtime;
106
+ const liveAdvance = runtime === void 0 ? void 0 : wallClockAdvance(runtime);
107
+ const bridgeOptions = {
103
108
  camera: ctx.camera,
109
+ ...clockMode === void 0 ? {} : { clockMode },
104
110
  entities: () => bridgeEntities(ctx),
105
111
  components: () => componentObservations(ctx.entities.snapshot()),
106
- ...runtime === void 0 ? {} : { fixedStep: runtime.fixedStep, tick: runtime.tick },
112
+ // The live clock has to be driven by the host's own frame pump, so a live run's `advance`
113
+ // waits the span of wall time the count names and reports the ticks that pump ran.
114
+ ...runtime === void 0 ? {} : {
115
+ fixedStep: (ticks, options2) => clockMode === "wall-clock" && liveAdvance !== void 0 ? liveAdvance(ticks) : runtime.fixedStep(ticks, options2),
116
+ tick: runtime.tick
117
+ },
107
118
  ...runtime?.runtimeDiagnosticsSeries === void 0 ? {} : { runtimeDiagnosticsSeries: runtime.runtimeDiagnosticsSeries },
119
+ // A driven native loop presents nothing between ticks; the render-only operation lets a
120
+ // desktop screenshot draw the standing world without spending a simulation step.
121
+ ...runtime?.renderCurrent === void 0 ? {} : { renderCurrent: () => runtime.renderCurrent?.() },
108
122
  ...options.events === void 0 ? {} : { events: options.events },
109
123
  gameplay: () => gameplayObservations(ctx, contactHistory, seed, replayRuntime, watcher),
110
124
  gameplayChannels: () => gameplayChannels(),
@@ -122,7 +136,7 @@ function playtest(options = {}) {
122
136
  velocity: { ...observation.velocity }
123
137
  };
124
138
  },
125
- resources: stateResources(ctx),
139
+ resources: stateResources(ctx, runtime),
126
140
  scene: ctx.scene,
127
141
  // A runner advances ticks far faster than a launch completes, and compute dispatch and
128
142
  // the first world present are both held behind an opaque loading layer. Published so the
@@ -136,7 +150,28 @@ function playtest(options = {}) {
136
150
  // of reading it off a console marker after the fact.
137
151
  ...runtime?.startupTimeline === void 0 ? {} : { timeline: runtime.startupTimeline() }
138
152
  })
139
- });
153
+ };
154
+ const installation = installThreePlaytestBridge(bridgeOptions);
155
+ let clockDisposed = false;
156
+ const clockControl = {
157
+ _clockEpoch: 0,
158
+ _setClockMode: (mode) => {
159
+ if (clockDisposed) throw new Error("Playtest clock is disposed.");
160
+ if (mode !== "fixed-step" && mode !== "wall-clock")
161
+ throw new Error("Unknown clock mode.");
162
+ clockRuntime?._setClockMode?.(mode);
163
+ if (mode !== clockMode) clockControl._clockEpoch += 1;
164
+ clockMode = mode;
165
+ bridgeOptions.clockMode = mode;
166
+ return { mode, tick: runtime?.tick(), epoch: clockControl._clockEpoch };
167
+ }
168
+ };
169
+ if (clockRuntime?._setClockMode !== void 0) {
170
+ Object.assign(installation.bridge, { _setClockMode: clockControl._setClockMode });
171
+ Object.defineProperty(installation.bridge, "_clockEpoch", {
172
+ get: () => clockControl._clockEpoch
173
+ });
174
+ }
140
175
  const pipelineCensus = runtime?.pipelineCensus;
141
176
  if (runtime !== void 0 && pipelineCensus !== void 0) {
142
177
  disposePipelineCensus = runtime.observations.contribute({
@@ -154,10 +189,16 @@ function playtest(options = {}) {
154
189
  });
155
190
  }
156
191
  installRuntimeChannels(installation.bridge, runtime);
157
- if (runnerAnnounced()) runtime?.enableRuntimeDiagnostics?.();
192
+ if (runnerAnnounced()) {
193
+ runtime?.enableRuntimeDiagnostics?.();
194
+ if (!wallClock) runtime?.freezeClock?.();
195
+ }
158
196
  dispose = installation.dispose;
159
197
  attached = holdUntilAttached(installation.bridge, options, () => startSceneEntered);
160
198
  const cleanup = () => {
199
+ if (!clockDisposed && clockRuntime?._setClockMode !== void 0)
200
+ clockControl._setClockMode("fixed-step");
201
+ clockDisposed = true;
161
202
  disposePipelineCensus?.();
162
203
  disposePipelineCensus = void 0;
163
204
  disposeGeometryCapture?.();
@@ -187,6 +228,18 @@ function playtest(options = {}) {
187
228
  }
188
229
  var PLAYTEST_ATTACH_TIMEOUT_MS = 3e4;
189
230
  var PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
231
+ var WALL_CLOCK_PUMP_TIMEOUT_MS = 1e3;
232
+ var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
233
+ function wallClockAdvance(runtime) {
234
+ const stepMs = runtime.step * 1e3;
235
+ return async (ticks) => {
236
+ const before = runtime.tick();
237
+ await sleep(ticks * stepMs);
238
+ const deadline = Date.now() + WALL_CLOCK_PUMP_TIMEOUT_MS;
239
+ while (runtime.tick() === before && Date.now() < deadline) await sleep(stepMs / 2);
240
+ return runtime.tick() - before;
241
+ };
242
+ }
190
243
  function shouldHoldUntilAttached(options) {
191
244
  if (options.holdUntilAttached !== void 0) return options.holdUntilAttached;
192
245
  return runnerAnnounced();
@@ -229,8 +282,9 @@ function holdUntilAttached(bridge, options, startSceneEntered) {
229
282
  if (applySetup !== void 0) {
230
283
  bridge.applySetup = async (request) => {
231
284
  try {
232
- await applySetup(request);
285
+ const confirmation = await applySetup(request);
233
286
  release();
287
+ return confirmation;
234
288
  } catch (error) {
235
289
  fail(error);
236
290
  throw error;
@@ -360,7 +414,7 @@ function drainContacts(ctx, history, tick) {
360
414
  for (const value of objectGraphValues(registered))
361
415
  if (!idsByEntity.has(value)) idsByEntity.set(value, id);
362
416
  });
363
- ctx.entities.forEach((id, registered) => {
417
+ ctx.entities.forEach((_id, registered) => {
364
418
  for (const source of entitySources(registered)) {
365
419
  for (const event of source.drainContacts()) {
366
420
  const entity = idsByEntity.get(event.body);
@@ -458,7 +512,7 @@ function componentObservations(snapshot) {
458
512
  }
459
513
  return components;
460
514
  }
461
- function stateResources(ctx) {
515
+ function stateResources(ctx, runtime) {
462
516
  return {
463
517
  read: () => {
464
518
  ctx.state.flush();
@@ -469,11 +523,30 @@ function stateResources(ctx) {
469
523
  // `state` is canonical. Keep `GameState` as a compatibility alias until published
470
524
  // scenarios have migrated, then remove the alias in a future breaking release.
471
525
  ["state", value],
472
- ["GameState", value]
526
+ ["GameState", value],
527
+ // Where every asset was actually served from, on every target and not only in a browser
528
+ // console log: a game whose manifest never loaded runs on the uncompiled source directory
529
+ // and looks healthy, and without this nothing observable says so.
530
+ ["assets", assetResolutions(ctx.assets)],
531
+ ...runtime?.frameCounts === void 0 ? [] : [["__threenativeFrameCounts", runtime.frameCounts()]]
473
532
  ]);
474
533
  }
475
534
  };
476
535
  }
536
+ function assetResolutions(assets) {
537
+ const nested = {};
538
+ for (const [logical, record] of assets.resolved) {
539
+ const parts = logical.split(".");
540
+ let node = nested;
541
+ for (const part of parts.slice(0, -1)) {
542
+ const child = node[part] ?? {};
543
+ node[part] = child;
544
+ node = child;
545
+ }
546
+ node[parts.at(-1) ?? logical] = { url: record.url, via: record.via };
547
+ }
548
+ return nested;
549
+ }
477
550
  function cloneJsonValue(value) {
478
551
  if (Array.isArray(value)) return value.map((item) => cloneJsonValue(item));
479
552
  if (typeof value === "object" && value !== null) {
@@ -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 };