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(sdk): stability tiers land on the public surface — net, material graph, and headless go @beta
esengine8422687323ad
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 6ae62ab9b..0f9944152 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -61,6 +61,8 @@ export {type AddressableManifest,type AddressableManifestGroup,type AddressableManifestAsset,+ contentHashHex,+ contentHashOf,type BundleMode,BUNDLE_MODES,normalizeBundleMode,diff --git a/sdk/src/index.node.ts b/sdk/src/index.node.tsindex a931269c6..2d79e133e 100644--- a/sdk/src/index.node.ts+++ b/sdk/src/index.node.ts@@ -33,6 +33,8 @@ export { nodeAdapter } from './platform/node';* Load the engine wasm module from a directory holding the web build* artifacts (esengine.js + esengine.wasm) — the emscripten glue runs natively* under Node. `dir` is filesystem-relative to the process cwd.+ *+ * @beta Pre-1.0: the node/headless entry is young; the loading shape may change.*/export async function loadEsengineModule(dir: string): Promise<ESEngineModule> {const { readFile } = await import('node:fs/promises');diff --git a/sdk/src/materialGraph.ts b/sdk/src/materialGraph.tsindex 21b799387..931d954f2 100644--- a/sdk/src/materialGraph.ts+++ b/sdk/src/materialGraph.ts@@ -11,6 +11,8 @@* alike. The vertex stage is fixed (2D bakes the transform into the batch vertices); the* programmable surface is the fragment, which this compiler builds by topologically* walking the node DAG from the output.+ *+ * @beta Pre-1.0: the material-graph node set and serialized shape may still change.*//** A node's GLSL output type. Determines how it combines and how it promotes to fragColor. */diff --git a/sdk/src/net/GameSocket.ts b/sdk/src/net/GameSocket.tsindex 3164add41..df22f46fd 100644--- a/sdk/src/net/GameSocket.ts+++ b/sdk/src/net/GameSocket.ts@@ -1,5 +1,11 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file GameSocket.ts+ * @brief Raw browser-WebSocket wrapper behind the platform socket seam.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.+ */import type { PlatformSocket, PlatformSocketOptions, PlatformSocketReadyState } from '../platform/types';export type SocketReadyState = PlatformSocketReadyState;diff --git a/sdk/src/net/MemoryTransport.ts b/sdk/src/net/MemoryTransport.tsindex 1815b2f08..ba34803b4 100644--- a/sdk/src/net/MemoryTransport.ts+++ b/sdk/src/net/MemoryTransport.ts@@ -8,6 +8,8 @@* step deterministically. `manualFlush` holds frames until the test* pumps them, which is how delivery order, latency and packet* interleaving are simulated.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { NetTransport } from './NetChannel';diff --git a/sdk/src/net/MessagePortTransport.ts b/sdk/src/net/MessagePortTransport.tsindex f15455718..2b68ab6df 100644--- a/sdk/src/net/MessagePortTransport.ts+++ b/sdk/src/net/MessagePortTransport.ts@@ -7,6 +7,8 @@* 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.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { NetTransport } from './NetChannel';diff --git a/sdk/src/net/NetChannel.ts b/sdk/src/net/NetChannel.tsindex 3bfcc5d4b..8f066dc45 100644--- a/sdk/src/net/NetChannel.ts+++ b/sdk/src/net/NetChannel.ts@@ -7,6 +7,8 @@* is the single channel that gives them typed events (`on`/`send`) and* RPC (`handle`/`request`) with a small JSON envelope. Transport-* agnostic — anything that can `send` and surface `onMessage` works.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*//** The minimal socket surface NetChannel drives (GameSocket / WeChatSocket fit). */diff --git a/sdk/src/net/WeChatSocket.ts b/sdk/src/net/WeChatSocket.tsindex c980f825d..0fac4c17d 100644--- a/sdk/src/net/WeChatSocket.ts+++ b/sdk/src/net/WeChatSocket.ts@@ -1,5 +1,11 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file WeChatSocket.ts+ * @brief Raw wx.connectSocket wrapper behind the platform socket seam.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.+ */import type { PlatformSocket } from '../platform/types';import type { GameSocketOptions, SocketReadyState } from './GameSocket';diff --git a/sdk/src/net/index.ts b/sdk/src/net/index.tsindex 5c43ef875..287edbb9a 100644--- a/sdk/src/net/index.ts+++ b/sdk/src/net/index.ts@@ -1,5 +1,11 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file index.ts+ * @brief Networking barrel: sockets, transports, NetChannel, replication.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.+ */export { GameSocket, type GameSocketOptions, type SocketReadyState } from './GameSocket';export { WeChatSocket } from './WeChatSocket';export {diff --git a/sdk/src/net/replication/NetIds.ts b/sdk/src/net/replication/NetIds.tsindex 7d1f431d1..e45024363 100644--- a/sdk/src/net/replication/NetIds.ts+++ b/sdk/src/net/replication/NetIds.ts@@ -6,6 +6,8 @@* generation|index, recycled on despawn), so the wire never carries* them — a server-allocated NetId is the one cross-machine identity,* and each endpoint keeps this bidirectional table.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { Entity } from '../../types';diff --git a/sdk/src/net/replication/ReplicationPlugin.ts b/sdk/src/net/replication/ReplicationPlugin.tsindex 7c03fc306..399ac410d 100644--- a/sdk/src/net/replication/ReplicationPlugin.ts+++ b/sdk/src/net/replication/ReplicationPlugin.ts@@ -8,6 +8,8 @@* FixedPostUpdate samples + broadcasts. Role gating is a resource,* not an environment flag: everything no-ops while NetRole stays* 'offline', so the plugin is safe to install unconditionally.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { App, Plugin } from '../../app';import { defineSystem, Schedule } from '../../system';diff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.tsindex ad80f49da..16443d2e9 100644--- a/sdk/src/net/replication/client.ts+++ b/sdk/src/net/replication/client.ts@@ -8,6 +8,8 @@* frames to apply at the FixedPreUpdate boundary — state lands at a* deterministic point in the frame, not mid-schedule on socket* timing.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { World } from '../../world';import type { Entity } from '../../types';diff --git a/sdk/src/net/replication/codec.ts b/sdk/src/net/replication/codec.tsindex 2197295d7..09734f309 100644--- a/sdk/src/net/replication/codec.ts+++ b/sdk/src/net/replication/codec.ts@@ -18,6 +18,8 @@* string → u16 len + utf8, plain object → keys recursively in* declaration order, entity-ref field → u32 netId (remapped at both* ends), anything else → JSON string fallback.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import { getComponentRegistry, type AnyComponentDef } from '../../component';import { REPLICATION_PROTOCOL_VERSION, type ReplComponentSchema } from './protocol';diff --git a/sdk/src/net/replication/components.ts b/sdk/src/net/replication/components.tsindex 25d6d395c..bf4857776 100644--- a/sdk/src/net/replication/components.ts+++ b/sdk/src/net/replication/components.ts@@ -8,6 +8,8 @@* annotations / metadata), not here. `NetGhost` tags the client-side* proxies so local simulation (physics, AI) can yield to the incoming* authoritative state via Without(NetGhost) queries.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import { defineComponent, defineTag } from '../../component';diff --git a/sdk/src/net/replication/interpolation.ts b/sdk/src/net/replication/interpolation.tsindex 3c3da886a..52f06d035 100644--- a/sdk/src/net/replication/interpolation.ts+++ b/sdk/src/net/replication/interpolation.ts@@ -10,6 +10,8 @@* across frame-rate mismatch and delivery jitter. Continuous values* lerp (f32 scalars, f32 leaves of vectors, quats via nlerp);* discrete values hold until their sample time passes.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { FieldShape } from './codec';diff --git a/sdk/src/net/replication/protocol.ts b/sdk/src/net/replication/protocol.tsindex 4e6d62fc8..6a320d468 100644--- a/sdk/src/net/replication/protocol.ts+++ b/sdk/src/net/replication/protocol.ts@@ -8,6 +8,8 @@* channel {@link REPLICATION_CHANNEL} (see codec.ts for the frame* layout). Version or schema drift refuses the connection at* handshake — never a silently mismatched simulation.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { SceneComponentData } from '../../scene';diff --git a/sdk/src/net/replication/server.ts b/sdk/src/net/replication/server.tsindex 58490ea77..ed44a5171 100644--- a/sdk/src/net/replication/server.ts+++ b/sdk/src/net/replication/server.ts@@ -8,6 +8,8 @@* and diffs replicated fields against a shadow copy to broadcast a* binary delta frame. WebSocket transports are reliable+ordered, so* delta-since-last-send needs no ack protocol.+ *+ * @beta Pre-1.0 networking: client prediction and interest management will reshape this surface.*/import type { World } from '../../world';import type { Entity } from '../../types';diff --git a/sdk/src/platform/node.ts b/sdk/src/platform/node.tsindex eb5a1f524..47ede45a0 100644--- a/sdk/src/platform/node.ts+++ b/sdk/src/platform/node.ts@@ -8,6 +8,8 @@* WebSocket (Node ≥ 22), silent audio, no DOM. Anything that* fundamentally needs a render host (image decode, canvas) fails* loud rather than pretending.+ *+ * @beta Pre-1.0: the node/headless host is young; the adapter surface may change.*/import { readFile as fsReadFile, access } from 'node:fs/promises';import type {diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.tsindex 85a9a4e14..07e62dffb 100644--- a/sdk/src/webAppFactory.ts+++ b/sdk/src/webAppFactory.ts@@ -96,6 +96,9 @@ const headlessBasePlugins = (): Plugin[] => [* shape (same wasm module, same gameplay code, same fixed-tick loop) — also* useful for workers and tests. Drive it with {@link runHeadless} or* `app.tick(dt)`.+ *+ * @beta Pre-1.0: the headless asset story (gameplay data without textures)+ * is still settling and may change this factory's options.*/export function createHeadlessApp(module: ESEngineModule, options?: HeadlessAppOptions): App {seedEngineComponents();@@ -118,6 +121,8 @@ export function createHeadlessApp(module: ESEngineModule, options?: HeadlessAppO* Drive an app on a wall-clock interval (no requestAnimationFrame on a* server). Delta is measured, so the fixed-step accumulator keeps simulation* cadence exact across timer jitter. Returns a stop function.+ *+ * @beta Pre-1.0: paired with {@link createHeadlessApp}, evolves with it.*/export function runHeadless(app: App, options?: { fps?: number }): () => void {const intervalMs = 1000 / (options?.fps ?? 60);