@threenative/core 0.3.6 → 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-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
package/src/loop.ts CHANGED
@@ -66,6 +66,13 @@ export interface IFixedStepLoopOptions {
66
66
  readonly interpolation?: PhysicsInterpolation;
67
67
  readonly step?: number;
68
68
  readonly maxSteps?: number;
69
+ /**
70
+ * The most wall time one frame adds to the simulation, in seconds. Default 1/20, after Unreal's
71
+ * `MaxPhysicsDeltaTime` (1/30 in UE 5.8.3: Engine/Source/Runtime/Engine/Private/PhysicsEngine/PhysicsSettings.cpp:22,
72
+ * applied per frame in PhysLevel.cpp:212). A slower frame slows the simulation instead of running
73
+ * extra whole updates to catch up. `Infinity` turns the clamp off; `maxSteps` still bounds a frame.
74
+ */
75
+ readonly maxPhysicsDeltaTime?: number;
69
76
  /** Collect per-frame render samples for diagnostics consumers. Default false. */
70
77
  readonly collectMetrics?: boolean;
71
78
  /** Runs once per presented frame, before any fixed-step simulation dispatches. */
@@ -152,9 +159,17 @@ function aggregatePassesByKind(passes: readonly IRenderPassSample[]): IRenderPas
152
159
  */
153
160
  const FROZEN_SETTLE_STEPS = 60;
154
161
 
162
+ /**
163
+ * The most simulated time one frame may add. Unreal clamps at 1/30 s (`MaxPhysicsDeltaTime`); 1/20 s keeps
164
+ * real time for a 30 fps frame that lands at 34 ms (physics/__tests__/determinism.spec.ts holds 30 and
165
+ * 144 fps to one result) and still bounds an overloaded 60 Hz frame at 3 ticks instead of 5.
166
+ */
167
+ const MAX_PHYSICS_DELTA_SECONDS = 1 / 20;
168
+
155
169
  export class FixedStepLoop {
156
170
  readonly step: number;
157
171
  readonly maxSteps: number;
172
+ readonly maxPhysicsDeltaTime: number;
158
173
  #onBeginFrame: (() => void) | undefined;
159
174
  #onUpdate: (dt: number) => void;
160
175
  #onAfterPhysics: (dt: number) => void;
@@ -204,6 +219,13 @@ export class FixedStepLoop {
204
219
  );
205
220
  }
206
221
  this.maxSteps = maxSteps;
222
+ const maxPhysicsDeltaTime = options.maxPhysicsDeltaTime ?? MAX_PHYSICS_DELTA_SECONDS;
223
+ if (Number.isNaN(maxPhysicsDeltaTime) || maxPhysicsDeltaTime <= 0) {
224
+ throw new Error(
225
+ `FixedStepLoop maxPhysicsDeltaTime must be seconds greater than zero, received ${String(options.maxPhysicsDeltaTime)}.`,
226
+ );
227
+ }
228
+ this.maxPhysicsDeltaTime = maxPhysicsDeltaTime;
207
229
  this.#collectMetrics = options.collectMetrics ?? false;
208
230
  this.#budget = options.budget;
209
231
  this.#spans = options.spans;
@@ -372,7 +394,9 @@ export class FixedStepLoop {
372
394
  }
373
395
  const elapsed = Math.max(0, (now - (this.#lastTime ?? now)) / 1000);
374
396
  this.#lastTime = Math.max(this.#lastTime ?? now, now);
375
- this.#accumulator += elapsed;
397
+ // An overloaded frame (the stress lab at load 4 drew at 12 fps) ran five whole game updates per
398
+ // frame to catch up, so the next frame was slower still; Unreal clamps instead.
399
+ this.#accumulator += Math.min(elapsed, this.maxPhysicsDeltaTime);
376
400
  let updates = 0;
377
401
  while (this.#accumulator + Number.EPSILON >= this.step && updates < this.maxSteps) {
378
402
  this.#interpolation?.beginTick();
@@ -69,6 +69,12 @@ export interface IMergeByMaterialOptions {
69
69
  * trading one draw for a single enormous buffer. See `CHUNK_MERGE_MAX_VERTICES`.
70
70
  */
71
71
  readonly maxGroupVertices?: number;
72
+ /**
73
+ * Told which meshes went into each merged mesh, part by part in the order their triangles sit in
74
+ * the merged buffer (an `InstancedMesh` appears once per instance it expanded into). The caller
75
+ * that detaches the sources uses it to give one back without rebuilding the merge.
76
+ */
77
+ readonly onGroup?: (merged: Mesh, sources: readonly Mesh[]) => void;
72
78
  }
73
79
 
74
80
  /** The channels `mergeByMaterial` keeps, in the order it asks `mergeParts` for them. */
@@ -77,6 +83,7 @@ const MERGEABLE_CHANNELS = ["normal", "uv"] as const;
77
83
  /** One material's parts that will become one mesh, and what that costs. */
78
84
  interface IMergeGroup {
79
85
  readonly parts: IMergePart[];
86
+ readonly sources: Mesh[];
80
87
  triangles: number;
81
88
  vertices: number;
82
89
  }
@@ -727,15 +734,21 @@ export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions
727
734
  open === undefined ||
728
735
  open.vertices + vertices > (options.maxGroupVertices ?? Number.POSITIVE_INFINITY)
729
736
  ) {
730
- const started: IMergeGroup = { parts: [], triangles: 0, vertices: 0 };
737
+ const started: IMergeGroup = { parts: [], sources: [], triangles: 0, vertices: 0 };
731
738
  groups.push(started);
732
739
  return started;
733
740
  }
734
741
  return open;
735
742
  };
736
- const add = (material: Material, part: IMergePart, triangles: number): IMergeGroup => {
743
+ const add = (
744
+ material: Material,
745
+ part: IMergePart,
746
+ triangles: number,
747
+ source: Mesh,
748
+ ): IMergeGroup => {
737
749
  const group = groupFor(material, part);
738
750
  group.parts.push(part);
751
+ group.sources.push(source);
739
752
  group.triangles += triangles;
740
753
  group.vertices += verticesOf(part.geometry);
741
754
  return group;
@@ -751,6 +764,7 @@ export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions
751
764
  renderable.material,
752
765
  { geometry: renderable.geometry, matrix: place },
753
766
  trianglesOf(renderable.geometry),
767
+ renderable,
754
768
  );
755
769
  return;
756
770
  }
@@ -780,6 +794,7 @@ export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions
780
794
  renderable.material,
781
795
  { geometry: instanced.geometry, matrix: place.clone().multiply(instance) },
782
796
  shape,
797
+ instanced,
783
798
  );
784
799
  }
785
800
  });
@@ -797,15 +812,15 @@ export function mergeByMaterial(root: Object3D, options: IMergeByMaterialOptions
797
812
  ? group.parts.some((piece) => has(piece, channel))
798
813
  : group.parts.every((piece) => has(piece, channel)),
799
814
  );
800
- merged.push(
801
- new Mesh(
802
- mergeParts(group.parts, {
803
- label: `${options.label}:${material.name || index}${part === 0 ? "" : `#${part}`}`,
804
- preserve,
805
- }),
806
- material,
807
- ),
815
+ const mesh = new Mesh(
816
+ mergeParts(group.parts, {
817
+ label: `${options.label}:${material.name || index}${part === 0 ? "" : `#${part}`}`,
818
+ preserve,
819
+ }),
820
+ material,
808
821
  );
822
+ options.onGroup?.(mesh, group.sources);
823
+ merged.push(mesh);
809
824
  });
810
825
  });
811
826
  return [...merged, ...kept];
package/src/model-lod.ts CHANGED
@@ -787,6 +787,16 @@ const carriedChains = chainsHost[CHAINS_KEY] as
787
787
  | undefined;
788
788
  const chains: WeakMap<BufferGeometry, IRegisteredChain> = carriedChains ?? new WeakMap();
789
789
  chainsHost[CHAINS_KEY] = chains;
790
+ /**
791
+ * Bumped on every chain registration: the shadow LOD sync re-walks the light root only when this or
792
+ * the hierarchy moved. Without it a chain joined onto a geometry already in the scene (the joined-rung
793
+ * path) would never reach native, and the caster would keep its rung-0 geometry in the shadow.
794
+ */
795
+ const CHAINS_VERSION_KEY = Symbol.for("threenative.discreteLodChainsVersion");
796
+ const bumpChains = (): void => {
797
+ chainsHost[CHAINS_VERSION_KEY] =
798
+ ((chainsHost[CHAINS_VERSION_KEY] as number | undefined) ?? 0) + 1;
799
+ };
790
800
 
791
801
  /**
792
802
  * Geometry preparation commonly clones and bakes a model transform before instancing. Keep the
@@ -826,6 +836,7 @@ function preserveChainClones(registered: IRegisteredChain): void {
826
836
  policy: current.policy,
827
837
  };
828
838
  for (const geometry of levels) chains.set(geometry, copied);
839
+ bumpChains();
829
840
  preserveChainClones(copied);
830
841
  const apply = copy.applyMatrix4.bind(copy);
831
842
  copy.applyMatrix4 = (matrix: Matrix4): BufferGeometry => {
@@ -1041,6 +1052,7 @@ export class DiscreteLodPlugin {
1041
1052
  // Every level, not just the base: a clone made after a selection already swapped the source to
1042
1053
  // a coarser level carries that derived geometry, and must still resolve to this chain.
1043
1054
  for (const geometry of levels) chains.set(geometry, registered);
1055
+ bumpChains();
1044
1056
  preserveChainClones(registered);
1045
1057
  controllers.set(mesh, new ModelLod(mesh, registered.chain, applied));
1046
1058
  appliedCount += 1;
@@ -1123,6 +1135,7 @@ export class DiscreteLodPlugin {
1123
1135
  policy: applied,
1124
1136
  };
1125
1137
  chains.set(member.geometry, registered);
1138
+ bumpChains();
1126
1139
  }
1127
1140
  for (const geometry of registered.chain.levels) geometries.add(geometry);
1128
1141
  }
@@ -1150,6 +1163,7 @@ export class DiscreteLodPlugin {
1150
1163
  // Every level, not just the base: a clone made after a selection already swapped a member to
1151
1164
  // a coarser level carries that derived geometry, and must still resolve to this rung.
1152
1165
  for (const geometry of registered.chain.levels) chains.set(geometry, withJoined);
1166
+ bumpChains();
1153
1167
  // Members that were already managed (a discrete chain) were built before the rung was known;
1154
1168
  // rebuild them with the rung and the authority mark.
1155
1169
  controllers.set(
@@ -56,6 +56,15 @@ export async function openConnection(
56
56
  });
57
57
  try {
58
58
  await Promise.race([Promise.resolve(transport.ready), deadline, cancelled]);
59
+ } catch (error) {
60
+ // A transport created for this attempt must not outlive it: a retry loop against a peer
61
+ // that never becomes ready otherwise accumulates open transports.
62
+ try {
63
+ transport.close();
64
+ } catch {
65
+ /* best effort */
66
+ }
67
+ throw error;
59
68
  } finally {
60
69
  if (timeoutId !== undefined) clearTimeout(timeoutId);
61
70
  normalized.signal?.removeEventListener("abort", onAbort);
@@ -69,11 +78,30 @@ async function establishSession(
69
78
  normalized: INormalizedOptions,
70
79
  ): Promise<INetworkConnection> {
71
80
  const abort = new AbortController();
72
- const timer = setTimeout(() => abort.abort(), normalized.connectTimeoutMs);
81
+ let timedOut = false;
82
+ const timer = setTimeout(() => {
83
+ timedOut = true;
84
+ abort.abort();
85
+ }, normalized.connectTimeoutMs);
86
+ // The caller's signal covers the whole establishment, not just readiness: a stream that never
87
+ // opens or a handshake write held by backpressure must be cancellable and bounded like the
88
+ // handshake read already is.
89
+ const onCallerAbort = (): void => abort.abort();
90
+ normalized.signal?.addEventListener("abort", onCallerAbort, { once: true });
91
+ const interrupted = new Promise<never>((_, reject) => {
92
+ const fail = (): void => reject(new Error("TN_NET_INTERRUPTED: establishment aborted"));
93
+ if (abort.signal.aborted) fail();
94
+ else abort.signal.addEventListener("abort", fail, { once: true });
95
+ });
96
+ // It rejects on cleanup too, where no step is racing it any more.
97
+ interrupted.catch(() => undefined);
98
+ /** Bound one establishment step by the session deadline and cancellation. */
99
+ const bounded = <T>(operation: Promise<T> | T): Promise<T> =>
100
+ Promise.race([Promise.resolve(operation), interrupted]);
73
101
  const readers: FrameReader[] = [];
74
102
  const writers: WritableStream<Uint8Array>[] = [];
75
103
  try {
76
- const controlStream = await Promise.resolve(transport.createBidirectionalStream());
104
+ const controlStream = await bounded(transport.createBidirectionalStream());
77
105
  writers.push(controlStream.writable);
78
106
  const controlReader = new FrameReader(controlStream.readable, MAX_HELLO_BYTES);
79
107
  readers.push(controlReader);
@@ -93,7 +121,7 @@ async function establishSession(
93
121
  );
94
122
  if (helloPayload.length > MAX_HELLO_BYTES)
95
123
  throw invalidArgument("handshake payload exceeds 4096 bytes");
96
- await writeAll(controlStream.writable, encodeFrame(KIND_HELLO, 0, helloPayload));
124
+ await bounded(writeAll(controlStream.writable, encodeFrame(KIND_HELLO, 0, helloPayload)));
97
125
 
98
126
  const welcomeFrame = await controlReader.nextFrame(abort.signal);
99
127
  if (welcomeFrame.kind !== KIND_WELCOME || welcomeFrame.channel !== 0)
@@ -125,11 +153,13 @@ async function establishSession(
125
153
  const reliableReaders = new Map<number, FrameReader>();
126
154
  const reliableWriters = new Map<number, WritableStream<Uint8Array>>();
127
155
  for (const channelId of reliableIds) {
128
- const stream = await Promise.resolve(transport.createBidirectionalStream());
156
+ const stream = await bounded(transport.createBidirectionalStream());
129
157
  writers.push(stream.writable);
130
158
  const reader = new FrameReader(stream.readable, messageLimit);
131
159
  readers.push(reader);
132
- await writeAll(stream.writable, encodeFrame(KIND_BIND, channelId, new Uint8Array(0)));
160
+ await bounded(
161
+ writeAll(stream.writable, encodeFrame(KIND_BIND, channelId, new Uint8Array(0))),
162
+ );
133
163
  const bound = await reader.nextFrame(abort.signal);
134
164
  if (bound.kind !== KIND_BOUND || bound.channel !== channelId)
135
165
  throw new Error("TN_NET_PROTOCOL: expected BOUND");
@@ -138,6 +168,7 @@ async function establishSession(
138
168
  reliableWriters.set(channelId, stream.writable);
139
169
  }
140
170
  clearTimeout(timer);
171
+ normalized.signal?.removeEventListener("abort", onCallerAbort);
141
172
  return createConnection({
142
173
  transport,
143
174
  channelById: new Map(normalized.channels.map((channel) => [channel.id, channel.delivery])),
@@ -152,9 +183,15 @@ async function establishSession(
152
183
  });
153
184
  } catch (error) {
154
185
  clearTimeout(timer);
186
+ normalized.signal?.removeEventListener("abort", onCallerAbort);
155
187
  abort.abort();
188
+ // A stalled stream can also hold its reader's cancel; bound the release so a failed launch
189
+ // settles rather than waiting on the operation that already failed to answer.
156
190
  for (const reader of readers) {
157
- await reader.cancel(error);
191
+ await Promise.race([
192
+ reader.cancel(error).catch(() => undefined),
193
+ new Promise<void>((resolve) => setTimeout(resolve, 50)),
194
+ ]);
158
195
  reader.release();
159
196
  }
160
197
  try {
@@ -163,6 +200,7 @@ async function establishSession(
163
200
  /* best effort */
164
201
  }
165
202
  if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted");
203
+ if (timedOut) throw new Error("TN_NET_TIMEOUT: connect timed out");
166
204
  if (error instanceof Error && error.message.startsWith("TN_NET_")) throw error;
167
205
  if (error instanceof Error) throw new Error(`TN_NET_PROTOCOL: ${error.message}`);
168
206
  throw new Error("TN_NET_UNAVAILABLE: handshake failed");
@@ -230,9 +268,8 @@ function createConnection(established: IEstablished): INetworkConnection {
230
268
  const enqueueReceived = (channel: number, data: Uint8Array): void => {
231
269
  const delivery = established.channelById.get(channel);
232
270
  if (delivery === "reliable-ordered") {
233
- // Reliable saturation pauses reads: the reader loop below stops consuming
234
- // while this queue holds a full window, and never drops.
235
- if (queuedReliableBytesReceived + data.length > established.maxQueuedReliableBytes) return;
271
+ // The pump below waits for room before it calls this, so an already-read reliable frame is
272
+ // never discarded: reliable delivery is ordered and lossless for every accepted message.
236
273
  queuedReliableBytesReceived += data.length;
237
274
  receiveQueue.push({ channel, data });
238
275
  return;
@@ -259,14 +296,21 @@ function createConnection(established: IEstablished): INetworkConnection {
259
296
  try {
260
297
  for (;;) {
261
298
  if (state !== "connected") return;
262
- if (queuedReliableBytesReceived >= established.maxQueuedReliableBytes) {
263
- await new Promise<void>((resolve) => setTimeout(resolve, 5));
264
- continue;
265
- }
266
299
  const frame = await reader.nextFrame();
267
300
  if (frame.kind !== KIND_DATA || frame.channel !== channelId)
268
301
  throw new Error("TN_NET_PROTOCOL: wrong stream frame");
269
- enqueueReceived(frame.channel, frame.payload.slice());
302
+ const payload = frame.payload.slice();
303
+ // A legal frame can be larger than the room left in the window. Hold this one frame and
304
+ // stop reading until a poll frees room, instead of dropping it and delivering the next,
305
+ // smaller one out of order.
306
+ while (
307
+ state === "connected" &&
308
+ queuedReliableBytesReceived + payload.length > established.maxQueuedReliableBytes
309
+ ) {
310
+ await new Promise<void>((resolve) => setTimeout(resolve, 5));
311
+ }
312
+ if (state !== "connected") return;
313
+ enqueueReceived(frame.channel, payload);
270
314
  }
271
315
  } catch {
272
316
  if (state === "connected") markDisconnected("transport error");
@@ -60,6 +60,19 @@ export interface ISpectralOceanOptions {
60
60
  readonly readbackResolution: number;
61
61
  /** Frames between height copies. Ignored when `readbackResolution` is zero. */
62
62
  readonly readbackEveryFrames: number;
63
+ /**
64
+ * The spectrum's shape, as energy per wavenumber cell at `(kx, kz)` in rad/m, replacing Phillips.
65
+ *
66
+ * Each cascade still keeps only its own band, so a custom curve is never counted twice. The game
67
+ * owns the curve — a fetch-limited wind sea, an independent swell — and this runs on the CPU at
68
+ * construction, so it must return a finite, non-negative number or construction throws.
69
+ */
70
+ readonly energy?: (kx: number, kz: number) => number;
71
+ /**
72
+ * The wavenumber, in rad/m, above which surface tension speeds waves up: `ω² = g·k·(1 + (k/km)²)`.
73
+ * Omitted, the dispersion is plain deep water.
74
+ */
75
+ readonly capillaryWavenumber?: number;
63
76
  }
64
77
 
65
78
  /** A height read from the CPU copy, with the age of the frame that produced it. */
@@ -90,6 +103,8 @@ interface ICascadeState {
90
103
 
91
104
  const TWO_PI = Math.PI * 2;
92
105
 
106
+ type SpectralEnergy = (kx: number, kz: number) => number;
107
+
93
108
  function positiveInteger(name: string, value: number): number {
94
109
  if (!Number.isInteger(value) || value <= 0)
95
110
  throw new Error(`SpectralOcean.${name} must be a positive integer.`);
@@ -190,6 +205,7 @@ export function initialSpectrumData(
190
205
  readonly directionality: number;
191
206
  readonly smallWaveCutoff: number;
192
207
  readonly seed: number;
208
+ readonly energy?: SpectralEnergy;
193
209
  },
194
210
  ): Float32Array {
195
211
  const random = createRandom(options.seed);
@@ -211,6 +227,15 @@ export function initialSpectrumData(
211
227
  const spacing = step;
212
228
  const half = resolution / 2;
213
229
  const energyOptions = { ...options, kMin: band.kMin, kMax: band.kMax };
230
+ const energyAt = (kx: number, kz: number): number => {
231
+ if (options.energy === undefined) return phillipsEnergy(kx, kz, energyOptions);
232
+ const kLength = Math.hypot(kx, kz);
233
+ if (kLength < 1e-6 || kLength < band.kMin || kLength >= band.kMax) return 0;
234
+ const energy = options.energy(kx, kz);
235
+ if (!Number.isFinite(energy) || energy < 0)
236
+ throw new Error("SpectralOcean.energy must return a finite, non-negative number.");
237
+ return energy;
238
+ };
214
239
  for (let y = 0; y < resolution; y += 1) {
215
240
  for (let x = 0; x < resolution; x += 1) {
216
241
  const index = y * resolution + x;
@@ -221,9 +246,7 @@ export function initialSpectrumData(
221
246
  // of texels and leaks an imaginary part into the height. One texel row of the shortest
222
247
  // resolvable wave is the whole cost of dropping it.
223
248
  const selfMirrored = x === 0 || y === 0;
224
- const amplitude = selfMirrored
225
- ? 0
226
- : Math.sqrt(phillipsEnergy(kx, kz, energyOptions) / 2) * spacing;
249
+ const amplitude = selfMirrored ? 0 : Math.sqrt(energyAt(kx, kz) / 2) * spacing;
227
250
  data[index * 4] = (gaussian[index * 2] as number) * amplitude;
228
251
  data[index * 4 + 1] = (gaussian[index * 2 + 1] as number) * amplitude;
229
252
 
@@ -233,9 +256,7 @@ export function initialSpectrumData(
233
256
  const mirrorX = (resolution - x) % resolution;
234
257
  const mirrorY = (resolution - y) % resolution;
235
258
  const mirror = mirrorY * resolution + mirrorX;
236
- const mirrorAmplitude = selfMirrored
237
- ? 0
238
- : Math.sqrt(phillipsEnergy(-kx, -kz, energyOptions) / 2) * spacing;
259
+ const mirrorAmplitude = selfMirrored ? 0 : Math.sqrt(energyAt(-kx, -kz) / 2) * spacing;
239
260
  data[index * 4 + 2] = (gaussian[mirror * 2] as number) * mirrorAmplitude;
240
261
  data[index * 4 + 3] = -(gaussian[mirror * 2 + 1] as number) * mirrorAmplitude;
241
262
  }
@@ -338,6 +359,10 @@ export class SpectralOcean extends Object3D implements IComputeDriven {
338
359
  finiteNumber("choppiness", options.choppiness);
339
360
  positiveNumber("smallWaveCutoff", options.smallWaveCutoff);
340
361
  finiteNumber("seed", options.seed);
362
+ if (options.energy !== undefined && typeof options.energy !== "function")
363
+ throw new Error("SpectralOcean.energy must be a function.");
364
+ if (options.capillaryWavenumber !== undefined)
365
+ positiveNumber("capillaryWavenumber", options.capillaryWavenumber);
341
366
  if (!Number.isInteger(options.readbackResolution) || options.readbackResolution < 0)
342
367
  throw new Error("SpectralOcean.readbackResolution must be a non-negative integer.");
343
368
  if (options.readbackResolution > 0) {
@@ -365,7 +390,9 @@ export class SpectralOcean extends Object3D implements IComputeDriven {
365
390
  const state = this.#buildCascade(cascade.patchSize, band, {
366
391
  amplitude: options.amplitude,
367
392
  choppiness: options.choppiness,
393
+ capillaryWavenumber: options.capillaryWavenumber,
368
394
  directionality: options.directionality,
395
+ energy: options.energy,
369
396
  gravity: options.gravity,
370
397
  // Each cascade draws from its own stream so two cascades never share a wave.
371
398
  seed: options.seed + index * 7919,
@@ -497,8 +524,10 @@ export class SpectralOcean extends Object3D implements IComputeDriven {
497
524
  band: { readonly kMin: number; readonly kMax: number },
498
525
  tuning: {
499
526
  readonly amplitude: number;
527
+ readonly capillaryWavenumber: number | undefined;
500
528
  readonly choppiness: number;
501
529
  readonly directionality: number;
530
+ readonly energy: SpectralEnergy | undefined;
502
531
  readonly gravity: number;
503
532
  readonly seed: number;
504
533
  readonly smallWaveCutoff: number;
@@ -536,7 +565,12 @@ export class SpectralOcean extends Object3D implements IComputeDriven {
536
565
  const kx = x.sub(gridSize.mul(0.5)).mul(step);
537
566
  const kz = y.sub(gridSize.mul(0.5)).mul(step);
538
567
  const kLength = kx.mul(kx).add(kz.mul(kz)).sqrt().max(1e-6);
539
- const omega = kLength.mul(tuning.gravity).sqrt().mul(time);
568
+ const deepWater = kLength.mul(tuning.gravity);
569
+ const dispersion =
570
+ tuning.capillaryWavenumber === undefined
571
+ ? deepWater
572
+ : deepWater.mul(kLength.div(tuning.capillaryWavenumber).pow(2).add(1));
573
+ const omega = dispersion.sqrt().mul(time);
540
574
  const cos = omega.cos();
541
575
  const sin = omega.sin();
542
576
  const amplitudes = initial.element(instanceIndex);
package/src/picking.ts CHANGED
@@ -2,6 +2,7 @@ import {
2
2
  type BufferGeometry,
3
3
  type Camera,
4
4
  type Intersection,
5
+ Matrix3,
5
6
  Mesh,
6
7
  type Object3D,
7
8
  Raycaster,
@@ -9,6 +10,7 @@ import {
9
10
  type Vector3,
10
11
  } from "three";
11
12
  import { MeshBVH } from "three-mesh-bvh";
13
+ import { type IAutoBatchPick, autoBatchOf, isAutoBatchMerged } from "./auto-batch.js";
12
14
  import { baseGeometryOf, isLodJoinProxy } from "./model-lod.js";
13
15
  import type { Viewport } from "./viewport.js";
14
16
 
@@ -50,6 +52,14 @@ type AcceleratedRaycaster = Raycaster & { firstHitOnly?: boolean };
50
52
  * Skinned, instanced, batched and morphed meshes fall back to the stock `three` path,
51
53
  * because a hierarchy over their rest positions would report hits in the wrong place.
52
54
  */
55
+ /** True when `object` is `root` or sits somewhere under it. */
56
+ function isWithin(object: Object3D, root: Object3D): boolean {
57
+ for (let node: Object3D | null = object; node !== null; node = node.parent) {
58
+ if (node === root) return true;
59
+ }
60
+ return false;
61
+ }
62
+
53
63
  export class ScenePicker {
54
64
  #camera: Camera;
55
65
  #pointer: () => Vector2;
@@ -64,6 +74,9 @@ export class ScenePicker {
64
74
  #compareHits = (first: Intersection, second: Intersection): number =>
65
75
  first.distance - second.distance;
66
76
  #trees = new WeakMap<BufferGeometry, ICachedTree>();
77
+ /** Merged meshes that answer for hidden sources a ray reached, with the target roots that reached them. */
78
+ #batched = new Map<Mesh, { pick: IAutoBatchPick; roots: Object3D[] }>();
79
+ #normalMatrix = new Matrix3();
67
80
 
68
81
  constructor(options: IScenePickerOptions) {
69
82
  this.#camera = options.camera;
@@ -120,12 +133,15 @@ export class ScenePicker {
120
133
  }
121
134
  }
122
135
  this.#hits.length = 0;
136
+ this.#batched.clear();
123
137
  this.#raycaster.firstHitOnly = single;
124
138
  try {
125
139
  for (const root of this.#roots) {
126
140
  root.updateMatrixWorld();
127
- this.#collect(root, this.#excluded, single);
141
+ this.#collect(root, this.#excluded, single, root);
128
142
  }
143
+ for (const [merged, { pick, roots }] of this.#batched)
144
+ this.#testBatched(merged, pick, roots, this.#excluded);
129
145
  if (!single) this.#hits.sort(this.#compareHits);
130
146
  } finally {
131
147
  this.#raycaster.firstHitOnly = false;
@@ -163,9 +179,18 @@ export class ScenePicker {
163
179
  this.#raycaster.setFromCamera(this.#ndc, this.#camera);
164
180
  }
165
181
 
166
- #collect(object: Object3D, excluded: ReadonlySet<Object3D>, single: boolean): void {
182
+ #collect(
183
+ object: Object3D,
184
+ excluded: ReadonlySet<Object3D>,
185
+ single: boolean,
186
+ root: Object3D,
187
+ ): void {
167
188
  if (excluded.size !== 0 && this.#isExcluded(object, excluded)) return;
168
- if (object.layers.test(this.#raycaster.layers)) {
189
+ const pick = autoBatchOf(object);
190
+ if (pick !== undefined) {
191
+ // A source the engine merged and hid: its merged mesh answers for it, once per ray.
192
+ if (object.layers.test(this.#raycaster.layers)) this.#reach(pick, root);
193
+ } else if (object.layers.test(this.#raycaster.layers)) {
169
194
  if (single) {
170
195
  // The stock fallback ignores `firstHitOnly`, so one object can still push several
171
196
  // intersections; only that object's own nearest survives. The global answer can only
@@ -183,14 +208,56 @@ export class ScenePicker {
183
208
  this.#hitTest(object, this.#hits);
184
209
  }
185
210
  }
186
- for (const child of object.children) this.#collect(child, excluded, single);
211
+ for (const child of object.children) this.#collect(child, excluded, single, root);
212
+ }
213
+
214
+ #reach(pick: IAutoBatchPick, root: Object3D): void {
215
+ const entry = this.#batched.get(pick.merged);
216
+ if (entry === undefined) this.#batched.set(pick.merged, { pick, roots: [root] });
217
+ else if (!entry.roots.includes(root)) entry.roots.push(root);
218
+ }
219
+
220
+ /**
221
+ * One hierarchy test on a merged mesh, answered with the authored sources the ray was asked about.
222
+ *
223
+ * Every hit along the ray is read, not only the nearest: the nearest triangle may belong to a
224
+ * source outside the target set, and a farther one inside it must still be found.
225
+ */
226
+ #testBatched(
227
+ merged: Mesh,
228
+ pick: IAutoBatchPick,
229
+ roots: readonly Object3D[],
230
+ excluded: ReadonlySet<Object3D>,
231
+ ): void {
232
+ const tree = this.#treeFor(merged);
233
+ if (tree === undefined) return;
234
+ const found: Intersection[] = [];
235
+ this.#raycaster.firstHitOnly = false;
236
+ tree.raycastObject3D(merged, this.#raycaster, found);
237
+ for (const hit of found) {
238
+ const source =
239
+ hit.face === null || hit.face === undefined ? undefined : pick.sourceAt(hit.face.a);
240
+ if (source === undefined || !roots.some((root) => isWithin(source, root))) continue;
241
+ if (excluded.size !== 0 && this.#isExcluded(source, excluded)) continue;
242
+ this.#hits.push(this.#asSource(hit, source));
243
+ }
244
+ }
245
+
246
+ /** The hit as the authored source reports it: its object, and a normal in its own space. */
247
+ #asSource(hit: Intersection, source: Object3D): Intersection {
248
+ const face = hit.face as NonNullable<Intersection["face"]>;
249
+ const normal = face.normal
250
+ .clone()
251
+ .applyMatrix3(this.#normalMatrix.getNormalMatrix(source.matrixWorld).invert())
252
+ .normalize();
253
+ return { ...hit, face: { ...face, normal }, faceIndex: undefined, object: source };
187
254
  }
188
255
 
189
256
  #hitTest(object: Object3D, into: Intersection[]): void {
190
257
  // A joined rung inserts a proxy object carrying the collapsed geometry but none of the authored
191
258
  // node identity. Authored primitives are hidden from the render, never from a ray test, so the
192
259
  // proxy must be skipped or a pick at distance would answer with an object the game never added.
193
- if (isLodJoinProxy(object)) return;
260
+ if (isLodJoinProxy(object) || isAutoBatchMerged(object)) return;
194
261
  const tree = this.#treeFor(object);
195
262
  if (tree === undefined) {
196
263
  object.raycast(this.#raycaster, into);
package/src/platform.ts CHANGED
@@ -174,7 +174,11 @@ function browserPlatform(source: unknown): Readonly<IPlatformInfo> {
174
174
 
175
175
  function globalPlatformSource(): IPlatformDetectionSource {
176
176
  const globals = globalThis as Record<string, unknown>;
177
- return { native: globals.__THREENATIVE_NATIVE__, navigator: globals.navigator };
177
+ // In a worker the host copied the page's navigator: a WorkerNavigator has no maxTouchPoints.
178
+ return {
179
+ native: globals.__THREENATIVE_NATIVE__,
180
+ navigator: globals.__tnPageNavigator ?? globals.navigator,
181
+ };
178
182
  }
179
183
 
180
184
  /** Internal source seam for unit tests; it is intentionally not a root package export. */
@@ -208,3 +212,27 @@ export function isMobile(): boolean {
208
212
  export function isTouchscreenAvailable(): boolean {
209
213
  return getPlatform().maxTouchPoints > 0;
210
214
  }
215
+
216
+ /** The page's `window`, or undefined in a worker or on a host without one. Core reads it only here (PRD-752). */
217
+ export function hostWindow(): (Window & typeof globalThis) | undefined {
218
+ return typeof window === "undefined" ? undefined : window;
219
+ }
220
+
221
+ /** Where a user gesture lands: the page's window, or in a worker the input target its host installed. */
222
+ export function hostGestureTarget(): EventTarget | undefined {
223
+ return (
224
+ hostWindow() ??
225
+ (globalThis as { __tnGamePlatform?: { inputTarget?: EventTarget } }).__tnGamePlatform
226
+ ?.inputTarget
227
+ );
228
+ }
229
+
230
+ /** The page's `document`, or undefined in a worker or on a host without one. */
231
+ export function hostDocument(): Document | undefined {
232
+ return typeof document === "undefined" ? undefined : document;
233
+ }
234
+
235
+ /** `ResizeObserver`, or undefined where the host has none. */
236
+ export function hostResizeObserver(): typeof ResizeObserver | undefined {
237
+ return typeof ResizeObserver === "undefined" ? undefined : ResizeObserver;
238
+ }