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(examples): multiplayer-arena runs on client prediction

yhh482601740fa0
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 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.tsx
index 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.mdx
index 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 what
diff --git a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx b/docs/astro/src/content/docs/zh-cn/guides/networking.mdx
index 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.md
index 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.md
index 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 every
component (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.ts
index 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.md
index 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: boolean
connectionId: number
disconnect: () => void
+enablePrediction: (options: PredictionOptions) => void
netIds: NetIds
ownsEntity: (entity: Entity) => boolean
+predictionEnabled: boolean
sampleInterpolation: (deltaTicks: number) => void
sendInput: (actions: Record<string, unknown>) => void
serverTick: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: boolean
connectionId: number
disconnect: () => void
+enablePrediction: (options: PredictionOptions) => void
netIds: NetIds
ownsEntity: (entity: Entity) => boolean
+predictionEnabled: boolean
sampleInterpolation: (deltaTicks: number) => void
sendInput: (actions: Record<string, unknown>) => void
serverTick: number
diff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.ts
index 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.ts
index 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();