Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(net): MessagePortTransport — replication between same-machine realms

esengineab06f162c79b
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 4d8d972cb..c8bee8b64 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -81,6 +81,7 @@ export { ScreenInfo, ScreenOrientation } from './screen';
export {
GameSocket, WeChatSocket, createSocket, NetChannel,
MemoryTransport, createMemoryTransportPair,
+ MessagePortTransport, type MessagePortLike,
type GameSocketOptions, type SocketReadyState, type NetTransport,
type NetChannelOptions, type MessageHandler, type RequestHandler,
type BinaryHandler, type PlatformSocket, type PlatformSocketOptions,
diff --git a/sdk/src/net/MessagePortTransport.ts b/sdk/src/net/MessagePortTransport.ts
new file mode 100644
index 000000000..f15455718
--- /dev/null
+++ b/sdk/src/net/MessagePortTransport.ts
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MessagePortTransport.ts
+ * @brief NetTransport over a MessagePort — replication between same-machine
+ * realms (editor multiplayer preview across play iframes, web
+ * workers) with no socket. Structured clone carries both wire planes
+ * (JSON strings and ArrayBuffer frames) natively, and a port queues
+ * messages until the other end attaches, so wiring order is free.
+ */
+import type { NetTransport } from './NetChannel';
+
+/** The minimal MessagePort surface (structural — works for window and worker
+ * ports). A real DOM MessagePort types its `onmessage` against the full
+ * MessageEvent, which mutable-property variance rejects against this shape,
+ * so the constructor also accepts MessagePort directly. */
+export interface MessagePortLike {
+ postMessage(data: unknown): void;
+ onmessage: ((event: { data: unknown }) => void) | null;
+ close?(): void;
+}
+
+export class MessagePortTransport implements NetTransport {
+ onMessage: ((data: string | ArrayBuffer) => void) | null = null;
+
+ private readonly port_: MessagePortLike;
+
+ constructor(port: MessagePortLike | MessagePort) {
+ this.port_ = port as MessagePortLike;
+ // Assigning onmessage implicitly starts a DOM MessagePort.
+ this.port_.onmessage = (e) => {
+ const d = e.data;
+ if (typeof d === 'string' || d instanceof ArrayBuffer) {
+ this.onMessage?.(d);
+ }
+ };
+ }
+
+ send(data: string | ArrayBuffer): void {
+ this.port_.postMessage(data);
+ }
+
+ close(): void {
+ this.port_.close?.();
+ }
+}
diff --git a/sdk/src/net/index.ts b/sdk/src/net/index.ts
index 2ce97fa9c..5c43ef875 100644
--- a/sdk/src/net/index.ts
+++ b/sdk/src/net/index.ts
@@ -11,6 +11,7 @@ export {
type BinaryHandler,
} from './NetChannel';
export { MemoryTransport, createMemoryTransportPair } from './MemoryTransport';
+export { MessagePortTransport, type MessagePortLike } from './MessagePortTransport';
export type { PlatformSocket, PlatformSocketOptions, PlatformSocketReadyState } from '../platform/types';
export * from './replication';
diff --git a/sdk/tests/net-messageport.test.ts b/sdk/tests/net-messageport.test.ts
new file mode 100644
index 000000000..783348399
--- /dev/null
+++ b/sdk/tests/net-messageport.test.ts
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MessagePortTransport: both NetChannel planes over a real
+ * MessageChannel (the editor multiplayer-preview transport between
+ * play realms). Ports deliver asynchronously, unlike MemoryTransport.
+ */
+import { describe, it, expect } from 'vitest';
+import { NetChannel } from '../src/net/NetChannel';
+import { MessagePortTransport } from '../src/net/MessagePortTransport';
+
+const settle = () => new Promise((r) => setTimeout(r, 0));
+
+describe('MessagePortTransport', () => {
+ it('carries the JSON control plane and RPC across a MessageChannel', async () => {
+ const { port1, port2 } = new MessageChannel();
+ const a = new NetChannel(new MessagePortTransport(port1));
+ const b = new NetChannel(new MessagePortTransport(port2));
+
+ const got: unknown[] = [];
+ b.on('ping', (p) => got.push(p));
+ b.handle('sum', (req) => (req as number[]).reduce((s, n) => s + n, 0));
+
+ a.send('ping', { hello: '世界' });
+ const sum = await a.request<number>('sum', [1, 2, 3]);
+ await settle();
+
+ expect(got).toEqual([{ hello: '世界' }]);
+ expect(sum).toBe(6);
+ port1.close();
+ });
+
+ it('carries binary frames with channel routing intact', async () => {
+ const { port1, port2 } = new MessageChannel();
+ const a = new NetChannel(new MessagePortTransport(port1));
+ const b = new NetChannel(new MessagePortTransport(port2));
+
+ const frames: number[][] = [];
+ b.onBinary(1, (p) => frames.push([...p]));
+ a.sendBinary(1, new Uint8Array([7, 8, 9]));
+ a.sendBinary(2, new Uint8Array([0])); // unregistered channel drops
+ await settle();
+
+ expect(frames).toEqual([[7, 8, 9]]);
+ port1.close();
+ });
+});