@threenative/core 0.3.5 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Bj8G1wmD.d.ts → game-cb99J-YE.d.ts} +112 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22445 -12411
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +59 -10
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +544 -106
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +40 -6
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +69 -12
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
package/src/worker.ts ADDED
@@ -0,0 +1,842 @@
1
+ /**
2
+ * The worker game host (PRD-752): the page keeps the DOM, the canvas and the input, while the
3
+ * unchanged portable game runs in a dedicated worker on an OffscreenCanvas.
4
+ *
5
+ * A worker cannot reach `window`, `document` or `ResizeObserver`, so the page forwards what the
6
+ * game would have read, one plain message at a time. The canvas frame and the UI bridge travel on
7
+ * their own ports: the game's start is slow, and a HUD that mounts first must not wait for it.
8
+ */
9
+
10
+ import type { IGamePlatformSource } from "./game.js";
11
+ import { hostDocument, hostResizeObserver, hostWindow } from "./platform.js";
12
+ import { countDebug, debugRequested } from "./profiling/debug-telemetry.js";
13
+ import { markerLogRequested } from "./quiet-markers.js";
14
+ import { GAME_STATE_MESSAGE } from "./ui-bridge.js";
15
+ import { createRemoteAudioContext, serveRemoteAudio } from "./worker-audio.js";
16
+
17
+ /** The realm `serveWorkerGame` runs in. Narrowed, because a test cannot build a real worker scope. */
18
+ export type WorkerScope = EventTarget &
19
+ Record<string, unknown> & {
20
+ postMessage(data: unknown): void;
21
+ };
22
+
23
+ interface IWorkerInitMessage {
24
+ type: "tn-worker-init";
25
+ canvas: OffscreenCanvas;
26
+ width: number;
27
+ height: number;
28
+ dpr: number;
29
+ pageUrl: string;
30
+ globals: Record<string, string | number | boolean>;
31
+ /** The page's navigator facts: a WorkerNavigator has no maxTouchPoints, so a phone read as touchless. */
32
+ navigator: Record<string, unknown>;
33
+ ui: MessagePort;
34
+ /** The page's AudioContext, served over its own port; absent where the page has none. */
35
+ audio?: { port: MessagePort; sampleRate: number; currentTime: number };
36
+ }
37
+
38
+ interface IWorkerResizeMessage {
39
+ type: "tn-worker-resize";
40
+ width: number;
41
+ height: number;
42
+ dpr: number;
43
+ }
44
+
45
+ interface IWorkerEventMessage {
46
+ type: "tn-worker-event";
47
+ target: "window" | "canvas";
48
+ event: Record<string, unknown>;
49
+ }
50
+
51
+ interface IWorkerRpcMessage {
52
+ type: "tn-worker-rpc";
53
+ id: number;
54
+ name: string;
55
+ method: string;
56
+ args: unknown[];
57
+ get?: boolean;
58
+ }
59
+
60
+ type WorkerGamepad = Pick<Gamepad, "id" | "index" | "connected" | "mapping" | "timestamp"> & {
61
+ axes: number[];
62
+ buttons: { pressed: boolean; value: number; touched: boolean }[];
63
+ };
64
+
65
+ type WorkerInbound =
66
+ | IWorkerInitMessage
67
+ | IWorkerResizeMessage
68
+ | IWorkerEventMessage
69
+ | IWorkerRpcMessage
70
+ | { type: "tn-worker-gamepads"; gamepads: (WorkerGamepad | null)[] };
71
+
72
+ type WorkerOutbound =
73
+ | { type: "tn-worker-ready" }
74
+ | { type: "tn-worker-mirror"; name: string; epoch?: number }
75
+ | { type: "tn-worker-started" }
76
+ | { type: "tn-worker-failed"; message: string }
77
+ | { type: "tn-worker-pointer-lock"; lock: boolean }
78
+ | { type: "tn-worker-attribute"; name: string; value: string }
79
+ | {
80
+ type: "tn-worker-rpc-result";
81
+ id: number;
82
+ name?: string;
83
+ epoch?: number;
84
+ result?: unknown;
85
+ error?: string;
86
+ };
87
+
88
+ type PageOutbound = WorkerInbound;
89
+
90
+ interface IPendingCall {
91
+ resolve(value: unknown): void;
92
+ reject(error: Error): void;
93
+ }
94
+
95
+ /** Debug surfaces the playtest harness drives from the page; they exist inside the worker only. */
96
+ const MIRRORED_GLOBALS = ["__THREENATIVE_PLAYTEST_BRIDGE__", "__THREENATIVE__"] as const;
97
+
98
+ /** The fields an input event carries across the boundary. `type` rides along as the event's name. */
99
+ const EVENT_FIELDS = [
100
+ "type",
101
+ "key",
102
+ "code",
103
+ "repeat",
104
+ "altKey",
105
+ "ctrlKey",
106
+ "metaKey",
107
+ "shiftKey",
108
+ "button",
109
+ "buttons",
110
+ "movementX",
111
+ "movementY",
112
+ "pointerId",
113
+ "pointerType",
114
+ "isPrimary",
115
+ "pressure",
116
+ "deltaX",
117
+ "deltaY",
118
+ "deltaZ",
119
+ "deltaMode",
120
+ "clientX",
121
+ "clientY",
122
+ ] as const;
123
+
124
+ const WINDOW_EVENTS = ["keydown", "keyup", "mousemove", "wheel", "blur"] as const;
125
+ const CANVAS_EVENTS = [
126
+ "pointerdown",
127
+ "pointermove",
128
+ "pointerup",
129
+ "pointercancel",
130
+ "click",
131
+ ] as const;
132
+
133
+ // `serializeUiState` writes `{ type, state }` in that order, so a state frame starts with this. A
134
+ // prefix test, not a parse: the page parses each frame once already, and that thread is the one to keep free.
135
+ const STATE_FRAME_PREFIX = `{"type":${JSON.stringify(GAME_STATE_MESSAGE)},`;
136
+
137
+ function isStateFrame(frame: unknown): frame is string {
138
+ return typeof frame === "string" && frame.startsWith(STATE_FRAME_PREFIX);
139
+ }
140
+
141
+ /** Shallow primitive payload estimate only: excludes clone headers, nested objects and transfers. */
142
+ function debugWorkerMessage(name: string, payload: unknown): void {
143
+ let bytes = 0;
144
+ let unmeasured = 0;
145
+ const primitive = (value: unknown): void => {
146
+ if (typeof value === "string") bytes += value.length * 2;
147
+ else if (typeof value === "number") bytes += 8;
148
+ else if (typeof value === "boolean") bytes += 1;
149
+ else if (value !== undefined && value !== null) unmeasured++;
150
+ };
151
+ if (typeof payload === "object" && payload !== null) {
152
+ for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(payload))) {
153
+ bytes += key.length * 2;
154
+ if ("value" in descriptor) primitive(descriptor.value);
155
+ else unmeasured++; // Observing traffic must not invoke a payload's getter.
156
+ }
157
+ } else primitive(payload);
158
+ const area = name.startsWith("workerUi") ? "ui" : "worker";
159
+ const caller = `worker.ts:${name} (shallow primitive payload; nested/transfer bytes unavailable)`;
160
+ countDebug(`${name}Messages`, 1, area, caller);
161
+ countDebug(`${name}EstimatedBytes`, bytes, area, caller, "estimated-bytes");
162
+ countDebug(`${name}UnmeasuredFields`, unmeasured, area, caller);
163
+ countDebug(`${name}UnmeasuredMessages`, unmeasured > 0 ? 1 : 0, area, caller);
164
+ }
165
+
166
+ /** Times the synchronous postMessage call, including clone/enqueue, not delivery or receiver work. */
167
+ function debugWorkerPost(
168
+ name: string,
169
+ target: { postMessage(data: unknown): void },
170
+ payload: unknown,
171
+ ): void {
172
+ const started = performance.now();
173
+ try {
174
+ target.postMessage(payload);
175
+ } finally {
176
+ const elapsed = performance.now() - started;
177
+ debugWorkerMessage(name, payload); // Counts attempted dispatches, even a refused clone.
178
+ countDebug(
179
+ `${name}DispatchMs`,
180
+ elapsed,
181
+ name.startsWith("workerUi") ? "ui" : "worker",
182
+ `worker.ts:${name}.postMessage (synchronous attempt)`,
183
+ "ms",
184
+ );
185
+ }
186
+ }
187
+
188
+ /**
189
+ * The game end of the UI bridge, live before the page's port arrives.
190
+ *
191
+ * A game module may connect its bridge while it evaluates (`game.ui.onIntent` at top level), and
192
+ * the bridge picks its transport once, at connect. So the host globals exist from the moment this
193
+ * module loads, frames each way wait in order, and `attach` joins them to the page's port.
194
+ */
195
+ function holdUiBridge(scope: Record<string, unknown>): { attach(port: MessagePort): void } {
196
+ const existing = scope.__tnWorkerUi as { attach(port: MessagePort): void } | undefined;
197
+ if (existing !== undefined) return existing;
198
+ let port: MessagePort | undefined;
199
+ let debug = debugRequested();
200
+ const outbound: unknown[] = [];
201
+ const inbound: unknown[] = [];
202
+ let snapshot: string | undefined;
203
+ let snapshotPending = false;
204
+ const post = (frame: unknown): void => {
205
+ if (port === undefined) return;
206
+ if (debug) debugWorkerPost("workerUiPost", port, frame);
207
+ else port.postMessage(frame);
208
+ };
209
+ const flushSnapshot = (): void => {
210
+ if (port === undefined || snapshotPending || snapshot === undefined) return;
211
+ snapshotPending = true;
212
+ post(snapshot);
213
+ snapshot = undefined;
214
+ };
215
+ let receive = scope.__tnUiGameReceive as ((frame: unknown) => void) | undefined;
216
+ Object.defineProperty(scope, "__tnUiGameReceive", {
217
+ configurable: true,
218
+ get: () => receive,
219
+ set: (value: ((frame: unknown) => void) | undefined) => {
220
+ receive = value;
221
+ if (typeof value === "function") for (const frame of inbound.splice(0)) value(frame);
222
+ },
223
+ });
224
+ scope.__tnUiPost = (frame: string) => {
225
+ if (isStateFrame(frame)) {
226
+ snapshot = frame;
227
+ flushSnapshot();
228
+ } else if (port === undefined) outbound.push(frame);
229
+ else post(frame);
230
+ };
231
+ scope.__tnUiOverlayAttached = () => true;
232
+ const held = {
233
+ attach(next: MessagePort): void {
234
+ port = next;
235
+ debug = debugRequested();
236
+ next.onmessage = (event: MessageEvent) => {
237
+ if (debug) debugWorkerMessage("workerUiReceived", event.data);
238
+ if (event.data?.type === "tn-worker-ui-ack") {
239
+ snapshotPending = false;
240
+ flushSnapshot();
241
+ return;
242
+ }
243
+ if (typeof receive === "function") receive(event.data);
244
+ else inbound.push(event.data);
245
+ };
246
+ for (const frame of outbound.splice(0)) post(frame);
247
+ flushSnapshot();
248
+ },
249
+ };
250
+ scope.__tnWorkerUi = held;
251
+ return held;
252
+ }
253
+
254
+ // In a dedicated worker, before the game module that imports this one after it evaluates.
255
+ if (hostWindow() === undefined && "WorkerGlobalScope" in globalThis) {
256
+ // quality-allow: the worker scope is no Window; the UI bridge holds it as a keyed record
257
+ holdUiBridge(globalThis as unknown as Record<string, unknown>);
258
+ }
259
+
260
+ /**
261
+ * Runs inside the worker: wire the page's messages to the unchanged portable game.
262
+ *
263
+ * Call it last in the worker entry, after the game module evaluated: it posts the ready message
264
+ * the page waits for before it sends the canvas.
265
+ * @situation run the game loop in a web worker so a busy page cannot stall its frames
266
+ * @example serveWorkerGame(game);
267
+ */
268
+ export function serveWorkerGame(
269
+ game: { start(): Promise<void> },
270
+ // quality-allow: the DOM lib this package compiles with has no DedicatedWorkerGlobalScope type
271
+ scope: WorkerScope = globalThis as unknown as WorkerScope,
272
+ ): void {
273
+ const inputTarget = new EventTarget();
274
+ const observers = new Set<() => void>();
275
+ const size = { dpr: 1, height: 1, width: 1 };
276
+ let canvas: OffscreenCanvas | undefined;
277
+ let gamepads: (WorkerGamepad | null)[] = [];
278
+ let debug = debugRequested();
279
+
280
+ const post = (message: WorkerOutbound): void => {
281
+ if (debug) debugWorkerPost("workerPost", scope, message);
282
+ else scope.postMessage(message);
283
+ };
284
+ const ui = holdUiBridge(scope);
285
+
286
+ const initialise = async (message: IWorkerInitMessage): Promise<void> => {
287
+ try {
288
+ canvas = message.canvas;
289
+ // An OffscreenCanvas cannot lock the pointer: the page locks its own canvas, inside the
290
+ // click's activation window, and forwards each pointerlockchange with `captured`. Attributes
291
+ // (the renderer's `data-engine`) land on the page canvas, where the harness reads them.
292
+ Object.assign(canvas, {
293
+ exitPointerLock: () => post({ lock: false, type: "tn-worker-pointer-lock" }),
294
+ requestPointerLock: () => post({ lock: true, type: "tn-worker-pointer-lock" }),
295
+ setAttribute: (name: string, value: string) =>
296
+ post({ name, type: "tn-worker-attribute", value: String(value) }),
297
+ });
298
+ size.width = message.width;
299
+ size.height = message.height;
300
+ size.dpr = message.dpr;
301
+ scope.devicePixelRatio = message.dpr;
302
+ for (const [key, value] of Object.entries(message.globals)) scope[key] = value;
303
+ // Read by platform detection (`isMobile`, `isTouchscreenAvailable`) in place of the worker's own.
304
+ scope.__tnPageNavigator = message.navigator;
305
+
306
+ // A worker resolves relative URLs against its own script, so the page's URL is the base.
307
+ const pageUrl = message.pageUrl;
308
+ const resolve = (input: RequestInfo | URL): RequestInfo | URL =>
309
+ typeof input === "string" || input instanceof URL ? new URL(input, pageUrl) : input;
310
+ const originalFetch = scope.fetch as typeof fetch;
311
+ scope.fetch = ((input: RequestInfo | URL, init?: RequestInit) =>
312
+ originalFetch(resolve(input), init)) as typeof fetch;
313
+ const OriginalRequest = scope.Request as typeof Request;
314
+ scope.Request = class extends OriginalRequest {
315
+ constructor(input: RequestInfo | URL, init?: RequestInit) {
316
+ super(resolve(input), init);
317
+ }
318
+ };
319
+
320
+ const observe = (_target: HTMLCanvasElement, resize: () => void): (() => void) => {
321
+ observers.add(resize);
322
+ return () => {
323
+ observers.delete(resize);
324
+ };
325
+ };
326
+ const platform: IGamePlatformSource = {
327
+ input: () => gamepads,
328
+ inputTarget,
329
+ mountCanvas: () => undefined,
330
+ renderer: {
331
+ // quality-allow: three types its canvas as HTMLCanvasElement; the transferred OffscreenCanvas fills that slot
332
+ createCanvas: () => message.canvas as unknown as HTMLCanvasElement,
333
+ hasWebGPU: () => "gpu" in navigator,
334
+ observeResize: observe,
335
+ readSize: () => [size.width, size.height],
336
+ },
337
+ unmountCanvas: () => undefined,
338
+ viewport: {
339
+ observeResize: observe,
340
+ readSize: () => ({
341
+ aspect: size.width / size.height,
342
+ height: size.height,
343
+ width: size.width,
344
+ }),
345
+ },
346
+ };
347
+ scope.__tnGamePlatform = platform;
348
+
349
+ const audio = message.audio;
350
+ if (audio !== undefined) {
351
+ // Created on first use, so a silent game opens no page AudioContext traffic.
352
+ let remote: AudioContext | undefined;
353
+ scope.AudioContext = function RemoteAudioContext() {
354
+ remote ??= createRemoteAudioContext(audio.port, audio);
355
+ return remote;
356
+ };
357
+ }
358
+
359
+ ui.attach(message.ui);
360
+
361
+ // Mirrored the moment the game installs one: with a runner announced, the playtest plugin
362
+ // holds start until the runner calls the bridge, so a mirror sent after start never arrives.
363
+ const mirror = (name: string, value: unknown): void => {
364
+ if (typeof value !== "object" || value === null) return;
365
+ const epoch = (value as { _clockEpoch?: number })._clockEpoch;
366
+ post({ epoch, name, type: "tn-worker-mirror" });
367
+ };
368
+ for (const name of MIRRORED_GLOBALS) {
369
+ let value = scope[name];
370
+ mirror(name, value);
371
+ Object.defineProperty(scope, name, {
372
+ configurable: true,
373
+ get: () => value,
374
+ set: (next: unknown) => {
375
+ value = next;
376
+ mirror(name, next);
377
+ },
378
+ });
379
+ }
380
+
381
+ await game.start();
382
+ post({ type: "tn-worker-started" });
383
+ } catch (error) {
384
+ post({
385
+ message: error instanceof Error ? error.message : String(error),
386
+ type: "tn-worker-failed",
387
+ });
388
+ }
389
+ };
390
+
391
+ const dispatchForwarded = (message: IWorkerEventMessage): void => {
392
+ const forwarded = new Event(String(message.event.type), { cancelable: true });
393
+ for (const [key, value] of Object.entries(message.event)) {
394
+ Object.defineProperty(forwarded, key, { enumerable: true, value });
395
+ }
396
+ if (message.target === "window") inputTarget.dispatchEvent(forwarded);
397
+ else {
398
+ canvas?.dispatchEvent(forwarded);
399
+ // On a page a canvas event bubbles to the window, where AudioBus waits for its gesture.
400
+ const bubbled = new Event(forwarded.type);
401
+ for (const [key, value] of Object.entries(message.event))
402
+ Object.defineProperty(bubbled, key, { enumerable: true, value });
403
+ inputTarget.dispatchEvent(bubbled);
404
+ }
405
+ };
406
+
407
+ const handleRpc = async (message: IWorkerRpcMessage): Promise<void> => {
408
+ const id = message.id;
409
+ try {
410
+ const receiver = scope[message.name] as Record<string, unknown> | undefined;
411
+ const method = receiver?.[message.method];
412
+ if (!message.get && typeof method !== "function") {
413
+ throw new Error(
414
+ `TN_WORKER_RPC_UNKNOWN: '${message.name}.${message.method}' is not a function.`,
415
+ );
416
+ }
417
+ const result = message.get
418
+ ? method
419
+ : await (method as (...args: unknown[]) => unknown).apply(receiver, message.args);
420
+ post({
421
+ id,
422
+ result,
423
+ name: message.name,
424
+ epoch: receiver?._clockEpoch as number | undefined,
425
+ type: "tn-worker-rpc-result",
426
+ });
427
+ } catch (error) {
428
+ post({
429
+ error: error instanceof Error ? error.message : String(error),
430
+ id,
431
+ type: "tn-worker-rpc-result",
432
+ });
433
+ }
434
+ };
435
+
436
+ const onMessage = (event: Event): void => {
437
+ const message = (event as MessageEvent).data as WorkerInbound;
438
+ if (message.type === "tn-worker-init" && message.globals.__THREENATIVE_DEBUG__ === true)
439
+ debug = true;
440
+ if (debug) debugWorkerMessage("workerReceived", message);
441
+ switch (message.type) {
442
+ case "tn-worker-init":
443
+ void initialise(message);
444
+ break;
445
+ case "tn-worker-resize":
446
+ size.width = message.width;
447
+ size.height = message.height;
448
+ size.dpr = message.dpr;
449
+ scope.devicePixelRatio = message.dpr;
450
+ for (const observer of [...observers]) observer();
451
+ break;
452
+ case "tn-worker-event":
453
+ dispatchForwarded(message);
454
+ break;
455
+ case "tn-worker-rpc":
456
+ void handleRpc(message);
457
+ break;
458
+ case "tn-worker-gamepads":
459
+ gamepads = message.gamepads;
460
+ break;
461
+ }
462
+ };
463
+
464
+ scope.addEventListener("message", onMessage);
465
+ post({ type: "tn-worker-ready" });
466
+ }
467
+
468
+ /**
469
+ * Runs on the page: own the canvas and the DOM, and feed the worker game.
470
+ *
471
+ * Call it before the UI mounts: the HUD's bridge host globals exist from this call on.
472
+ * @situation host a worker-run game's canvas, input and HUD on the page
473
+ * @example const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }), root);
474
+ */
475
+ export function startWorkerGame(
476
+ worker: Worker,
477
+ container: HTMLElement,
478
+ ): { ready: Promise<void>; stop(): void } {
479
+ const documentHost = hostDocument();
480
+ const windowHost = hostWindow();
481
+ if (documentHost === undefined || windowHost === undefined) {
482
+ throw new Error("TN_WORKER_HOST_REQUIRED: startWorkerGame runs on a page.");
483
+ }
484
+ // quality-allow: the page host is read by key for the globals it forwards
485
+ const page = windowHost as unknown as Record<string, unknown>;
486
+
487
+ const canvas = documentHost.createElement("canvas");
488
+ canvas.style.cssText = "display:block;width:100%;height:100%;touch-action:none";
489
+ container.append(canvas);
490
+ const offscreen = canvas.transferControlToOffscreen();
491
+ const { port1: uiPort, port2: gamePort } = new MessageChannel();
492
+
493
+ let stopped = false;
494
+ let nextRpcId = 0;
495
+ const pending = new Map<number, IPendingCall>();
496
+ const installed = new Set<string>();
497
+ const capturedPointers = new Set<number>();
498
+ const listeners: Array<[EventTarget, string, EventListener]> = [];
499
+
500
+ const send = (message: PageOutbound, transfer?: Transferable[]): void => {
501
+ if (stopped) return;
502
+ if (transfer === undefined) worker.postMessage(message);
503
+ else worker.postMessage(message, transfer);
504
+ };
505
+
506
+ const postResize = (): void => {
507
+ send({
508
+ dpr: windowHost.devicePixelRatio,
509
+ height: Math.max(1, canvas.clientHeight),
510
+ type: "tn-worker-resize",
511
+ width: Math.max(1, canvas.clientWidth),
512
+ });
513
+ };
514
+
515
+ const listen = (target: EventTarget, type: string, listener: EventListener): void => {
516
+ target.addEventListener(type, listener);
517
+ listeners.push([target, type, listener]);
518
+ };
519
+
520
+ let gamepadFrame: number | undefined;
521
+ const pollGamepads = (): void => {
522
+ if (gamepadFrame !== undefined) windowHost.cancelAnimationFrame(gamepadFrame);
523
+ gamepadFrame = undefined;
524
+ if (stopped) return;
525
+ const gamepads = Array.from(windowHost.navigator?.getGamepads?.() ?? [], (pad) =>
526
+ pad === null
527
+ ? null
528
+ : {
529
+ id: pad.id,
530
+ index: pad.index,
531
+ connected: pad.connected,
532
+ mapping: pad.mapping,
533
+ timestamp: pad.timestamp,
534
+ axes: Array.from(pad.axes),
535
+ buttons: Array.from(pad.buttons, ({ pressed, value, touched }) => ({
536
+ pressed,
537
+ value,
538
+ touched,
539
+ })),
540
+ },
541
+ );
542
+ send({ type: "tn-worker-gamepads", gamepads });
543
+ if (gamepads.some((pad) => pad?.connected))
544
+ gamepadFrame = windowHost.requestAnimationFrame(pollGamepads);
545
+ };
546
+ listen(windowHost, "gamepadconnected", pollGamepads);
547
+ listen(windowHost, "gamepaddisconnected", pollGamepads);
548
+
549
+ const eventFields = (event: Event): Record<string, unknown> => {
550
+ // quality-allow: a DOM event is copied by key into a structured-clone message
551
+ const source = event as unknown as Record<string, unknown>;
552
+ const fields: Record<string, unknown> = {};
553
+ for (const field of EVENT_FIELDS) {
554
+ if (field in event) fields[field] = source[field];
555
+ }
556
+ return fields;
557
+ };
558
+
559
+ let motionFrame: number | undefined;
560
+ const motion = new Map<string, IWorkerEventMessage>();
561
+ const postEvent = (message: IWorkerEventMessage, rect?: DOMRect): void => {
562
+ const fields = message.event;
563
+ // The worker draws on the canvas, so its pointer coordinates must be canvas-relative.
564
+ if (message.target === "canvas" || fields.type === "wheel") {
565
+ const bounds = rect ?? canvas.getBoundingClientRect();
566
+ const { clientX, clientY } = fields;
567
+ if (typeof clientX === "number") fields.clientX = clientX - bounds.left;
568
+ if (typeof clientY === "number") fields.clientY = clientY - bounds.top;
569
+ }
570
+ send(message);
571
+ };
572
+ const flushMotion = (): void => {
573
+ if (motionFrame !== undefined) windowHost.cancelAnimationFrame(motionFrame);
574
+ motionFrame = undefined;
575
+ if (stopped) motion.clear();
576
+ if (motion.size === 0) return;
577
+ const rect = [...motion.values()].some((message) => message.target === "canvas")
578
+ ? canvas.getBoundingClientRect()
579
+ : undefined;
580
+ for (const message of motion.values()) postEvent(message, rect);
581
+ motion.clear();
582
+ };
583
+ const forward = (event: Event, target: "window" | "canvas"): void => {
584
+ if (stopped) return;
585
+ // Match InputMap: wheel events on DOM overlays belong to the HUD.
586
+ if (
587
+ event.type === "wheel" &&
588
+ event.target != null &&
589
+ event.target !== windowHost &&
590
+ event.target !== canvas
591
+ )
592
+ return;
593
+ const fields = eventFields(event);
594
+ if (event.type === "pointermove" || event.type === "mousemove") {
595
+ const key = `${target}:${event.type}:${fields.pointerId ?? ""}`;
596
+ const previous = motion.get(key)?.event;
597
+ fields.movementX = Number(previous?.movementX ?? 0) + Number(fields.movementX ?? 0);
598
+ fields.movementY = Number(previous?.movementY ?? 0) + Number(fields.movementY ?? 0);
599
+ motion.set(key, { event: fields, target, type: "tn-worker-event" });
600
+ motionFrame ??= windowHost.requestAnimationFrame(flushMotion);
601
+ return;
602
+ }
603
+ flushMotion();
604
+ postEvent({ event: fields, target, type: "tn-worker-event" });
605
+ };
606
+
607
+ for (const type of WINDOW_EVENTS) listen(windowHost, type, (event) => forward(event, "window"));
608
+ const releasePointer = (id: number): void => {
609
+ if (!capturedPointers.delete(id)) return;
610
+ try {
611
+ canvas.releasePointerCapture?.(id);
612
+ } catch {
613
+ // The browser may already have released a cancelled pointer.
614
+ }
615
+ };
616
+ for (const type of CANVAS_EVENTS)
617
+ listen(canvas, type, (event) => {
618
+ const id = (event as PointerEvent).pointerId;
619
+ if (type === "pointerdown" && canvas.setPointerCapture !== undefined) {
620
+ try {
621
+ canvas.setPointerCapture(id);
622
+ capturedPointers.add(id);
623
+ } catch {
624
+ // Synthetic events have no active browser pointer to capture.
625
+ }
626
+ }
627
+ forward(event, "canvas");
628
+ if (type === "pointerup" || type === "pointercancel") releasePointer(id);
629
+ });
630
+ listen(canvas, "contextmenu", (event) => event.preventDefault());
631
+ const pageLock = documentHost as Document & { pointerLockElement?: Element | null };
632
+ const sendLock = (captured: boolean): void =>
633
+ send({
634
+ event: { captured, type: "pointerlockchange" },
635
+ target: "canvas",
636
+ type: "tn-worker-event",
637
+ });
638
+ listen(pageLock, "pointerlockchange", () => sendLock(pageLock.pointerLockElement === canvas));
639
+ listen(pageLock, "pointerlockerror", () => sendLock(false));
640
+ const pointerLock = (lock: boolean): void => {
641
+ if (!lock) {
642
+ pageLock.exitPointerLock?.();
643
+ return;
644
+ }
645
+ // A refused lock fires no pointerlockchange: report it, or the game believes it captured.
646
+ const refused = (): void => sendLock(false);
647
+ try {
648
+ void (canvas.requestPointerLock?.() as Promise<void> | undefined)?.catch(refused);
649
+ } catch {
650
+ refused();
651
+ }
652
+ };
653
+
654
+ // The worker's game plays through the page's own AudioContext, resumed by a page gesture.
655
+ const AudioContextCtor = page.AudioContext as (new () => AudioContext) | undefined;
656
+ const audioContext = AudioContextCtor === undefined ? undefined : new AudioContextCtor();
657
+ const audioChannel = audioContext === undefined ? undefined : new MessageChannel();
658
+ const stopAudio =
659
+ audioContext === undefined || audioChannel === undefined
660
+ ? undefined
661
+ : serveRemoteAudio(audioChannel.port1, audioContext);
662
+ if (audioContext !== undefined) {
663
+ const resume = (): void => void audioContext.resume?.().catch(() => undefined);
664
+ for (const type of ["keydown", "pointerdown", "touchstart"]) listen(windowHost, type, resume);
665
+ }
666
+
667
+ const ResizeObserverCtor = hostResizeObserver();
668
+ const observer =
669
+ ResizeObserverCtor === undefined ? undefined : new ResizeObserverCtor(() => postResize());
670
+ observer?.observe(canvas);
671
+
672
+ const pageNavigator = (source: Navigator | undefined): Record<string, unknown> => {
673
+ const agent = (source as { userAgentData?: { mobile?: unknown; platform?: unknown } })
674
+ ?.userAgentData;
675
+ return {
676
+ maxTouchPoints: source?.maxTouchPoints,
677
+ platform: source?.platform,
678
+ userAgent: source?.userAgent,
679
+ ...(agent === undefined
680
+ ? {}
681
+ : { userAgentData: { mobile: agent.mobile, platform: agent.platform } }),
682
+ };
683
+ };
684
+
685
+ const pageGlobals = (): Record<string, string | number | boolean> => {
686
+ const globals: Record<string, string | number | boolean> = {};
687
+ for (const key of Object.keys(page)) {
688
+ if (!key.startsWith("__THREENATIVE_")) continue;
689
+ const value = page[key];
690
+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
691
+ globals[key] = value;
692
+ }
693
+ }
694
+ // The worker's own URL carries no `?tnLog`, so the page's answer travels as the global.
695
+ if (markerLogRequested()) globals.__THREENATIVE_LOG__ = true;
696
+ if (debugRequested()) globals.__THREENATIVE_DEBUG__ = true;
697
+ return globals;
698
+ };
699
+
700
+ // The UI mounts before the game is ready, so its host globals exist from the first call.
701
+ page.tnHost = { postMessage: (frame: string) => uiPort.postMessage(frame) };
702
+ page.__tnUiOverlayAttached = () => true;
703
+ installed.add("tnHost");
704
+ installed.add("__tnUiOverlayAttached");
705
+ uiPort.onmessage = (event: MessageEvent) => {
706
+ const receive = page.__tnUiReceive;
707
+ try {
708
+ if (typeof receive === "function") (receive as (frame: unknown) => void)(event.data);
709
+ } finally {
710
+ if (isStateFrame(event.data)) uiPort.postMessage({ type: "tn-worker-ui-ack" });
711
+ }
712
+ };
713
+
714
+ let resolveReady: () => void = () => undefined;
715
+ let rejectReady: (error: Error) => void = () => undefined;
716
+ const ready = new Promise<void>((resolve, reject) => {
717
+ resolveReady = resolve;
718
+ rejectReady = reject;
719
+ });
720
+
721
+ const mirrorEpochs = new Map<string, number>();
722
+ const installMirror = (name: string, epoch = 0): void => {
723
+ mirrorEpochs.set(name, epoch);
724
+ const call = (method: string, args: unknown[], get = false): Promise<unknown> => {
725
+ if (stopped) {
726
+ return Promise.reject(new Error("TN_WORKER_STOPPED: the worker game stopped."));
727
+ }
728
+ const id = nextRpcId++;
729
+ return new Promise<unknown>((resolve, reject) => {
730
+ pending.set(id, { reject, resolve });
731
+ send({ args, get, id, method, name, type: "tn-worker-rpc" });
732
+ });
733
+ };
734
+ page[name] = new Proxy(
735
+ {},
736
+ {
737
+ get: (_target, method) => {
738
+ // Promise resolution probes "then"; the mirror itself is not a thenable.
739
+ if (typeof method !== "string" || method === "then") return undefined;
740
+ // The runner reads the epoch synchronously around sample(); each RPC refreshes it.
741
+ if (method === "_clockEpoch") return mirrorEpochs.get(name) ?? 0;
742
+ if (method === "$get") return (field: string) => call(field, [], true);
743
+ return (...args: unknown[]) => call(method, args);
744
+ },
745
+ },
746
+ );
747
+ installed.add(name);
748
+ };
749
+
750
+ const sendInit = (): void => {
751
+ const init: IWorkerInitMessage = {
752
+ canvas: offscreen,
753
+ dpr: windowHost.devicePixelRatio ?? 1,
754
+ globals: pageGlobals(),
755
+ height: Math.max(1, canvas.clientHeight),
756
+ navigator: pageNavigator(windowHost.navigator),
757
+ pageUrl: windowHost.location.href,
758
+ type: "tn-worker-init",
759
+ ui: gamePort,
760
+ width: Math.max(1, canvas.clientWidth),
761
+ };
762
+ const transfer: Transferable[] = [offscreen, gamePort];
763
+ if (audioContext !== undefined && audioChannel !== undefined) {
764
+ init.audio = {
765
+ currentTime: audioContext.currentTime,
766
+ port: audioChannel.port2,
767
+ sampleRate: audioContext.sampleRate,
768
+ };
769
+ transfer.push(audioChannel.port2);
770
+ }
771
+ send(init, transfer);
772
+ pollGamepads();
773
+ };
774
+
775
+ const onWorkerMessage = (event: Event): void => {
776
+ if (stopped) return;
777
+ const message = (event as MessageEvent).data as WorkerOutbound;
778
+ switch (message.type) {
779
+ case "tn-worker-ready":
780
+ sendInit();
781
+ break;
782
+ case "tn-worker-pointer-lock":
783
+ pointerLock(message.lock);
784
+ break;
785
+ case "tn-worker-attribute":
786
+ canvas.setAttribute(message.name, message.value);
787
+ break;
788
+ case "tn-worker-mirror":
789
+ installMirror(message.name, message.epoch);
790
+ break;
791
+ case "tn-worker-started":
792
+ resolveReady();
793
+ break;
794
+ case "tn-worker-failed":
795
+ stop(new Error(message.message));
796
+ break;
797
+ case "tn-worker-rpc-result": {
798
+ const call = pending.get(message.id);
799
+ if (call === undefined) break;
800
+ pending.delete(message.id);
801
+ if (message.name !== undefined && message.epoch !== undefined)
802
+ mirrorEpochs.set(message.name, message.epoch);
803
+ if (message.error === undefined) call.resolve(message.result);
804
+ else call.reject(new Error(message.error));
805
+ break;
806
+ }
807
+ }
808
+ };
809
+
810
+ const stop = (error = new Error("TN_WORKER_STOPPED: the worker game stopped.")): void => {
811
+ if (stopped) return;
812
+ stopped = true;
813
+ rejectReady(error);
814
+ if (gamepadFrame !== undefined) windowHost.cancelAnimationFrame(gamepadFrame);
815
+ flushMotion();
816
+ for (const [target, type, listener] of listeners) target.removeEventListener(type, listener);
817
+ listeners.length = 0;
818
+ observer?.disconnect();
819
+ if (pageLock.pointerLockElement === canvas) pointerLock(false);
820
+ for (const id of capturedPointers) releasePointer(id);
821
+ canvas.remove();
822
+ for (const call of pending.values()) call.reject(error);
823
+ pending.clear();
824
+ uiPort.onmessage = null;
825
+ uiPort.close();
826
+ gamePort.close();
827
+ stopAudio?.();
828
+ void audioContext?.close?.().catch(() => undefined);
829
+ for (const key of installed) delete page[key];
830
+ installed.clear();
831
+ worker.terminate();
832
+ };
833
+
834
+ listen(worker, "message", onWorkerMessage);
835
+ const onWorkerError = (event: Event): void => {
836
+ const message = (event as ErrorEvent).message;
837
+ stop(new Error(message || `TN_WORKER_FAILED: worker ${event.type}.`));
838
+ };
839
+ listen(worker, "error", onWorkerError);
840
+ listen(worker, "messageerror", onWorkerError);
841
+ return { ready, stop };
842
+ }