@threenative/core 0.3.3 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -0,0 +1,477 @@
1
+ import {
2
+ FrameReader,
3
+ HEADER_BYTES,
4
+ type IDecodedFrame,
5
+ type INormalizedOptions,
6
+ type IWebTransportLike,
7
+ KIND_BIND,
8
+ KIND_BOUND,
9
+ KIND_DATA,
10
+ KIND_HELLO,
11
+ KIND_WELCOME,
12
+ MAX_HELLO_BYTES,
13
+ asBytes,
14
+ decodeStandaloneFrame,
15
+ encodeFrame,
16
+ invalidArgument,
17
+ parseWelcome,
18
+ webTransportConstructor,
19
+ writeAll,
20
+ } from "./net-protocol.js";
21
+ import type { INetworkConnection, INetworkMessage, INetworkPoll, INetworkStats } from "./net.js";
22
+
23
+ export async function openConnection(
24
+ url: string,
25
+ normalized: INormalizedOptions,
26
+ ): Promise<INetworkConnection> {
27
+ if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted before connect");
28
+ const Constructor = webTransportConstructor();
29
+ if (Constructor === undefined) throw new Error("TN_NET_UNAVAILABLE: WebTransport is missing");
30
+
31
+ const transport = new Constructor(url, {});
32
+ let timeoutId: ReturnType<typeof setTimeout> | undefined;
33
+ const onAbort = (): void => {
34
+ try {
35
+ transport.close();
36
+ } catch {
37
+ /* best effort */
38
+ }
39
+ };
40
+ normalized.signal?.addEventListener("abort", onAbort, { once: true });
41
+ const deadline = new Promise<never>((_, reject) => {
42
+ timeoutId = setTimeout(
43
+ () => reject(new Error("TN_NET_TIMEOUT: connect timed out")),
44
+ normalized.connectTimeoutMs,
45
+ );
46
+ });
47
+ const cancelled = new Promise<never>((_, reject) => {
48
+ if (normalized.signal === undefined) return;
49
+ if (normalized.signal.aborted) reject(new Error("TN_NET_CANCELLED: aborted"));
50
+ else
51
+ normalized.signal.addEventListener(
52
+ "abort",
53
+ () => reject(new Error("TN_NET_CANCELLED: aborted")),
54
+ { once: true },
55
+ );
56
+ });
57
+ try {
58
+ await Promise.race([Promise.resolve(transport.ready), deadline, cancelled]);
59
+ } finally {
60
+ if (timeoutId !== undefined) clearTimeout(timeoutId);
61
+ normalized.signal?.removeEventListener("abort", onAbort);
62
+ }
63
+ if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted");
64
+ return establishSession(transport, normalized);
65
+ }
66
+
67
+ async function establishSession(
68
+ transport: IWebTransportLike,
69
+ normalized: INormalizedOptions,
70
+ ): Promise<INetworkConnection> {
71
+ const abort = new AbortController();
72
+ const timer = setTimeout(() => abort.abort(), normalized.connectTimeoutMs);
73
+ const readers: FrameReader[] = [];
74
+ const writers: WritableStream<Uint8Array>[] = [];
75
+ try {
76
+ const controlStream = await Promise.resolve(transport.createBidirectionalStream());
77
+ writers.push(controlStream.writable);
78
+ const controlReader = new FrameReader(controlStream.readable, MAX_HELLO_BYTES);
79
+ readers.push(controlReader);
80
+
81
+ const helloPayload = new TextEncoder().encode(
82
+ JSON.stringify({
83
+ applicationProtocol: normalized.applicationProtocol,
84
+ credential: normalized.credential,
85
+ channels: normalized.channels.map((channel) => ({
86
+ id: channel.id,
87
+ delivery: channel.delivery,
88
+ })),
89
+ maxReliableMessageBytes: normalized.maxReliableMessageBytes,
90
+ maxQueuedReliableBytes: normalized.maxQueuedReliableBytes,
91
+ maxQueuedDatagrams: normalized.maxQueuedDatagrams,
92
+ }),
93
+ );
94
+ if (helloPayload.length > MAX_HELLO_BYTES)
95
+ throw invalidArgument("handshake payload exceeds 4096 bytes");
96
+ await writeAll(controlStream.writable, encodeFrame(KIND_HELLO, 0, helloPayload));
97
+
98
+ const welcomeFrame = await controlReader.nextFrame(abort.signal);
99
+ if (welcomeFrame.kind !== KIND_WELCOME || welcomeFrame.channel !== 0)
100
+ throw new Error("TN_NET_PROTOCOL: expected WELCOME");
101
+ const welcome = parseWelcome(welcomeFrame.payload, normalized.applicationProtocol);
102
+ const expected = [...normalized.channels].sort((left, right) => left.id - right.id);
103
+ const offered = [...welcome.channels].sort((left, right) => left.id - right.id);
104
+ if (JSON.stringify(expected) !== JSON.stringify(offered))
105
+ throw new Error("TN_NET_PROTOCOL: WELCOME channels mismatch");
106
+ const messageLimit = Math.min(
107
+ normalized.maxReliableMessageBytes,
108
+ welcome.maxReliableMessageBytes,
109
+ );
110
+ const queueLimit = Math.min(normalized.maxQueuedReliableBytes, welcome.maxQueuedReliableBytes);
111
+ const datagramLimit = Math.min(normalized.maxQueuedDatagrams, welcome.maxQueuedDatagrams);
112
+ if (messageLimit > queueLimit) throw new Error("TN_NET_PROTOCOL: invalid negotiated limits");
113
+
114
+ const maxDatagramSize = transport.datagrams.maxDatagramSize;
115
+ const maxDatagramPayload =
116
+ typeof maxDatagramSize === "number" && Number.isFinite(maxDatagramSize)
117
+ ? maxDatagramSize - HEADER_BYTES
118
+ : Number.NaN;
119
+ if (!Number.isSafeInteger(maxDatagramPayload) || maxDatagramPayload <= 0)
120
+ throw new Error("TN_NET_UNAVAILABLE: datagram support is missing");
121
+
122
+ const reliableIds = expected
123
+ .filter((channel) => channel.delivery === "reliable-ordered")
124
+ .map((channel) => channel.id);
125
+ const reliableReaders = new Map<number, FrameReader>();
126
+ const reliableWriters = new Map<number, WritableStream<Uint8Array>>();
127
+ for (const channelId of reliableIds) {
128
+ const stream = await Promise.resolve(transport.createBidirectionalStream());
129
+ writers.push(stream.writable);
130
+ const reader = new FrameReader(stream.readable, messageLimit);
131
+ readers.push(reader);
132
+ await writeAll(stream.writable, encodeFrame(KIND_BIND, channelId, new Uint8Array(0)));
133
+ const bound = await reader.nextFrame(abort.signal);
134
+ if (bound.kind !== KIND_BOUND || bound.channel !== channelId)
135
+ throw new Error("TN_NET_PROTOCOL: expected BOUND");
136
+ if (bound.payload.length !== 0) throw new Error("TN_NET_PROTOCOL: BOUND carries payload");
137
+ reliableReaders.set(channelId, reader);
138
+ reliableWriters.set(channelId, stream.writable);
139
+ }
140
+ clearTimeout(timer);
141
+ return createConnection({
142
+ transport,
143
+ channelById: new Map(normalized.channels.map((channel) => [channel.id, channel.delivery])),
144
+ sessionId: welcome.sessionId,
145
+ maxDatagramPayload,
146
+ maxReliableMessageBytes: messageLimit,
147
+ maxQueuedReliableBytes: queueLimit,
148
+ maxQueuedDatagrams: datagramLimit,
149
+ readers,
150
+ reliableReaders,
151
+ reliableWriters,
152
+ });
153
+ } catch (error) {
154
+ clearTimeout(timer);
155
+ abort.abort();
156
+ for (const reader of readers) {
157
+ await reader.cancel(error);
158
+ reader.release();
159
+ }
160
+ try {
161
+ transport.close();
162
+ } catch {
163
+ /* best effort */
164
+ }
165
+ if (normalized.signal?.aborted) throw new Error("TN_NET_CANCELLED: aborted");
166
+ if (error instanceof Error && error.message.startsWith("TN_NET_")) throw error;
167
+ if (error instanceof Error) throw new Error(`TN_NET_PROTOCOL: ${error.message}`);
168
+ throw new Error("TN_NET_UNAVAILABLE: handshake failed");
169
+ }
170
+ }
171
+
172
+ interface IEstablished {
173
+ transport: IWebTransportLike;
174
+ channelById: Map<number, "unreliable" | "reliable-ordered">;
175
+ sessionId: string;
176
+ maxDatagramPayload: number;
177
+ maxReliableMessageBytes: number;
178
+ maxQueuedReliableBytes: number;
179
+ maxQueuedDatagrams: number;
180
+ readers: FrameReader[];
181
+ reliableReaders: Map<number, FrameReader>;
182
+ reliableWriters: Map<number, WritableStream<Uint8Array>>;
183
+ }
184
+
185
+ function createConnection(established: IEstablished): INetworkConnection {
186
+ let state: "connected" | "closing" | "closed" = "connected";
187
+ let disconnectReason: string | null = null;
188
+ let disconnectReported = false;
189
+ let closePromise: Promise<void> | undefined;
190
+ let releasePromise: Promise<void> | undefined;
191
+ let droppedDatagrams = 0;
192
+ let queuedReliableBytes = 0;
193
+ let queuedReliableBytesReceived = 0;
194
+ const pendingReliable = new Map<number, Uint8Array[]>();
195
+ const pendingDatagrams: { channel: number; bytes: Uint8Array }[] = [];
196
+ const receiveQueue: INetworkMessage[] = [];
197
+ let flushScheduled = false;
198
+ for (const channelId of established.reliableReaders.keys()) pendingReliable.set(channelId, []);
199
+
200
+ const statsBase = {
201
+ transport: "webtransport" as const,
202
+ sessionId: established.sessionId,
203
+ maxDatagramPayload: established.maxDatagramPayload,
204
+ maxReliableMessageBytes: established.maxReliableMessageBytes,
205
+ maxQueuedReliableBytes: established.maxQueuedReliableBytes,
206
+ maxQueuedDatagrams: established.maxQueuedDatagrams,
207
+ };
208
+
209
+ const markDisconnected = (reason: string | null): void => {
210
+ if (state === "closed") return;
211
+ state = "closed";
212
+ disconnectReason = reason;
213
+ void releaseAll();
214
+ };
215
+
216
+ const closedReason = (result: unknown): string | null => {
217
+ if (typeof result === "object" && result !== null && "reason" in result) {
218
+ const reason = (result as { reason?: unknown }).reason;
219
+ if (reason === null || reason === undefined) return null;
220
+ if (typeof reason === "string" && reason.length > 0) return reason;
221
+ }
222
+ return "transport closed";
223
+ };
224
+
225
+ void Promise.resolve(established.transport.closed).then(
226
+ (result) => markDisconnected(closedReason(result)),
227
+ () => markDisconnected("transport error"),
228
+ );
229
+
230
+ const enqueueReceived = (channel: number, data: Uint8Array): void => {
231
+ const delivery = established.channelById.get(channel);
232
+ 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;
236
+ queuedReliableBytesReceived += data.length;
237
+ receiveQueue.push({ channel, data });
238
+ return;
239
+ }
240
+ if (delivery !== "unreliable") {
241
+ droppedDatagrams += 1;
242
+ return;
243
+ }
244
+ const unreliableCount = receiveQueue.filter(
245
+ (message) => established.channelById.get(message.channel) === "unreliable",
246
+ ).length;
247
+ if (unreliableCount >= established.maxQueuedDatagrams) {
248
+ const index = receiveQueue.findIndex(
249
+ (message) => established.channelById.get(message.channel) === "unreliable",
250
+ );
251
+ if (index >= 0) receiveQueue.splice(index, 1);
252
+ droppedDatagrams += 1;
253
+ }
254
+ receiveQueue.push({ channel, data });
255
+ };
256
+
257
+ const pumpReliable = (channelId: number, reader: FrameReader): void => {
258
+ void (async () => {
259
+ try {
260
+ for (;;) {
261
+ if (state !== "connected") return;
262
+ if (queuedReliableBytesReceived >= established.maxQueuedReliableBytes) {
263
+ await new Promise<void>((resolve) => setTimeout(resolve, 5));
264
+ continue;
265
+ }
266
+ const frame = await reader.nextFrame();
267
+ if (frame.kind !== KIND_DATA || frame.channel !== channelId)
268
+ throw new Error("TN_NET_PROTOCOL: wrong stream frame");
269
+ enqueueReceived(frame.channel, frame.payload.slice());
270
+ }
271
+ } catch {
272
+ if (state === "connected") markDisconnected("transport error");
273
+ }
274
+ })();
275
+ };
276
+
277
+ let datagramReader: ReadableStreamDefaultReader<Uint8Array> | undefined;
278
+
279
+ const pumpDatagrams = (): void => {
280
+ const reader = established.transport.datagrams.readable.getReader();
281
+ datagramReader = reader;
282
+ void (async () => {
283
+ try {
284
+ for (;;) {
285
+ if (state !== "connected") {
286
+ try {
287
+ reader.releaseLock();
288
+ } catch {
289
+ /* already released */
290
+ }
291
+ datagramReader = undefined;
292
+ return;
293
+ }
294
+ const read = await reader.read();
295
+ if (read.done) {
296
+ markDisconnected("transport closed");
297
+ return;
298
+ }
299
+ let frame: IDecodedFrame;
300
+ try {
301
+ frame = decodeStandaloneFrame(asBytes(read.value).slice());
302
+ } catch {
303
+ droppedDatagrams += 1;
304
+ continue;
305
+ }
306
+ if (
307
+ frame.kind !== KIND_DATA ||
308
+ established.channelById.get(frame.channel) !== "unreliable"
309
+ ) {
310
+ droppedDatagrams += 1;
311
+ continue;
312
+ }
313
+ enqueueReceived(frame.channel, frame.payload.slice());
314
+ }
315
+ } catch {
316
+ if (state === "connected") markDisconnected("transport error");
317
+ }
318
+ })();
319
+ };
320
+
321
+ for (const [channelId, reader] of established.reliableReaders) pumpReliable(channelId, reader);
322
+ pumpDatagrams();
323
+
324
+ const flushQueues = (): void => {
325
+ if (flushScheduled) return;
326
+ flushScheduled = true;
327
+ void Promise.resolve().then(async () => {
328
+ try {
329
+ if (state !== "connected") return;
330
+ while (pendingDatagrams.length > 0) {
331
+ if (state !== "connected") return;
332
+ const next = pendingDatagrams.shift();
333
+ if (next === undefined) return;
334
+ try {
335
+ await writeAll(
336
+ established.transport.datagrams.writable,
337
+ encodeFrame(KIND_DATA, next.channel, next.bytes),
338
+ );
339
+ } catch {
340
+ markDisconnected("transport error");
341
+ return;
342
+ }
343
+ }
344
+ for (const [channelId, queue] of pendingReliable) {
345
+ while (queue.length > 0) {
346
+ if (state !== "connected") return;
347
+ const writer = established.reliableWriters.get(channelId);
348
+ const next = queue.shift();
349
+ if (writer === undefined || next === undefined) break;
350
+ try {
351
+ await writeAll(writer, encodeFrame(KIND_DATA, channelId, next));
352
+ queuedReliableBytes -= next.length;
353
+ } catch {
354
+ markDisconnected("transport error");
355
+ return;
356
+ }
357
+ }
358
+ }
359
+ } finally {
360
+ flushScheduled = false;
361
+ if (
362
+ state === "connected" &&
363
+ (pendingDatagrams.length > 0 ||
364
+ [...pendingReliable.values()].some((queue) => queue.length > 0))
365
+ )
366
+ flushQueues();
367
+ }
368
+ });
369
+ };
370
+
371
+ async function releaseAll(): Promise<void> {
372
+ if (releasePromise !== undefined) return releasePromise;
373
+ releasePromise = (async () => {
374
+ for (const reader of established.readers) {
375
+ try {
376
+ await reader.cancel(new Error("TN_NET_CLOSED: connection closed"));
377
+ } catch {
378
+ /* best effort */
379
+ }
380
+ reader.release();
381
+ }
382
+ if (datagramReader !== undefined) {
383
+ try {
384
+ await datagramReader.cancel(new Error("TN_NET_CLOSED: connection closed"));
385
+ } catch {
386
+ /* best effort */
387
+ }
388
+ try {
389
+ datagramReader.releaseLock();
390
+ } catch {
391
+ /* best effort */
392
+ }
393
+ datagramReader = undefined;
394
+ } else {
395
+ try {
396
+ await established.transport.datagrams.readable.cancel(
397
+ new Error("TN_NET_CLOSED: connection closed"),
398
+ );
399
+ } catch {
400
+ /* best effort */
401
+ }
402
+ }
403
+ try {
404
+ established.transport.close();
405
+ } catch {
406
+ /* best effort */
407
+ }
408
+ })();
409
+ return releasePromise;
410
+ }
411
+
412
+ return {
413
+ send(channel: number, data: Uint8Array): boolean {
414
+ const delivery = established.channelById.get(channel);
415
+ if (delivery === undefined) throw new Error("TN_NET_INVALID_ARGUMENT: unknown channel");
416
+ if (!(data instanceof Uint8Array))
417
+ throw new Error("TN_NET_INVALID_ARGUMENT: data must be bytes");
418
+ if (state !== "connected") throw new Error("TN_NET_CLOSED: connection is closed");
419
+ const bytes = Uint8Array.from(data);
420
+ if (delivery === "reliable-ordered") {
421
+ if (bytes.length > established.maxReliableMessageBytes)
422
+ throw new Error("TN_NET_MESSAGE_TOO_LARGE: reliable message exceeds limit");
423
+ if (queuedReliableBytes + bytes.length > established.maxQueuedReliableBytes) return false;
424
+ pendingReliable.get(channel)?.push(bytes);
425
+ queuedReliableBytes += bytes.length;
426
+ flushQueues();
427
+ return true;
428
+ }
429
+ const payloadLimit = established.maxDatagramPayload;
430
+ if (bytes.length > payloadLimit)
431
+ throw new Error("TN_NET_MESSAGE_TOO_LARGE: datagram exceeds limit");
432
+ if (pendingDatagrams.length >= established.maxQueuedDatagrams) {
433
+ pendingDatagrams.shift();
434
+ droppedDatagrams += 1;
435
+ }
436
+ pendingDatagrams.push({ channel, bytes });
437
+ flushQueues();
438
+ return true;
439
+ },
440
+ poll(): INetworkPoll {
441
+ const room = established.maxQueuedDatagrams * 2;
442
+ const messages = receiveQueue.splice(0, Math.max(0, room));
443
+ queuedReliableBytesReceived = receiveQueue
444
+ .filter((message) => established.channelById.get(message.channel) === "reliable-ordered")
445
+ .reduce((sum, message) => sum + message.data.length, 0);
446
+ if (state === "closed" && !disconnectReported) {
447
+ disconnectReported = true;
448
+ return { messages, disconnected: true, reason: disconnectReason };
449
+ }
450
+ return { messages, disconnected: false, reason: null };
451
+ },
452
+ getStats(): INetworkStats {
453
+ return {
454
+ ...statsBase,
455
+ state,
456
+ queuedReliableBytes,
457
+ queuedDatagrams: pendingDatagrams.length,
458
+ droppedDatagrams,
459
+ rttMs: null,
460
+ };
461
+ },
462
+ close(): Promise<void> {
463
+ if (closePromise !== undefined) return closePromise;
464
+ if (state === "connected") state = "closing";
465
+ closePromise = (async () => {
466
+ receiveQueue.length = 0;
467
+ pendingDatagrams.length = 0;
468
+ for (const queue of pendingReliable.values()) queue.length = 0;
469
+ queuedReliableBytes = 0;
470
+ queuedReliableBytesReceived = 0;
471
+ await releaseAll();
472
+ state = "closed";
473
+ })();
474
+ return closePromise;
475
+ },
476
+ };
477
+ }
package/src/net.ts ADDED
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Optional portable message transport over the platform WebTransport seam.
3
+ *
4
+ * Browser and native share this implementation: WebTransport owns QUIC/HTTP3
5
+ * security and reliability, while this module owns validation, bounded queues,
6
+ * application framing and delivery semantics. Gameplay serialization and
7
+ * simulation stay in game/server code.
8
+ */
9
+
10
+ export interface INetworkChannel {
11
+ id: number;
12
+ delivery: "unreliable" | "reliable-ordered";
13
+ }
14
+
15
+ export interface INetworkOptions {
16
+ applicationProtocol: string;
17
+ credential: string;
18
+ channels: readonly INetworkChannel[];
19
+ signal?: AbortSignal;
20
+ connectTimeoutMs?: number;
21
+ maxReliableMessageBytes?: number;
22
+ maxQueuedReliableBytes?: number;
23
+ maxQueuedDatagrams?: number;
24
+ }
25
+
26
+ export interface INetworkMessage {
27
+ channel: number;
28
+ data: Uint8Array;
29
+ }
30
+
31
+ export interface INetworkPoll {
32
+ messages: INetworkMessage[];
33
+ disconnected: boolean;
34
+ reason: string | null;
35
+ }
36
+
37
+ export interface INetworkStats {
38
+ transport: "webtransport";
39
+ state: "connected" | "closing" | "closed";
40
+ sessionId: string;
41
+ maxDatagramPayload: number;
42
+ maxReliableMessageBytes: number;
43
+ maxQueuedReliableBytes: number;
44
+ maxQueuedDatagrams: number;
45
+ queuedReliableBytes: number;
46
+ queuedDatagrams: number;
47
+ droppedDatagrams: number;
48
+ rttMs: number | null;
49
+ }
50
+
51
+ export interface INetworkConnection {
52
+ send(channel: number, data: Uint8Array): boolean;
53
+ poll(): INetworkPoll;
54
+ getStats(): INetworkStats;
55
+ close(): Promise<void>;
56
+ }
57
+
58
+ import { normalizeOptions } from "./net-protocol.js";
59
+ import { openConnection } from "./net-session.js";
60
+
61
+ /**
62
+ * Open a bounded, authenticated WebTransport message channel shared by browser and native games.
63
+ *
64
+ * @situation connect two game clients over the portable WebTransport seam
65
+ * @situation send ordered actions and bounded unreliable state messages between game clients
66
+ * @situation exchange multiplayer messages without putting replication or gameplay in the engine
67
+ * @constraint the URL must use HTTPS and the credential is supplied by the game's identity flow; this API never issues credentials
68
+ * @constraint channels, message sizes, and queues are validated before WebTransport opens, and reliable overflow returns false
69
+ * @constraint native qualification depends on the installed host WebTransport bridge; iOS remains unverified
70
+ * @override connectTimeoutMs, maxReliableMessageBytes, maxQueuedReliableBytes, and maxQueuedDatagrams are named per-connection limits
71
+ * @example const connection = await connect("https://game.example/game", { applicationProtocol: "my-game/1", credential, channels: [{ id: 1, delivery: "unreliable" }] });
72
+ */
73
+ export function connect(url: string, options: INetworkOptions): Promise<INetworkConnection> {
74
+ try {
75
+ const normalized = normalizeOptions(url, options);
76
+ return openConnection(url, normalized);
77
+ } catch (error) {
78
+ return Promise.reject(error);
79
+ }
80
+ }
@@ -0,0 +1,72 @@
1
+ /**
2
+ * The index arithmetic behind a radix-2 inverse FFT, kept separate from the kernel that runs it.
3
+ *
4
+ * This file holds no GPU code on purpose. An FFT that is subtly wrong produces a field that still
5
+ * looks like water — plausible, animated, and wrong — so the arithmetic has to be checkable
6
+ * against a naive transform on the CPU, where a test can actually see it. The compute kernel in
7
+ * `spectral.ts` walks exactly these stages.
8
+ */
9
+
10
+ /** `log2(n)` when `n` is a power of two, and a thrown error when it is not. */
11
+ export function log2Exact(n: number): number {
12
+ if (!Number.isInteger(n) || n <= 0 || (n & (n - 1)) !== 0) {
13
+ throw new Error(`fft size must be a power of two, received ${n}.`);
14
+ }
15
+ return 31 - Math.clz32(n);
16
+ }
17
+
18
+ /**
19
+ * Where each element must move before the butterflies start.
20
+ *
21
+ * A decimation-in-time FFT reads its input bit-reversed. Doing that as an explicit gather costs
22
+ * one pass and makes every later stage a pure in-place butterfly, which is what lets a GPU run a
23
+ * stage with no barrier inside it.
24
+ */
25
+ export function bitReverseIndices(n: number): Uint32Array {
26
+ const bits = log2Exact(n);
27
+ const indices = new Uint32Array(n);
28
+ for (let index = 0; index < n; index += 1) {
29
+ let reversed = 0;
30
+ for (let bit = 0; bit < bits; bit += 1) {
31
+ reversed = (reversed << 1) | ((index >>> bit) & 1);
32
+ }
33
+ indices[index] = reversed;
34
+ }
35
+ return indices;
36
+ }
37
+
38
+ /** One butterfly pair: the two slots it combines and the twiddle exponent between them. */
39
+ export interface IButterflyPair {
40
+ readonly low: number;
41
+ readonly high: number;
42
+ /** `k` in `exp(+2πi·k / (2·half))` — positive because this is the inverse transform. */
43
+ readonly twiddleIndex: number;
44
+ readonly half: number;
45
+ }
46
+
47
+ /**
48
+ * The pairs one stage combines, for a transform of length `n`.
49
+ *
50
+ * Every pair touches two slots no other pair in the same stage touches, so a stage is race-free
51
+ * in place with one thread per pair. That property is the reason the GPU passes need no scratch
52
+ * buffer and no barrier, and a test that stops checking it would let a silent corruption in.
53
+ */
54
+ export function butterflyPairs(n: number, stage: number): IButterflyPair[] {
55
+ const stages = log2Exact(n);
56
+ if (!Number.isInteger(stage) || stage < 0 || stage >= stages) {
57
+ throw new Error(`fft stage must be within [0, ${stages}), received ${stage}.`);
58
+ }
59
+ const half = 1 << stage;
60
+ const pairs: IButterflyPair[] = [];
61
+ for (let pair = 0; pair < n / 2; pair += 1) {
62
+ const twiddleIndex = pair & (half - 1);
63
+ const low = ((pair >> stage) << (stage + 1)) + twiddleIndex;
64
+ pairs.push({ low, high: low + half, twiddleIndex, half });
65
+ }
66
+ return pairs;
67
+ }
68
+
69
+ /** The number of butterfly stages a transform of length `n` runs. */
70
+ export function butterflyStageCount(n: number): number {
71
+ return log2Exact(n);
72
+ }