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(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);