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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* Client-side prediction + reconciliation: owned entities respond to input
* immediately (before any server round trip), unacknowledged commands replay
* on top of every authoritative update (authority ⊕ replay), server-side
* corrections win, and mispredictions can never accumulate because the live
* state is rebuilt from the authority copy every fixed step. The server's
* per-tick input queue (tickInputOf) is the exactly-once contract that makes
* the replay deterministic.
*/
import { describe, it, expect, beforeEach } from 'vitest';
import { App } from '../src/app/app';
import { defineComponent, clearUserComponents } from '../src/ecs/component';
import { defineSystem, Schedule, GetWorld } from '../src/ecs/system';
import { MemoryTransport } from '../src/net/MemoryTransport';
import { replicationPlugin, Net, Replicated, predictionReplays, type ReplicationServer } from '../src/net/replication';
import { ResourceStorage } from '../src/ecs/resource';
import type { Entity } from '../src/types';
import type { World } from '../src/ecs/world';
const STEP = 1 / 60;
const SPEED = 600; // units/second → 10 units per tick
let NetPos: ReturnType<typeof defineComponent<{ x: number; y: number }>>;
beforeEach(() => {
clearUserComponents();
NetPos = defineComponent('NetPos', { x: 0, y: 0 }, { replicatedFields: ['x', 'y'] });
});
/** The ONE movement function both ends run — the single source of the rules. */
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) return;
const pos = world.tryGet(entity, NetPos) as { x: number; y: number } | null;
if (!pos) return;
pos.x += move.x * SPEED * dt;
pos.y += move.y * SPEED * dt;
world.set(entity, NetPos, pos);
}
function makeApp(): App {
const app = App.new();
app.addPlugin(replicationPlugin);
return app;
}
/** Server gameplay: apply each connection's PER-TICK input to its entities. */
function addServerInputSystem(serverApp: App, server: ReplicationServer): void {
serverApp.addSystemToSchedule(Schedule.FixedUpdate, defineSystem(
[GetWorld()],
(world) => {
for (const e of world.getEntitiesWithComponents([Replicated])) {
const repl = world.tryGet(e, Replicated)!;
if (repl.owner === 0) continue;
const input = server.tickInputOf(repl.owner);
if (input) applyMove(world as World, e as Entity, input.actions, STEP);
}
},
{ name: 'ApplyPlayerInput' },
));
}
async function makePredictedPair(interpolationDelayTicks = 0) {
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);
const client = await clientApp.getResource(Net).connect(tb, {
interpolationDelayTicks,
prediction: { apply: applyMove },
});
const pawn = serverApp.world.spawn('pawn');
serverApp.world.insert(pawn, Replicated, { owner: connId });
serverApp.world.insert(pawn, NetPos, {});
await serverApp.tick(STEP);
await clientApp.tick(STEP);
const ghost = clientApp.world.getEntitiesWithComponents([Replicated])[0];
expect(client.ownsEntity(ghost)).toBe(true);
return { serverApp, clientApp, server, client, connId, pawn, ghost };
}
const posX = (app: App, e: Entity): number => (app.world.tryGet(e, NetPos) as { x: number }).x;
describe('client prediction', () => {
it('an owned entity moves the moment input is sent — no server round trip', async () => {
const { serverApp, clientApp, pawn, ghost, client } = await makePredictedPair();
client.sendInput({ move: { x: 1, y: 0 } });
expect(posX(clientApp, ghost)).toBeCloseTo(10, 5); // immediately
expect(posX(serverApp, pawn)).toBe(0); // server hasn't ticked
await serverApp.tick(STEP);
await clientApp.tick(STEP);
expect(posX(serverApp, pawn)).toBeCloseTo(10, 5);
expect(posX(clientApp, ghost)).toBeCloseTo(10, 5); // converged, no rubber-band
});
it('prediction stays ahead under latency and converges exactly when acks land', async () => {
const serverApp = makeApp();
const clientApp = makeApp();
const server = serverApp.getResource(Net).startServer();
addServerInputSystem(serverApp, server);
const [ta, tb] = MemoryTransport.pair({ manualFlush: true });
const connId = server.attachConnection(ta);
const connectP = clientApp.getResource(Net).connect(tb, {
interpolationDelayTicks: 0,
prediction: { apply: applyMove },
});
for (let i = 0; i < 8; i++) { ta.flush(); tb.flush(); await Promise.resolve(); }
const client = await connectP;
const pawn = serverApp.world.spawn('pawn');
serverApp.world.insert(pawn, Replicated, { owner: connId });
serverApp.world.insert(pawn, NetPos, {});
await serverApp.tick(STEP);
ta.flush(); tb.flush();
await clientApp.tick(STEP);
const ghost = clientApp.world.getEntitiesWithComponents([Replicated])[0];
// Three inputs while the wire is held: the client is 3 ticks ahead.
for (let i = 0; i < 3; i++) client.sendInput({ move: { x: 1, y: 0 } });
expect(posX(clientApp, ghost)).toBeCloseTo(30, 5);
expect(posX(serverApp, pawn)).toBe(0);
// Release the wire: the server consumes the queue one command per tick.
ta.flush(); tb.flush();
for (let i = 0; i < 3; i++) {
await serverApp.tick(STEP);
ta.flush(); tb.flush();
await clientApp.tick(STEP);
}
expect(posX(serverApp, pawn)).toBeCloseTo(30, 5);
expect(posX(clientApp, ghost)).toBeCloseTo(30, 5);
});
it('a server-side correction wins over the prediction', async () => {
const { serverApp, clientApp, ghost, pawn, client } = await makePredictedPair();
// Server-only rule the client's apply knows nothing about: a wall at x=25.
serverApp.addSystemToSchedule(Schedule.FixedUpdate, defineSystem(
[GetWorld()],
(world) => {
const pos = world.tryGet(pawn, NetPos) as { x: number; y: number } | null;
if (pos && pos.x > 25) { pos.x = 25; world.set(pawn, NetPos, pos); }
},
{ name: 'WallClamp' },
));
for (let i = 0; i < 3; i++) client.sendInput({ move: { x: 1, y: 0 } });
expect(posX(clientApp, ghost)).toBeCloseTo(30, 5); // optimistic
for (let i = 0; i < 4; i++) {
await serverApp.tick(STEP);
await clientApp.tick(STEP);
}
expect(posX(serverApp, pawn)).toBeCloseTo(25, 5);
expect(posX(clientApp, ghost)).toBeCloseTo(25, 5); // corrected
});
it('local tampering cannot drift: live state is rebuilt from authority every step', async () => {
const { serverApp, clientApp, ghost, client } = await makePredictedPair();
client.sendInput({ move: { x: 1, y: 0 } });
await serverApp.tick(STEP);
await clientApp.tick(STEP);
expect(posX(clientApp, ghost)).toBeCloseTo(10, 5);
// A wayward local write to a predicted entity — the server sends no
// new delta for x (it idles on the next command), yet reconciliation
// snaps the value back to the authority copy.
clientApp.world.set(ghost, NetPos, { x: 999, y: 0 });
client.sendInput({ move: { x: 0, y: 0 } }); // the per-tick idle command
await serverApp.tick(STEP);
await clientApp.tick(STEP);
expect(posX(clientApp, ghost)).toBeCloseTo(10, 5);
});
it('non-owned entities are untouched by prediction and still replicate', async () => {
const { serverApp, clientApp, client, server } = await makePredictedPair();
const npc = serverApp.world.spawn('npc');
serverApp.world.insert(npc, Replicated, {});
serverApp.world.insert(npc, NetPos, { x: 100, y: 0 });
await serverApp.tick(STEP);
await clientApp.tick(STEP);
const npcGhost = clientApp.world.getEntitiesWithComponents([Replicated])
.find((e) => !client.ownsEntity(e))!;
expect(posX(clientApp, npcGhost)).toBe(100);
client.sendInput({ move: { x: 1, y: 0 } });
expect(posX(clientApp, npcGhost)).toBe(100); // prediction never touches it
serverApp.world.set(npc, NetPos, { x: 120, y: 0 });
await serverApp.tick(STEP);
await clientApp.tick(STEP);
expect(posX(clientApp, npcGhost)).toBe(120); // normal replication path
void server;
});
it('prediction bypasses snapshot interpolation for owned entities', async () => {
const { clientApp, ghost, client } = await makePredictedPair(/* interpolationDelayTicks */ 2);
client.sendInput({ move: { x: 1, y: 0 } });
// With a 2-tick presentation delay a ghost would lag; the owned pawn moves NOW.
expect(posX(clientApp, ghost)).toBeCloseTo(10, 5);
});
});
describe('correction smoothing', () => {
async function makeSmoothedPair(smoothing: { halfLife: number; maxError?: number }) {
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);
const client = await clientApp.getResource(Net).connect(tb, {
interpolationDelayTicks: 0,
prediction: { apply: applyMove, smoothing },
});
const pawn = serverApp.world.spawn('pawn');
serverApp.world.insert(pawn, Replicated, { owner: connId });
serverApp.world.insert(pawn, NetPos, {});
await serverApp.tick(STEP);
await clientApp.tick(STEP);
const ghost = clientApp.world.getEntitiesWithComponents([Replicated])[0];
return { serverApp, clientApp, server, client, pawn, ghost };
}
it('eases a correction out instead of snapping, and converges on the authority', async () => {
// Error halves every 4 ticks — slow enough to observe.
const { serverApp, clientApp, pawn, ghost, client } = await makeSmoothedPair({ halfLife: 4 * STEP });
// Server-only wall at x=25; the client optimistically predicts to 30.
serverApp.addSystemToSchedule(Schedule.FixedUpdate, defineSystem(
[GetWorld()],
(world) => {
const pos = world.tryGet(pawn, NetPos) as { x: number; y: number } | null;
if (pos && pos.x > 25) { pos.x = 25; world.set(pawn, NetPos, pos); }
},
{ name: 'WallClamp' },
));
for (let i = 0; i < 3; i++) client.sendInput({ move: { x: 1, y: 0 } });
expect(posX(clientApp, ghost)).toBeCloseTo(30, 5);
// While the replay still accounts for the prediction there is NO error
// (deterministic replay); the correction materialises the tick the
// server clamps — and lands BETWEEN authority (25) and prediction (30).
for (let i = 0; i < 3; i++) {
await serverApp.tick(STEP);
await clientApp.tick(STEP);
}
const eased = posX(clientApp, ghost);
expect(eased).toBeGreaterThan(25.5);
expect(eased).toBeLessThan(30);
// The error decays monotonically to the authoritative value.
let prev = eased;
for (let i = 0; i < 40; i++) {
await serverApp.tick(STEP);
await clientApp.tick(STEP);
const x = posX(clientApp, ghost);
expect(x).toBeLessThanOrEqual(prev + 1e-6);
prev = x;
}
expect(prev).toBeCloseTo(25, 1);
});
it('a correction beyond maxError snaps — a teleport must look like one', async () => {
const { serverApp, clientApp, pawn, ghost, client } = await makeSmoothedPair({ halfLife: 4 * STEP, maxError: 50 });
client.sendInput({ move: { x: 1, y: 0 } });
await serverApp.tick(STEP);
await clientApp.tick(STEP);
expect(posX(clientApp, ghost)).toBeCloseTo(10, 5);
// The server teleports the pawn far beyond maxError.
serverApp.world.set(pawn, NetPos, { x: 500, y: 0 });
client.sendInput({ move: { x: 0, y: 0 } });
await serverApp.tick(STEP);
await clientApp.tick(STEP);
expect(posX(clientApp, ghost)).toBeCloseTo(500, 5); // no easing
});
});
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();
const clientApp = makeApp();
const server = serverApp.getResource(Net).startServer();
const [ta, tb] = MemoryTransport.pair();
const connId = server.attachConnection(ta);
const client = await clientApp.getResource(Net).connect(tb, { interpolationDelayTicks: 0 });
client.sendInput({ n: 1 });
client.sendInput({ n: 2 });
expect(server.inputOf(connId)!.seq).toBe(2); // latest-persists, unchanged
expect(server.tickInputOf(connId)).toBeNull(); // nothing consumed yet
await serverApp.tick(STEP);
expect(server.tickInputOf(connId)!.actions).toEqual({ n: 1 });
await serverApp.tick(STEP);
expect(server.tickInputOf(connId)!.actions).toEqual({ n: 2 });
await serverApp.tick(STEP); // queue dry → the held command repeats
expect(server.tickInputOf(connId)!.actions).toEqual({ n: 2 });
});
});
// The promise `apply` carries — "must depend only on world state + actions +
// dt (it re-runs during reconciliation)" — is what the rebuild rests on, and
// until there was a machine for it only a desync could report it broken.
describe('the rule reconciliation replays', () => {
it('is a function of the world, and the same one twice', () => {
const app = App.new();
const world = app.world;
const pawn = world.spawn();
world.insert(pawn, NetPos, { x: 0, y: 0 });
const report = predictionReplays(
{ world, resources: new ResourceStorage() },
{ apply: applyMove },
pawn,
{ move: { x: 1, y: 0 } },
STEP,
);
expect(report).toEqual({ stable: true, why: '' });
// Asking moved nothing: both runs were taken back.
expect(world.get(pawn, NetPos).x).toBe(0);
});
it('and is reported when it is not', () => {
const app = App.new();
const world = app.world;
const pawn = world.spawn();
world.insert(pawn, NetPos, { x: 0, y: 0 });
const drifts = (w: World, e: Entity): void => {
w.set(e, NetPos, { x: Math.random(), y: 0 });
};
const report = predictionReplays(
{ world, resources: new ResourceStorage() },
{ apply: drifts },
pawn,
{},
STEP,
);
expect(report.stable).toBe(false);
expect(report.why).toMatch(/^values differed between runs/);
});
});