@threenative/core 0.3.6 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -66,6 +66,13 @@ declare const UI_INTENT_MESSAGE = "tn:intent";
66
66
  * from it lies in exactly the sessions where somebody is trying to measure.
67
67
  */
68
68
  declare const UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
69
+ /**
70
+ * The startup phase the game end publishes: `covered` while the loading cover is up, `ready` from
71
+ * the frame the cover lifts. The UI realm cannot read `ctx.startup`, so this is how `useUiState`
72
+ * knows to return `undefined` until the player can see the page. A game that never sends it (an
73
+ * older core) reads as uncovered.
74
+ */
75
+ declare const UI_STARTUP_MESSAGE = "tn:startup";
69
76
  /**
70
77
  * The intent the UI layer sends once, when its tree has rendered and its rectangles are published.
71
78
  *
@@ -151,7 +158,9 @@ interface IUiStatePublisher {
151
158
  interface IUiStateMirror<T> {
152
159
  /** The last state the game published, or undefined before the first frame arrives. */
153
160
  get(): T | undefined;
154
- /** Called after each accepted publication. Returns an unsubscribe function. */
161
+ /** True while the game reports its loading cover up; false before it says so and after it lifts. */
162
+ covered(): boolean;
163
+ /** Called after each accepted publication, and when the cover state changes. Returns an unsubscribe function. */
155
164
  subscribe(listener: () => void): () => void;
156
165
  /** Stop listening. */
157
166
  stop(): void;
@@ -311,4 +320,4 @@ interface IScopeLike extends IEventTargetLike {
311
320
  */
312
321
  declare function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry;
313
322
 
314
- export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
323
+ export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, UI_STARTUP_MESSAGE, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
package/dist/ui-layer.js CHANGED
@@ -3,6 +3,7 @@ var HIT_REGIONS_MESSAGE = "tn:hit-regions";
3
3
  var GAME_STATE_MESSAGE = "tn:state";
4
4
  var UI_INTENT_MESSAGE = "tn:intent";
5
5
  var UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
6
+ var UI_STARTUP_MESSAGE = "tn:startup";
6
7
  var UI_READY_INTENT = "tn:ready";
7
8
  var UI_BRIDGE_GLOBALS = {
8
9
  /** UI end, inbound: the host calls this with one JSON string. */
@@ -129,12 +130,35 @@ function installInbound(scope, key, deliver) {
129
130
  if (installed.receivers.size === 0 && scope[key] === installed.dispatch) scope[key] = void 0;
130
131
  };
131
132
  }
133
+ var LOOPBACK_KEY = "__tnUiLoopback";
134
+ function installLoopback(scope) {
135
+ const search = scope.location?.search;
136
+ if (typeof search !== "string" || new URLSearchParams(search).get("tnUiLoopback") !== "1") return;
137
+ if (scope[LOOPBACK_KEY] !== void 0) return;
138
+ const { port1: gamePort, port2: uiPort } = new MessageChannel();
139
+ const receive = (key) => (event) => scope[key]?.(event.data);
140
+ gamePort.onmessage = receive(UI_BRIDGE_GLOBALS.gameReceive);
141
+ uiPort.onmessage = receive(UI_BRIDGE_GLOBALS.uiReceive);
142
+ scope[UI_BRIDGE_GLOBALS.gamePost] = (frame) => gamePort.postMessage(frame);
143
+ scope[UI_BRIDGE_GLOBALS.uiHost] = { postMessage: (frame) => uiPort.postMessage(frame) };
144
+ scope.__tnUiOverlayAttached = () => true;
145
+ scope[LOOPBACK_KEY] = {
146
+ close() {
147
+ gamePort.close();
148
+ uiPort.close();
149
+ for (const key of [UI_BRIDGE_GLOBALS.gamePost, UI_BRIDGE_GLOBALS.uiHost, LOOPBACK_KEY])
150
+ scope[key] = void 0;
151
+ scope.__tnUiOverlayAttached = void 0;
152
+ }
153
+ };
154
+ }
132
155
  function connectUiBridge(options) {
133
156
  const { end } = options;
134
157
  if (end !== "game" && end !== "ui") {
135
158
  throw new Error(`TN_UI_BRIDGE_END_INVALID: expected 'game' or 'ui', got '${String(end)}'.`);
136
159
  }
137
160
  const scope = options.scope ?? globalThis;
161
+ installLoopback(scope);
138
162
  const listeners = /* @__PURE__ */ new Set();
139
163
  const deliver = (frame) => {
140
164
  const message = parseFrame(frame);
@@ -204,6 +228,31 @@ function connectUiBridge(options) {
204
228
  };
205
229
  }
206
230
 
231
+ // src/profiling/debug-telemetry.ts
232
+ var DEBUG_GLOBAL = "__THREENATIVE_DEBUG__";
233
+ function debugRequested() {
234
+ const host = globalThis;
235
+ return host.process?.env?.TN_DEBUG === "1" || globalThis[DEBUG_GLOBAL] === true || /[?&]tnDebug=1(?:&|$)/u.test(globalThis.location?.search ?? "");
236
+ }
237
+ function countDebug(name, value, area, caller, unit = "count") {
238
+ if (!Number.isFinite(value) || value < 0)
239
+ throw new Error(`TN_DEBUG: invalid ${name} observation.`);
240
+ const host = globalThis;
241
+ host.__tnEngineCost ??= {};
242
+ host.__tnDebugSources ??= {};
243
+ host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + value;
244
+ host.__tnDebugSources[name] ??= { area, caller, unit };
245
+ }
246
+ function measureDebug(name, area, caller, run) {
247
+ const start = performance.now();
248
+ try {
249
+ return run();
250
+ } finally {
251
+ countDebug(`${name}Ms`, performance.now() - start, area, caller, "ms");
252
+ countDebug(`${name}Calls`, 1, area, caller);
253
+ }
254
+ }
255
+
207
256
  // src/ui-state.ts
208
257
  var microtask = (flush) => {
209
258
  void Promise.resolve().then(flush);
@@ -215,6 +264,11 @@ function publishUiState(bridge, store, options = {}) {
215
264
  );
216
265
  }
217
266
  const schedule = options.schedule ?? microtask;
267
+ const debug = debugRequested();
268
+ const serialize = debug ? (state) => {
269
+ countDebug("uiSerializations", 1, "ui", "publishUiState");
270
+ return measureDebug("uiSerialize", "ui", "publishUiState", () => serializeUiState(state));
271
+ } : serializeUiState;
218
272
  const read = () => store.getPublishedState === void 0 ? store.getState() : store.getPublishedState();
219
273
  let stopped = false;
220
274
  let queued = false;
@@ -222,18 +276,27 @@ function publishUiState(bridge, store, options = {}) {
222
276
  const send = (state, frame) => {
223
277
  lastFrame = frame;
224
278
  postUiState(bridge, state, frame);
279
+ if (debug) {
280
+ countDebug("uiMessages", 1, "ui", "publishUiState");
281
+ countDebug(
282
+ "uiMessageBytes",
283
+ new TextEncoder().encode(frame).byteLength,
284
+ "ui",
285
+ "publishUiState"
286
+ );
287
+ }
225
288
  };
226
289
  const publish = () => {
227
290
  if (stopped) return;
228
291
  const state = read();
229
- send(state, serializeUiState(state));
292
+ send(state, serialize(state));
230
293
  };
231
294
  const flush = () => {
232
295
  queued = false;
233
296
  if (stopped) return;
234
297
  if (!bridge.hasPeer()) return;
235
298
  const state = read();
236
- const frame = serializeUiState(state);
299
+ const frame = serialize(state);
237
300
  if (frame === lastFrame) return;
238
301
  send(state, frame);
239
302
  };
@@ -259,7 +322,15 @@ function subscribeUiState(bridge) {
259
322
  }
260
323
  const listeners = /* @__PURE__ */ new Set();
261
324
  let current;
325
+ let covered = false;
262
326
  const off = bridge.onMessage((message) => {
327
+ if (message.type === UI_STARTUP_MESSAGE) {
328
+ const next = message.phase !== "ready";
329
+ if (next === covered) return;
330
+ covered = next;
331
+ for (const listener of [...listeners]) listener();
332
+ return;
333
+ }
263
334
  if (message.type !== GAME_STATE_MESSAGE) return;
264
335
  const state = message.state;
265
336
  if (typeof state !== "object" || state === null || Array.isArray(state)) {
@@ -270,6 +341,7 @@ function subscribeUiState(bridge) {
270
341
  });
271
342
  return {
272
343
  get: () => current,
344
+ covered: () => covered,
273
345
  subscribe(listener) {
274
346
  listeners.add(listener);
275
347
  return () => listeners.delete(listener);
@@ -315,7 +387,7 @@ var INTERACTIVE_ATTRIBUTE = "data-tn-interactive";
315
387
  function quantize(value) {
316
388
  return Math.round(value * 1e5) / 1e5;
317
389
  }
318
- var TRANSITION_START = ["transitionrun", "transitionstart", "animationstart"];
390
+ var TRANSITION_START = ["transitionstart", "animationstart"];
319
391
  var TRANSITION_END = [
320
392
  "transitionend",
321
393
  "transitioncancel",
@@ -474,4 +546,4 @@ function isDevelopment() {
474
546
  return import.meta.env?.DEV === true;
475
547
  }
476
548
 
477
- export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
549
+ export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, UI_STARTUP_MESSAGE, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
@@ -0,0 +1,36 @@
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
+ /** The realm `serveWorkerGame` runs in. Narrowed, because a test cannot build a real worker scope. */
10
+ type WorkerScope = EventTarget & Record<string, unknown> & {
11
+ postMessage(data: unknown): void;
12
+ };
13
+ /**
14
+ * Runs inside the worker: wire the page's messages to the unchanged portable game.
15
+ *
16
+ * Call it last in the worker entry, after the game module evaluated: it posts the ready message
17
+ * the page waits for before it sends the canvas.
18
+ * @situation run the game loop in a web worker so a busy page cannot stall its frames
19
+ * @example serveWorkerGame(game);
20
+ */
21
+ declare function serveWorkerGame(game: {
22
+ start(): Promise<void>;
23
+ }, scope?: WorkerScope): void;
24
+ /**
25
+ * Runs on the page: own the canvas and the DOM, and feed the worker game.
26
+ *
27
+ * Call it before the UI mounts: the HUD's bridge host globals exist from this call on.
28
+ * @situation host a worker-run game's canvas, input and HUD on the page
29
+ * @example const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }), root);
30
+ */
31
+ declare function startWorkerGame(worker: Worker, container: HTMLElement): {
32
+ ready: Promise<void>;
33
+ stop(): void;
34
+ };
35
+
36
+ export { type WorkerScope, serveWorkerGame, startWorkerGame };