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): transport joins the platform seam; NetChannel grows a binary plane — RC11 N1

esengine7c72c10b7212
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 50f9c8af4..8d17a1547 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -80,8 +80,11 @@ export { ScreenInfo, ScreenOrientation } from './screen';
export {
GameSocket, WeChatSocket, createSocket, NetChannel,
+ MemoryTransport, createMemoryTransportPair,
type GameSocketOptions, type SocketReadyState, type NetTransport,
type NetChannelOptions, type MessageHandler, type RequestHandler,
+ type BinaryHandler, type PlatformSocket, type PlatformSocketOptions,
+ type PlatformSocketReadyState,
} from './net';
// =============================================================================
diff --git a/sdk/src/net/GameSocket.ts b/sdk/src/net/GameSocket.ts
index 9fa6e8023..3164add41 100644
--- a/sdk/src/net/GameSocket.ts
+++ b/sdk/src/net/GameSocket.ts
@@ -1,13 +1,12 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-export type SocketReadyState = 'connecting' | 'open' | 'closing' | 'closed';
+import type { PlatformSocket, PlatformSocketOptions, PlatformSocketReadyState } from '../platform/types';
-export interface GameSocketOptions {
- url: string;
- protocols?: string | string[];
-}
+export type SocketReadyState = PlatformSocketReadyState;
+
+export type GameSocketOptions = PlatformSocketOptions;
-export class GameSocket {
+export class GameSocket implements PlatformSocket {
private url_: string;
private protocols_?: string | string[];
private ws_: WebSocket | null = null;
diff --git a/sdk/src/net/MemoryTransport.ts b/sdk/src/net/MemoryTransport.ts
new file mode 100644
index 000000000..1815b2f08
--- /dev/null
+++ b/sdk/src/net/MemoryTransport.ts
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file MemoryTransport.ts
+ * @brief An in-process transport pair — two NetTransports wired to each
+ * other with no socket. This is the replication test seam: a server
+ * App and a client App connect through a pair inside one process and
+ * step deterministically. `manualFlush` holds frames until the test
+ * pumps them, which is how delivery order, latency and packet
+ * interleaving are simulated.
+ */
+import type { NetTransport } from './NetChannel';
+
+export interface MemoryTransportOptions {
+ /** Queue outgoing frames until flush() instead of delivering synchronously. */
+ manualFlush?: boolean;
+}
+
+export class MemoryTransport implements NetTransport {
+ onMessage: ((data: string | ArrayBuffer) => void) | null = null;
+
+ private peer_: MemoryTransport | null = null;
+ private readonly manualFlush_: boolean;
+ private outbox_: (string | ArrayBuffer)[] = [];
+
+ constructor(options: MemoryTransportOptions = {}) {
+ this.manualFlush_ = options.manualFlush ?? false;
+ }
+
+ /** Frames sent but not yet delivered (manualFlush mode). */
+ get pendingCount(): number {
+ return this.outbox_.length;
+ }
+
+ send(data: string | ArrayBuffer): void {
+ if (!this.peer_) return;
+ if (this.manualFlush_) {
+ this.outbox_.push(data);
+ } else {
+ this.peer_.onMessage?.(data);
+ }
+ }
+
+ /** Deliver up to `limit` queued frames to the peer, in send order. */
+ flush(limit = Infinity): void {
+ if (!this.peer_) return;
+ let n = 0;
+ while (this.outbox_.length > 0 && n < limit) {
+ const frame = this.outbox_.shift()!;
+ this.peer_.onMessage?.(frame);
+ n++;
+ }
+ }
+
+ /** Drop queued frames without delivering (packet loss simulation). */
+ dropPending(): void {
+ this.outbox_ = [];
+ }
+
+ static pair(options: MemoryTransportOptions = {}): [MemoryTransport, MemoryTransport] {
+ const a = new MemoryTransport(options);
+ const b = new MemoryTransport(options);
+ a.peer_ = b;
+ b.peer_ = a;
+ return [a, b];
+ }
+}
+
+export function createMemoryTransportPair(
+ options: MemoryTransportOptions = {},
+): [MemoryTransport, MemoryTransport] {
+ return MemoryTransport.pair(options);
+}
diff --git a/sdk/src/net/NetChannel.ts b/sdk/src/net/NetChannel.ts
index cabfc7f50..3bfcc5d4b 100644
--- a/sdk/src/net/NetChannel.ts
+++ b/sdk/src/net/NetChannel.ts
@@ -17,6 +17,7 @@ export interface NetTransport {
export type MessageHandler<T = unknown> = (payload: T) => void;
export type RequestHandler<Req = unknown, Res = unknown> = (payload: Req) => Res | Promise<Res>;
+export type BinaryHandler = (payload: Uint8Array) => void;
export interface NetChannelOptions {
/** Default RPC timeout in ms (0 disables). Default 10000. */
@@ -38,12 +39,17 @@ interface Pending {
* Typed messaging over a {@link NetTransport}. Claims the transport's
* `onMessage` (it is the message router). Events are fire-and-forget; requests
* await a matching response by id (or reject on timeout / remote error).
- * Binary frames are ignored — the envelope is JSON text.
+ *
+ * Two planes share the one transport: string frames carry the JSON control
+ * envelope; binary frames carry a 1-byte channel id + payload for high-rate
+ * data (replication snapshots claim channel 1). A binary frame with no
+ * registered channel handler is dropped.
*/
export class NetChannel {
private readonly transport: NetTransport;
private readonly handlers = new Map<string, Set<MessageHandler>>();
private readonly requestHandlers = new Map<string, RequestHandler>();
+ private readonly binaryHandlers = new Map<number, BinaryHandler>();
private readonly pending = new Map<number, Pending>();
private readonly defaultTimeout: number;
private nextId = 1;
@@ -97,6 +103,25 @@ export class NetChannel {
});
}
+ /** Register the single handler for a binary channel id (0-255). Returns an
+ * unregister function. */
+ onBinary(channel: number, handler: BinaryHandler): () => void {
+ this.binaryHandlers.set(channel, handler);
+ return () => {
+ if (this.binaryHandlers.get(channel) === handler) {
+ this.binaryHandlers.delete(channel);
+ }
+ };
+ }
+
+ /** Fire-and-forget a binary payload on a channel id (0-255). */
+ sendBinary(channel: number, payload: Uint8Array): void {
+ const frame = new Uint8Array(1 + payload.byteLength);
+ frame[0] = channel;
+ frame.set(payload, 1);
+ this.transport.send(frame.buffer);
+ }
+
/** Reject all in-flight requests and drop handlers (call on disconnect). */
dispose(reason = 'net channel closed'): void {
for (const [, p] of this.pending) {
@@ -106,6 +131,7 @@ export class NetChannel {
this.pending.clear();
this.handlers.clear();
this.requestHandlers.clear();
+ this.binaryHandlers.clear();
}
// -- internals ------------------------------------------------------------
@@ -115,7 +141,12 @@ export class NetChannel {
}
private handleIncoming_(data: string | ArrayBuffer): void {
- if (typeof data !== 'string') return; // JSON-text envelope only
+ if (typeof data !== 'string') {
+ const view = new Uint8Array(data);
+ if (view.byteLength === 0) return;
+ this.binaryHandlers.get(view[0])?.(view.subarray(1));
+ return;
+ }
let msg: Wire;
try { msg = JSON.parse(data) as Wire; } catch { return; }
if (!msg || typeof (msg as { k?: unknown }).k !== 'string') return;
diff --git a/sdk/src/net/WeChatSocket.ts b/sdk/src/net/WeChatSocket.ts
index 546208ad4..c980f825d 100644
--- a/sdk/src/net/WeChatSocket.ts
+++ b/sdk/src/net/WeChatSocket.ts
@@ -1,8 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { PlatformSocket } from '../platform/types';
import type { GameSocketOptions, SocketReadyState } from './GameSocket';
-export class WeChatSocket {
+export class WeChatSocket implements PlatformSocket {
private url_: string;
private protocols_?: string | string[];
private task_: any = null;
diff --git a/sdk/src/net/index.ts b/sdk/src/net/index.ts
index e17fc62d3..f10edaa40 100644
--- a/sdk/src/net/index.ts
+++ b/sdk/src/net/index.ts
@@ -8,15 +8,27 @@ export {
type NetChannelOptions,
type MessageHandler,
type RequestHandler,
+ type BinaryHandler,
} from './NetChannel';
+export { MemoryTransport, createMemoryTransportPair } from './MemoryTransport';
+export type { PlatformSocket, PlatformSocketOptions, PlatformSocketReadyState } from '../platform/types';
import { GameSocket, type GameSocketOptions } from './GameSocket';
-import { WeChatSocket } from './WeChatSocket';
+import { isPlatformInitialized, getPlatform } from '../platform/base';
+import type { PlatformSocket } from '../platform/types';
-export function createSocket(options: GameSocketOptions): GameSocket | WeChatSocket {
- const g = globalThis as any;
- if (typeof g.wx !== 'undefined' && typeof g.wx.connectSocket === 'function') {
- return new WeChatSocket(options);
+/**
+ * Open a socket through the platform adapter (web → WebSocket, wechat →
+ * wx.connectSocket, node → ws). A platform without networking fails loud; a
+ * bare host with no adapter set (unit tests) falls back to the browser socket.
+ */
+export function createSocket(options: GameSocketOptions): PlatformSocket {
+ if (isPlatformInitialized()) {
+ const platform = getPlatform();
+ if (!platform.createSocket) {
+ throw new Error(`[net] platform "${platform.name}" has no socket support`);
+ }
+ return platform.createSocket(options);
}
return new GameSocket(options);
}
diff --git a/sdk/src/platform/base.ts b/sdk/src/platform/base.ts
index 47335188d..86f1b22a6 100644
--- a/sdk/src/platform/base.ts
+++ b/sdk/src/platform/base.ts
@@ -44,7 +44,7 @@ export function isPlatformInitialized(): boolean {
/**
* Get platform type
*/
-export function getPlatformType(): 'web' | 'wechat' | null {
+export function getPlatformType(): PlatformAdapter['name'] | null {
return currentPlatform?.name ?? null;
}
diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.ts
index a94bb698f..23ad63a24 100644
--- a/sdk/src/platform/types.ts
+++ b/sdk/src/platform/types.ts
@@ -82,12 +82,39 @@ export interface ImageLoadResult {
pixels: Uint8Array;
}
+// =============================================================================
+// Sockets
+// =============================================================================
+
+export type PlatformSocketReadyState = 'connecting' | 'open' | 'closing' | 'closed';
+
+export interface PlatformSocketOptions {
+ url: string;
+ protocols?: string | string[];
+}
+
+/**
+ * The platform-neutral socket surface (GameSocket / WeChatSocket / a Node ws
+ * wrapper all fit): callback-based, queues sends until open, moves
+ * string|ArrayBuffer frames.
+ */
+export interface PlatformSocket {
+ readyState: PlatformSocketReadyState;
+ onOpen: (() => void) | null;
+ onMessage: ((data: string | ArrayBuffer) => void) | null;
+ onClose: ((code: number, reason: string) => void) | null;
+ onError: ((error: unknown) => void) | null;
+ connect(): void;
+ send(data: string | ArrayBuffer): void;
+ close(code?: number, reason?: string): void;
+}
+
// =============================================================================
// Platform Adapter Interface
// =============================================================================
export interface PlatformAdapter {
- readonly name: 'web' | 'wechat';
+ readonly name: 'web' | 'wechat' | 'node';
fetch(url: string, options?: PlatformRequestOptions): Promise<PlatformResponse>;
@@ -124,6 +151,11 @@ export interface PlatformAdapter {
* concept (web) omit it and lazy groups load directly from their URLs. */
loadSubpackage?(name: string): Promise<void>;
+ /** Open a socket connection. Web → WebSocket, WeChat → wx.connectSocket,
+ * Node → a ws wrapper. Optional — platforms without networking (playable
+ * ads) omit it and `createSocket()` fails loud. */
+ createSocket?(options: PlatformSocketOptions): PlatformSocket;
+
/** Subscribe to OS memory-pressure warnings; returns an unsubscribe.
* WeChat → wx.onMemoryWarning; platforms without a pressure signal (web)
* omit it. Residency caches subscribe to drop their evictable entries. */
diff --git a/sdk/src/platform/web.ts b/sdk/src/platform/web.ts
index 930e44bbb..5adba4fa1 100644
--- a/sdk/src/platform/web.ts
+++ b/sdk/src/platform/web.ts
@@ -13,9 +13,12 @@ import type {
InputEventCallbacks,
GamepadSnapshot,
ImageLoadResult,
+ PlatformSocket,
+ PlatformSocketOptions,
} from './types';
import { WebAudioBackend } from '../audio/WebAudioBackend';
import type { PlatformAudioBackend } from '../audio/PlatformAudioBackend';
+import { GameSocket } from '../net/GameSocket';
const WHEEL_LINE_HEIGHT = 16;
@@ -273,6 +276,10 @@ class WebPlatformAdapter implements PlatformAdapter {
return new WebAudioBackend();
}
+ createSocket(options: PlatformSocketOptions): PlatformSocket {
+ return new GameSocket(options);
+ }
+
getStorageItem(key: string): string | null {
return localStorage.getItem(key);
}
diff --git a/sdk/src/platform/wechat/index.ts b/sdk/src/platform/wechat/index.ts
index 03644fddb..36fabc7a8 100644
--- a/sdk/src/platform/wechat/index.ts
+++ b/sdk/src/platform/wechat/index.ts
@@ -14,7 +14,10 @@ import type {
WasmInstantiateResult,
InputEventCallbacks,
ImageLoadResult,
+ PlatformSocket,
+ PlatformSocketOptions,
} from '../types';
+import { WeChatSocket } from '../../net/WeChatSocket';
import { WeChatAudioBackend } from '../../audio/WeChatAudioBackend';
import type { PlatformAudioBackend } from '../../audio/PlatformAudioBackend';
import { wxFetch, polyfillFetch } from './fetch';
@@ -170,6 +173,10 @@ class WeChatPlatformAdapter implements PlatformAdapter {
return new WeChatAudioBackend();
}
+ createSocket(options: PlatformSocketOptions): PlatformSocket {
+ return new WeChatSocket(options);
+ }
+
getStorageItem(key: string): string | null {
try {
const value = wx.getStorageSync(key);
diff --git a/sdk/tests/net-binary.test.ts b/sdk/tests/net-binary.test.ts
new file mode 100644
index 000000000..381b81e51
--- /dev/null
+++ b/sdk/tests/net-binary.test.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file N1 transport base for replication: the NetChannel binary plane
+ * (1-byte channel id frames beside the JSON control plane), the
+ * MemoryTransport in-process pair, and the platform-adapter socket
+ * factory.
+ */
+import { describe, it, expect } from 'vitest';
+import { NetChannel } from '../src/net/NetChannel';
+import { MemoryTransport } from '../src/net/MemoryTransport';
+import { createSocket } from '../src/net';
+import { setPlatform, isPlatformInitialized } from '../src/platform/base';
+import type { PlatformAdapter, PlatformSocket } from '../src/platform/types';
+
+function channelPair(): [NetChannel, NetChannel] {
+ const [ta, tb] = MemoryTransport.pair();
+ return [new NetChannel(ta), new NetChannel(tb)];
+}
+
+describe('NetChannel binary plane', () => {
+ it('routes a binary frame by its channel id, payload intact', () => {
+ const [a, b] = channelPair();
+ const got: Uint8Array[] = [];
+ b.onBinary(1, (p) => got.push(p.slice()));
+ a.sendBinary(1, new Uint8Array([10, 20, 30]));
+ expect(got).toHaveLength(1);
+ expect([...got[0]]).toEqual([10, 20, 30]);
+ });
+
+ it('channels are isolated; unregistered channels drop silently', () => {
+ const [a, b] = channelPair();
+ const ch1: number[] = [];
+ b.onBinary(1, (p) => ch1.push(p.byteLength));
+ a.sendBinary(2, new Uint8Array([1, 2, 3]));
+ a.sendBinary(1, new Uint8Array([9]));
+ expect(ch1).toEqual([1]);
+ });
+
+ it('the JSON control plane and the binary plane share one transport', () => {
+ const [a, b] = channelPair();
+ const events: unknown[] = [];
+ const frames: number[] = [];
+ b.on('hello', (p) => events.push(p));
+ b.onBinary(1, (p) => frames.push(p.byteLength));
+ a.send('hello', { v: 1 });
+ a.sendBinary(1, new Uint8Array(8));
+ a.send('hello', { v: 2 });
+ expect(events).toEqual([{ v: 1 }, { v: 2 }]);
+ expect(frames).toEqual([8]);
+ });
+
+ it('an empty binary frame is ignored', () => {
+ const [ta, tb] = MemoryTransport.pair();
+ const b = new NetChannel(tb);
+ let hits = 0;
+ b.onBinary(0, () => hits++);
+ ta.send(new ArrayBuffer(0));
+ // channel 0 with empty payload still routes (1-byte frame = id only)
+ const a = new NetChannel(ta);
+ a.sendBinary(0, new Uint8Array(0));
+ expect(hits).toBe(1);
+ });
+
+ it('dispose drops binary handlers', () => {
+ const [a, b] = channelPair();
+ let hits = 0;
+ b.onBinary(1, () => hits++);
+ b.dispose();
+ a.sendBinary(1, new Uint8Array([1]));
+ expect(hits).toBe(0);
+ });
+});
+
+describe('MemoryTransport manual flush', () => {
+ it('holds frames until flushed, delivers in send order with a limit', () => {
+ const [ta, tb] = MemoryTransport.pair({ manualFlush: true });
+ const got: string[] = [];
+ tb.onMessage = (d) => got.push(d as string);
+ ta.send('1'); ta.send('2'); ta.send('3');
+ expect(got).toEqual([]);
+ expect(ta.pendingCount).toBe(3);
+ ta.flush(2);
+ expect(got).toEqual(['1', '2']);
+ ta.flush();
+ expect(got).toEqual(['1', '2', '3']);
+ });
+
+ it('dropPending simulates packet loss', () => {
+ const [ta, tb] = MemoryTransport.pair({ manualFlush: true });
+ const got: string[] = [];
+ tb.onMessage = (d) => got.push(d as string);
+ ta.send('lost');
+ ta.dropPending();
+ ta.flush();
+ expect(got).toEqual([]);
+ });
+});
+
+describe('createSocket platform seam', () => {
+ it('delegates to the platform adapter when one is set', () => {
+ expect(isPlatformInitialized()).toBe(false);
+ const marker = { readyState: 'closed' } as PlatformSocket;
+ const urls: string[] = [];
+ setPlatform({
+ name: 'web',
+ createSocket: (o) => { urls.push(o.url); return marker; },
+ } as unknown as PlatformAdapter);
+ expect(createSocket({ url: 'wss://x' })).toBe(marker);
+ expect(urls).toEqual(['wss://x']);
+ });
+
+ it('fails loud on a platform without socket support', () => {
+ setPlatform({ name: 'web' } as unknown as PlatformAdapter);
+ expect(() => createSocket({ url: 'wss://x' })).toThrow(/no socket support/);
+ });
+});