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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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/);+ });+});