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(examples): multiplayer-arena runs on client prediction
yhh482601740fa0
diff --git a/desktop/electron/main.ts b/desktop/electron/main.tsindex 0178ed6ad..806a80983 100644--- a/desktop/electron/main.ts+++ b/desktop/electron/main.ts@@ -192,6 +192,11 @@ async function runScreenshot(w: BrowserWindow, out: string): Promise<void> {}}if (process.env.ESTELLA_SHOT_PLAY) {+ // Multiplayer preview: pick the player count before entering Play+ // (2-4 = listen server + client realms, each its own estella:// frame).+ if (process.env.ESTELLA_SHOT_PLAYERS) {+ await exec(`window.__estellaEditor.setPlayPlayers(${Number(process.env.ESTELLA_SHOT_PLAYERS)})`);+ }await exec('window.__estellaEditor.play()');await waitFor('window.__estellaEditor.playState().ready || !!window.__estellaEditor.playState().error', 'play realm ready', 20000);const err = await exec('window.__estellaEditor.playState().error');@@ -235,9 +240,13 @@ async function runScreenshot(w: BrowserWindow, out: string): Promise<void> {// reach the iframe. Lets a shot drive gameplay input, e.g. dispatching// KeyboardEvents on the frame's document.if (process.env.ESTELLA_SHOT_PLAY_EVAL) {- const playFrame = w.webContents.mainFrame.frames.find((f) => f.url.startsWith('estella://'));+ // ESTELLA_SHOT_PLAY_FRAME picks which play realm the eval targets when a+ // multiplayer preview runs several (0 = the host, 1+ = client realms).+ const frameIndex = Number(process.env.ESTELLA_SHOT_PLAY_FRAME ?? '0');+ const playFrames = w.webContents.mainFrame.frames.filter((f) => f.url.startsWith('estella://'));+ const playFrame = playFrames[frameIndex];if (!playFrame) {- console.log('[playEval] no estella:// play frame found');+ console.log(`[playEval] no estella:// play frame at index ${frameIndex} (${playFrames.length} present)`);} else {const result = await playFrame.executeJavaScript(process.env.ESTELLA_SHOT_PLAY_EVAL)diff --git a/desktop/src/main.tsx b/desktop/src/main.tsxindex 90feb0d41..42954a3b5 100644--- a/desktop/src/main.tsx+++ b/desktop/src/main.tsx@@ -73,6 +73,8 @@ if (new URLSearchParams(location.search).has('automation')) {selectAsset: (path: string | null) => useSelection.getState().selectAsset(path),play: () => useEditorStore.getState().togglePlay(),playState: () => PlayRealm.getSnapshot(),+ /** Player count for the next Play (1 = single, 2-4 = listen server + clients). */+ setPlayPlayers: (n: number) => useEditorStore.getState().setPlayPlayers(n),reveal: (id: string) => dockApi.revealAndExpand(id),togglePerfOverlay: () => PerfMonitor.toggleOverlay(),captureThumbnail: () => ProjectStore.captureThumbnail(),diff --git a/docs/astro/src/content/docs/guides/networking.mdx b/docs/astro/src/content/docs/guides/networking.mdxindex 590c71212..6d1a321c6 100644--- a/docs/astro/src/content/docs/guides/networking.mdx+++ b/docs/astro/src/content/docs/guides/networking.mdx@@ -113,7 +113,7 @@ clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // per-tick input uplin- **Dedicated servers**: the same gameplay code runs headless under Node —`import { loadEsengineModule, createHeadlessApp, runHeadless } from 'esengine/node'`.-See the **Multiplayer Arena** example for the full pattern in ~100 lines.+See the **Multiplayer Arena** example for the full pattern — replication, per-tick input, and client prediction — in ~130 lines.### Interest management — who sees whatdiff --git a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx b/docs/astro/src/content/docs/zh-cn/guides/networking.mdxindex 1331e3cb0..9f1fb2188 100644--- a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/networking.mdx@@ -110,7 +110,7 @@ clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // 每 tick 输入上- **专用服务器**:同一份玩法代码可在 Node 下无头运行——`import { loadEsengineModule, createHeadlessApp, runHeadless } from 'esengine/node'`。-完整范式见 **Multiplayer Arena** 示例(约 100 行)。+完整范式(复制、每 tick 输入、客户端预测)见 **Multiplayer Arena** 示例(约 130 行)。### 兴趣管理——谁看见什么diff --git a/examples/README.md b/examples/README.mdindex c340b59e4..d7ef434d8 100644--- a/examples/README.md+++ b/examples/README.md@@ -35,7 +35,7 @@ for your own game.| **ui-layout** | UI | Flexbox-style responsive UI layout. || **ui-list** | UI | A virtualized list and grid — `createListView`, live data, `scrollToIndex`. || **enemy-ai** | AI | A state machine drives enemies to patrol, sense the player, and chase via A* navigation. |-| **multiplayer-arena** | Networking | Server-authoritative multiplayer: each player steers a replicated pawn ('2 Players' in the Play dropdown runs listen server + client). |+| **multiplayer-arena** | Networking | Server-authoritative multiplayer with client prediction: each player steers a replicated pawn, own-pawn input applies instantly ('2 Players' in the Play dropdown runs listen server + client). || **platformer** | Game | A tiny platformer — run, jump and collect coins. || **space-shooter** | Game | A vertical shmup with prefabs, a HUD and a difficulty ramp. |diff --git a/examples/multiplayer-arena/README.md b/examples/multiplayer-arena/README.mdindex 1d40f644c..b3a33c4a6 100644--- a/examples/multiplayer-arena/README.md+++ b/examples/multiplayer-arena/README.md@@ -1,7 +1,8 @@# Multiplayer Arena-Server-authoritative multiplayer in ~100 lines: each player steers a colored-pawn inside an arena, replicated to every other player.+Server-authoritative multiplayer **with client prediction** in ~130 lines: each+player steers a colored pawn inside an arena, replicated to every other player+— and your own pawn responds the moment a key goes down, no round trip.## Run it@@ -17,11 +18,18 @@ Plain **Single Player** Play works too: the same systems run offline.- `Replicated` marks an entity for replication — the spawn carries everycomponent (the sprite color included), and Transform's built-in `replicated`annotation streams the pose as binary deltas with snapshot interpolation.-- The authority is the only simulator: `movePawnsSystem` integrates every pawn,- reading the local keyboard for the host and `server.inputOf(connection)` for- remote players (`Replicated.owner` routes input to its pawn).-- Clients run one system: sample the keyboard, `client.sendInput(...)` once per- fixed tick. Everything they see — their own pawn included — is replicated,- authoritative state.+- **One movement rule, both ends**: `applyMove` is the single function the+ authority runs per pawn AND the client's prediction function — the bounds+ clamp included, so even the arena walls are predicted.+- The authority consumes each connection's input queue with+ `server.tickInputOf(connection)` — exactly one command per fixed tick, the+ contract prediction replays against (`Replicated.owner` routes input to its+ pawn).+- Clients run one system: sample the keyboard, enable prediction lazily (the+ editor preview makes the connection itself, so `client.enablePrediction`+ happens in-game), and `client.sendInput(...)` once per fixed tick — idle+ moves included. Remote pawns stay smooth via snapshot interpolation; your+ own pawn bypasses it and moves instantly, reconciled against the+ authoritative state every tick.- The same gameplay code ships unchanged against a real WebSocket server(`esengine/node` + `createHeadlessApp`).diff --git a/examples/multiplayer-arena/src/net.ts b/examples/multiplayer-arena/src/net.tsindex 39df338b5..4de8f908a 100644--- a/examples/multiplayer-arena/src/net.ts+++ b/examples/multiplayer-arena/src/net.ts@@ -1,11 +1,11 @@import {- defineSystem, Query, Mut, Res, GetWorld,+ defineSystem, Res, GetWorld,Time, Input, Net, Replicated, Transform, Sprite,- type World, type InputState,+ type World, type Entity, type InputState,} from 'esengine';import { Pawn } from './components';-// Arena bounds the authority clamps pawns to (matches the scene's walls).+// Arena bounds the movement rule clamps pawns to (matches the scene's walls).const BOUND_X = 420;const BOUND_Y = 278;@@ -27,6 +27,26 @@ function readMove(input: InputState): { x: number; y: number } {return len > 0 ? { x: x / len, y: y / len } : { x: 0, y: 0 };}+/**+ * THE movement rule — one function, both ends. The server applies it with each+ * connection's per-tick input (`tickInputOf`); the client applies it as its+ * prediction function, so your own pawn responds the moment a key goes down+ * (the bounds clamp included — even the walls are predicted). Because both+ * ends run the same rule, reconciliation corrections are invisible in normal+ * play.+ */+function applyMove(world: World, entity: Entity, actions: Record<string, unknown>, dt: number): void {+ const move = actions.move as { x: number; y: number } | undefined;+ if (!move || (move.x === 0 && move.y === 0)) return;+ const pawn = world.tryGet(entity, Pawn);+ const transform = world.tryGet(entity, Transform);+ if (!pawn || !transform) return;+ const p = transform.position;+ p.x = Math.min(BOUND_X, Math.max(-BOUND_X, p.x + move.x * pawn.speed * dt));+ p.y = Math.min(BOUND_Y, Math.max(-BOUND_Y, p.y + move.y * pawn.speed * dt));+ world.set(entity, Transform, transform);+}+function spawnPawn(world: World, player: number): void {const slot = PLAYER_COLORS[player % PLAYER_COLORS.length];const e = world.spawn(`Pawn P${player + 1}`);@@ -36,6 +56,7 @@ function spawnPawn(world: World, player: number): void {// Marking it Replicated is ALL it takes: the entity spawns on every client// (full component payload — sprite color included), its annotated Transform// pose streams as deltas, and `owner` routes that connection's input to it.+ // Owner is assigned AT spawn — ownership rides the spawn payload.world.insert(e, Replicated, { owner: player });}@@ -63,34 +84,41 @@ export const provisionPawnsSystem = defineSystem();/**- * Authority-side movement: one rule for everyone. The host pawn reads the local- * keyboard; remote pawns read their connection's uplinked input. Clients never- * run this — their view of every pawn (their own included) is the replicated,- * interpolated authoritative state.+ * Authority-side movement: `applyMove` for everyone. The host pawn reads the+ * local keyboard; remote pawns consume their connection's input queue via+ * `tickInputOf` — exactly one command per tick, the contract the clients'+ * prediction replays against.*/export const movePawnsSystem = defineSystem(- [Query(Mut(Transform), Pawn, Replicated), Res(Net), Res(Input), Res(Time)],- (query, net, input, time) => {+ [GetWorld(), Res(Net), Res(Input), Res(Time)],+ (world, net, input, time) => {if (net.role === 'client') return;- for (const [, transform, pawn, repl] of query) {- const move = repl.owner === 0- ? readMove(input)- : ((net.server?.inputOf(repl.owner)?.actions.move as { x: number; y: number } | undefined) ?? { x: 0, y: 0 });- if (move.x === 0 && move.y === 0) continue;- const p = transform.position;- p.x = Math.min(BOUND_X, Math.max(-BOUND_X, p.x + move.x * pawn.speed * time.fixedDelta));- p.y = Math.min(BOUND_Y, Math.max(-BOUND_Y, p.y + move.y * pawn.speed * time.fixedDelta));+ for (const e of world.getEntitiesWithComponents([Pawn, Replicated])) {+ const repl = world.tryGet(e, Replicated)!;+ const actions = repl.owner === 0+ ? { move: readMove(input) }+ : (net.server?.tickInputOf(repl.owner)?.actions ?? {});+ applyMove(world as World, e as Entity, actions, time.fixedDelta);}},{ name: 'MovePawnsSystem' },);-/** Client-side input uplink: one command per fixed tick, keyboard → server. */+/**+ * Client-side input uplink + prediction: one command per fixed tick (an idle+ * move counts — with prediction on, silence would mean "keep doing that").+ * The editor's multiplayer preview connects the client realm itself, so+ * prediction is enabled here, lazily, with the same `applyMove` the server+ * runs — your own pawn stops waiting for the round trip.+ */export const sendInputSystem = defineSystem([Res(Net), Res(Input)],(net, input) => {- if (net.role !== 'client') return;- net.client?.sendInput({ move: readMove(input) });+ if (net.role !== 'client' || !net.client) return;+ if (!net.client.predictionEnabled) {+ net.client.enablePrediction({ apply: applyMove });+ }+ net.client.sendInput({ move: readMove(input) });},{ name: 'SendInputSystem' },);diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 5c5826e8f..6a63079c0 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -4706,8 +4706,10 @@ connect: (transport: NetTransport) => Promise<void>connected: booleanconnectionId: numberdisconnect: () => void+enablePrediction: (options: PredictionOptions) => voidnetIds: NetIdsownsEntity: (entity: Entity) => boolean+predictionEnabled: booleansampleInterpolation: (deltaTicks: number) => voidsendInput: (actions: Record<string, unknown>) => voidserverTick: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 729d3e06e..a4f954f1e 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4701,8 +4701,10 @@ connect: (transport: NetTransport) => Promise<void>connected: booleanconnectionId: numberdisconnect: () => void+enablePrediction: (options: PredictionOptions) => voidnetIds: NetIdsownsEntity: (entity: Entity) => boolean+predictionEnabled: booleansampleInterpolation: (deltaTicks: number) => voidsendInput: (actions: Record<string, unknown>) => voidserverTick: numberdiff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.tsindex a30f95ace..6572eedff 100644--- a/sdk/src/net/replication/client.ts+++ b/sdk/src/net/replication/client.ts@@ -79,7 +79,7 @@ export class ReplicationClient {private readonly pendingDespawns_: ReplDespawnBatch[] = [];private readonly interp_: InterpolationState | null;private inputSeq_ = 0;- private readonly prediction_: PredictionOptions | null;+ private prediction_: PredictionOptions | null;/** Sent-but-unacknowledged input commands, oldest first (replay order). */private readonly pendingInputs_: ReplInputMsg[] = [];private ackedSeq_ = 0;@@ -170,6 +170,27 @@ export class ReplicationClient {if (dt > 0) this.fixedDelta_ = dt;}+ get predictionEnabled(): boolean {+ return this.prediction_ !== null;+ }++ /**+ * Enable (or reconfigure) prediction after construction — the path for+ * game code whose connection a HOST made (the editor's multiplayer+ * preview connects the client realm itself, options-free): call from a+ * fixed-tick system once the session is a client. Owned entities that+ * already spawned get their authority copies seeded from current state.+ */+ enablePrediction(options: PredictionOptions): void {+ this.prediction_ = options;+ for (const e of this.ownedEntities_()) {+ const netId = this.netIds_.netIdOf(e);+ if (netId !== undefined && !this.authority_.has(netId)) {+ this.seedAuthority_(netId, e);+ }+ }+ }+disconnect(): void {this.channel_?.dispose();this.channel_ = null;diff --git a/sdk/tests/replication-prediction.test.ts b/sdk/tests/replication-prediction.test.tsindex 57beeb925..e20f21eed 100644--- a/sdk/tests/replication-prediction.test.ts+++ b/sdk/tests/replication-prediction.test.ts@@ -209,6 +209,44 @@ describe('client prediction', () => {});});+describe('late enablePrediction (host-connected realms)', () => {+ it('seeds authority for already-spawned owned entities and predicts from then on', async () => {+ const serverApp = makeApp();+ const clientApp = makeApp();+ const server = serverApp.getResource(Net).startServer();+ addServerInputSystem(serverApp, server);+ const [ta, tb] = MemoryTransport.pair();+ const connId = server.attachConnection(ta);+ // Connected WITHOUT prediction — the editor-host shape.+ const client = await clientApp.getResource(Net).connect(tb, { interpolationDelayTicks: 0 });++ const pawn = serverApp.world.spawn('pawn');+ serverApp.world.insert(pawn, Replicated, { owner: connId });+ serverApp.world.insert(pawn, NetPos, { x: 5, y: 0 });+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ const ghost = clientApp.world.getEntitiesWithComponents([Replicated])[0];++ expect(client.predictionEnabled).toBe(false);+ client.enablePrediction({ apply: applyMove });+ expect(client.predictionEnabled).toBe(true);++ // Immediate local movement…+ client.sendInput({ move: { x: 1, y: 0 } });+ expect(posX(clientApp, ghost)).toBeCloseTo(15, 5);++ // …and the late seed holds the authority baseline: a tampered value+ // snaps back even though the server never re-sends it.+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ clientApp.world.set(ghost, NetPos, { x: 999, y: 0 });+ client.sendInput({ move: { x: 0, y: 0 } });+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ expect(posX(clientApp, ghost)).toBeCloseTo(15, 5);+ });+});+describe('per-tick input queue (tickInputOf)', () => {it('consumes exactly one command per tick, repeats on starvation, and inputOf stays latest', async () => {const serverApp = makeApp();