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(replication): server-authoritative state replication core — RC11 N2 keystone

esengine54be32664278
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index f35575d38..4081b9613 100644
--- a/sdk/src/app.ts
+++ b/sdk/src/app.ts
@@ -585,7 +585,7 @@ export class App {
this.runner_.setTimingEnabled(true);
}
if (!this.resources_.has(Time)) {
- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0 });
+ this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0 });
}
this.finishPlugins_();
}
@@ -606,7 +606,7 @@ export class App {
this.runner_.setTimingEnabled(true);
}
if (!this.resources_.has(Time)) {
- this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0 });
+ this.resources_.insert(Time, { delta: 0, elapsed: 0, frameCount: 0, fixedDelta: this.fixedTimestep_, fixedAlpha: 0, fixedTick: 0 });
}
this.finishPlugins_();
}
@@ -712,6 +712,9 @@ export class App {
const fixedStart = perf ? perf.now() : 0;
while (this.fixedAccumulator_ >= this.fixedTimestep_ && fixedSteps < this.maxFixedSteps_) {
this.fixedAccumulator_ -= this.fixedTimestep_;
+ // Every system inside one fixed step sees the same tick number
+ // (1-based) — the simulation time axis netcode stamps packets with.
+ this.resources_.get(Time).fixedTick++;
input?.beginFixedStep();
await this.runSchedule(Schedule.FixedPreUpdate);
await this.runSchedule(Schedule.FixedUpdate);
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 8d17a1547..4d8d972cb 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -87,6 +87,13 @@ export {
type PlatformSocketReadyState,
} from './net';
+export {
+ replicationPlugin, ReplicationPlugin, Net, NetSession,
+ Replicated, NetGhost, ReplicationServer, ReplicationClient,
+ REPLICATION_PROTOCOL_VERSION, REPLICATION_CHANNEL,
+ type NetRoleKind, type ReplicatedData,
+} from './net/replication';
+
// =============================================================================
// Platform (base functions only)
// =============================================================================
diff --git a/sdk/src/net/index.ts b/sdk/src/net/index.ts
index f10edaa40..2ce97fa9c 100644
--- a/sdk/src/net/index.ts
+++ b/sdk/src/net/index.ts
@@ -12,6 +12,7 @@ export {
} from './NetChannel';
export { MemoryTransport, createMemoryTransportPair } from './MemoryTransport';
export type { PlatformSocket, PlatformSocketOptions, PlatformSocketReadyState } from '../platform/types';
+export * from './replication';
import { GameSocket, type GameSocketOptions } from './GameSocket';
import { isPlatformInitialized, getPlatform } from '../platform/base';
diff --git a/sdk/src/net/replication/NetIds.ts b/sdk/src/net/replication/NetIds.ts
new file mode 100644
index 000000000..7d1f431d1
--- /dev/null
+++ b/sdk/src/net/replication/NetIds.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file NetIds.ts
+ * @brief NetId ↔ Entity mapping. Entity handles are realm-local (packed
+ * 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.
+ */
+import type { Entity } from '../../types';
+
+export class NetIds {
+ private readonly byNetId_ = new Map<number, Entity>();
+ private readonly byEntity_ = new Map<Entity, number>();
+ private nextId_ = 1;
+
+ /** Server-side: allocate the next NetId. */
+ allocate(): number {
+ return this.nextId_++;
+ }
+
+ register(netId: number, entity: Entity): void {
+ this.byNetId_.set(netId, entity);
+ this.byEntity_.set(entity, netId);
+ }
+
+ unregister(netId: number): void {
+ const e = this.byNetId_.get(netId);
+ this.byNetId_.delete(netId);
+ if (e !== undefined) this.byEntity_.delete(e);
+ }
+
+ unregisterEntity(entity: Entity): void {
+ const id = this.byEntity_.get(entity);
+ this.byEntity_.delete(entity);
+ if (id !== undefined) this.byNetId_.delete(id);
+ }
+
+ entityOf(netId: number): Entity | undefined {
+ return this.byNetId_.get(netId);
+ }
+
+ netIdOf(entity: Entity): number | undefined {
+ return this.byEntity_.get(entity);
+ }
+
+ get size(): number {
+ return this.byNetId_.size;
+ }
+
+ clear(): void {
+ this.byNetId_.clear();
+ this.byEntity_.clear();
+ this.nextId_ = 1;
+ }
+}
diff --git a/sdk/src/net/replication/ReplicationPlugin.ts b/sdk/src/net/replication/ReplicationPlugin.ts
new file mode 100644
index 000000000..ef0933797
--- /dev/null
+++ b/sdk/src/net/replication/ReplicationPlugin.ts
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ReplicationPlugin.ts
+ * @brief Replication as a normal plugin on the normal schedules — no second
+ * runtime (the defineBehavior/FSM/BT unification rule). The netcode
+ * shares the physics cadence: FixedPreUpdate applies received state,
+ * 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.
+ */
+import type { App, Plugin } from '../../app';
+import { defineSystem, Schedule } from '../../system';
+import { defineResource, Res, Time, type TimeData } from '../../resource';
+import type { NetTransport } from '../NetChannel';
+import { ReplicationServer } from './server';
+import { ReplicationClient } from './client';
+import { ensureReplicationComponentsRegistered } from './components';
+
+export type NetRoleKind = 'offline' | 'server' | 'client';
+
+export class NetSession {
+ private role_: NetRoleKind = 'offline';
+ private server_: ReplicationServer | null = null;
+ private client_: ReplicationClient | null = null;
+
+ constructor(private readonly app_: App) {}
+
+ get role(): NetRoleKind {
+ return this.role_;
+ }
+
+ get server(): ReplicationServer | null {
+ return this.server_;
+ }
+
+ get client(): ReplicationClient | null {
+ return this.client_;
+ }
+
+ /** Become the authority. Attach one transport per accepted client. */
+ startServer(): ReplicationServer {
+ if (this.role_ !== 'offline') throw new Error(`[repl] session already ${this.role_}`);
+ this.role_ = 'server';
+ this.server_ = new ReplicationServer(this.app_.world);
+ return this.server_;
+ }
+
+ /** Become a replica: handshake over the given transport. */
+ async connect(transport: NetTransport): Promise<ReplicationClient> {
+ if (this.role_ !== 'offline') throw new Error(`[repl] session already ${this.role_}`);
+ const client = new ReplicationClient(this.app_.world);
+ await client.connect(transport);
+ this.role_ = 'client';
+ this.client_ = client;
+ return client;
+ }
+
+ stop(): void {
+ this.client_?.disconnect();
+ this.client_ = null;
+ this.server_ = null;
+ this.role_ = 'offline';
+ }
+}
+
+export const Net = defineResource<NetSession>(null!, 'Net');
+
+export class ReplicationPlugin implements Plugin {
+ name = 'replication';
+
+ build(app: App): void {
+ ensureReplicationComponentsRegistered();
+ const session = new NetSession(app);
+ app.insertResource(Net, session);
+
+ app.addSystemToSchedule(
+ Schedule.FixedPreUpdate,
+ defineSystem(
+ [Res(Time)],
+ (_time: TimeData) => {
+ session.client?.applyPending();
+ },
+ { name: 'ReplicationApplySystem' },
+ ),
+ { runIf: () => session.role === 'client' },
+ );
+
+ app.addSystemToSchedule(
+ Schedule.FixedPostUpdate,
+ defineSystem(
+ [Res(Time)],
+ (time: TimeData) => {
+ session.server?.sample(time.fixedTick);
+ },
+ { name: 'ReplicationSampleSystem' },
+ ),
+ { runIf: () => session.role === 'server' },
+ );
+ }
+}
+
+export const replicationPlugin = new ReplicationPlugin();
diff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.ts
new file mode 100644
index 000000000..2206dd954
--- /dev/null
+++ b/sdk/src/net/replication/client.ts
@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file client.ts
+ * @brief The replica endpoint. Handshakes schema + ABI, spawns NetGhost
+ * proxies from server spawn batches (via loadComponent, so codecs and
+ * validation are the scene-loading ones), and queues binary delta
+ * frames to apply at the FixedPreUpdate boundary — state lands at a
+ * deterministic point in the frame, not mid-schedule on socket
+ * timing.
+ */
+import type { World } from '../../world';
+import type { Entity } from '../../types';
+import { getComponent } from '../../component';
+import { ABI_LAYOUT_HASH } from '../../component.generated';
+import { loadComponent } from '../../scene';
+import { NetChannel, type NetTransport } from '../NetChannel';
+import { log } from '../../logger';
+import {
+ REPLICATION_CHANNEL, REPLICATION_PROTOCOL_VERSION, ReplMsg,
+ type ReplDespawnBatch, type ReplHelloRequest, type ReplHelloResponse, type ReplSpawnBatch, type ReplSpawnEntity,
+} from './protocol';
+import {
+ buildReplicationTable, decodeStateFrame, tableSchemas,
+ type EntityRefMap, type ReplicationTable, type StateFrame,
+} from './codec';
+import { NetGhost } from './components';
+import { NetIds } from './NetIds';
+
+export class ReplicationClient {
+ private readonly world_: World;
+ private readonly netIds_ = new NetIds();
+ private channel_: NetChannel | null = null;
+ private table_: ReplicationTable | null = null;
+ private connectionId_ = 0;
+ private serverTick_ = 0;
+ private readonly pendingFrames_: Uint8Array[] = [];
+ private readonly pendingSpawns_: ReplSpawnBatch[] = [];
+ private readonly pendingDespawns_: ReplDespawnBatch[] = [];
+
+ constructor(world: World) {
+ this.world_ = world;
+ world.onDespawn((e) => this.netIds_.unregisterEntity(e));
+ }
+
+ get table(): ReplicationTable {
+ return (this.table_ ??= buildReplicationTable());
+ }
+
+ get netIds(): NetIds {
+ return this.netIds_;
+ }
+
+ get connected(): boolean {
+ return this.channel_ !== null && this.connectionId_ !== 0;
+ }
+
+ get connectionId(): number {
+ return this.connectionId_;
+ }
+
+ /** The tick stamped on the newest applied state (server time axis). */
+ get serverTick(): number {
+ return this.serverTick_;
+ }
+
+ private get refs_(): EntityRefMap {
+ return {
+ toWire: (entity) => this.netIds_.netIdOf(entity as Entity) ?? 0,
+ fromWire: (netId) => (this.netIds_.entityOf(netId) as number | undefined) ?? 0,
+ };
+ }
+
+ /** Handshake over the transport; rejects (and detaches) on any mismatch. */
+ async connect(transport: NetTransport): Promise<void> {
+ if (this.channel_) throw new Error('[repl] client already connected');
+ const channel = new NetChannel(transport);
+ this.channel_ = channel;
+
+ // Handlers first: the initial spawn batch may hit the wire before the
+ // hello response settles on this side. Batches queue until the fixed
+ // step applies them, so ordering stays deterministic either way.
+ channel.on<ReplSpawnBatch>(ReplMsg.spawn, (batch) => this.pendingSpawns_.push(batch));
+ channel.on<ReplDespawnBatch>(ReplMsg.despawn, (batch) => this.pendingDespawns_.push(batch));
+ channel.onBinary(REPLICATION_CHANNEL, (payload) => {
+ // Copy out: the payload view may alias a transport-owned buffer.
+ this.pendingFrames_.push(payload.slice());
+ });
+
+ const hello: ReplHelloRequest = {
+ protocolVersion: REPLICATION_PROTOCOL_VERSION,
+ abiHash: ABI_LAYOUT_HASH,
+ components: tableSchemas(this.table),
+ };
+ let res: ReplHelloResponse;
+ try {
+ res = await channel.request<ReplHelloResponse>(ReplMsg.hello, hello);
+ } catch (err) {
+ this.disconnect();
+ throw err;
+ }
+ if (!res.ok) {
+ this.disconnect();
+ throw new Error(`[repl] server refused connection: ${res.error}`);
+ }
+ this.connectionId_ = res.connectionId;
+ this.serverTick_ = res.tick;
+ }
+
+ disconnect(): void {
+ this.channel_?.dispose();
+ this.channel_ = null;
+ this.connectionId_ = 0;
+ }
+
+ /** Apply everything received since the last fixed step. Spawns before
+ * state (a frame may reference an entity spawned in the same flush). */
+ applyPending(): void {
+ while (this.pendingSpawns_.length > 0) {
+ this.applySpawnBatch_(this.pendingSpawns_.shift()!);
+ }
+ while (this.pendingFrames_.length > 0) {
+ this.applyStateFrame_(decodeStateFrame(this.pendingFrames_.shift()!, this.table, this.refs_));
+ }
+ while (this.pendingDespawns_.length > 0) {
+ this.applyDespawnBatch_(this.pendingDespawns_.shift()!);
+ }
+ }
+
+ private applySpawnBatch_(batch: ReplSpawnBatch): void {
+ for (const spawn of batch.entities) {
+ this.spawnGhost_(spawn);
+ }
+ // Parent after the whole batch so forward references resolve.
+ for (const spawn of batch.entities) {
+ if (spawn.parentNetId !== 0) {
+ const child = this.netIds_.entityOf(spawn.netId);
+ const parent = this.netIds_.entityOf(spawn.parentNetId);
+ if (child !== undefined && parent !== undefined) {
+ this.world_.setParent(child, parent);
+ }
+ }
+ }
+ }
+
+ private spawnGhost_(spawn: ReplSpawnEntity): void {
+ if (this.netIds_.entityOf(spawn.netId) !== undefined) return; // duplicate delivery
+ const e = this.world_.spawn(spawn.name || undefined);
+ for (const comp of spawn.components) {
+ const data = this.remapEntityRefs_(comp.type, comp.data);
+ loadComponent(this.world_, e, { type: comp.type, data }, spawn.name);
+ }
+ this.world_.insert(e, NetGhost, {});
+ this.netIds_.register(spawn.netId, e);
+ }
+
+ private remapEntityRefs_(type: string, data: Record<string, unknown>): Record<string, unknown> {
+ const entityFields = getComponent(type)?.entityFields ?? [];
+ if (entityFields.length === 0) return { ...data };
+ const out = { ...data };
+ for (const f of entityFields) {
+ if (typeof out[f] === 'number') {
+ out[f] = (this.netIds_.entityOf(out[f] as number) as number | undefined) ?? 0;
+ }
+ }
+ return out;
+ }
+
+ private applyDespawnBatch_(batch: ReplDespawnBatch): void {
+ for (const netId of batch.netIds) {
+ const e = this.netIds_.entityOf(netId);
+ this.netIds_.unregister(netId);
+ if (e !== undefined && this.world_.valid(e)) {
+ this.world_.despawn(e);
+ }
+ }
+ }
+
+ private applyStateFrame_(frame: StateFrame): void {
+ if (frame.tick > this.serverTick_) this.serverTick_ = frame.tick;
+ for (const entry of frame.entries) {
+ const e = this.netIds_.entityOf(entry.netId);
+ if (e === undefined || !this.world_.valid(e)) continue;
+ const te = this.table.entries[entry.componentId];
+ if (!te) continue;
+ const existing = this.world_.tryGet(e, te.def) as Record<string, unknown> | null;
+ const target = existing ?? {};
+ let v = 0;
+ for (let i = 0; i < te.fields.length; i++) {
+ if (entry.fieldMask & (1 << i)) {
+ target[te.fields[i]] = entry.values[v++];
+ }
+ }
+ if (existing) {
+ this.world_.set(e, te.def, target);
+ } else {
+ this.world_.insert(e, te.def, target);
+ }
+ }
+ }
+}
diff --git a/sdk/src/net/replication/codec.ts b/sdk/src/net/replication/codec.ts
new file mode 100644
index 000000000..2197295d7
--- /dev/null
+++ b/sdk/src/net/replication/codec.ts
@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file codec.ts
+ * @brief Reflection-driven binary codec for replication state frames. No
+ * hand-written per-component serializers: the field list comes from
+ * the `replicated` declaration (getReplicatedFields) and each field's
+ * wire shape derives from the component's default value — both ends
+ * derive from the same declaration, verified at handshake, so the
+ * layouts cannot drift independently.
+ *
+ * Frame layout (little-endian):
+ * u32 magic 'ESRP' | u8 version | u32 tick | u16 entryCount
+ * entry: u32 netId | u16 componentId | u32 fieldMask
+ * | field values for set mask bits, in declaration order
+ *
+ * Value shapes: number → f32 (engine truth is f32), boolean → u8,
+ * 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.
+ */
+import { getComponentRegistry, type AnyComponentDef } from '../../component';
+import { REPLICATION_PROTOCOL_VERSION, type ReplComponentSchema } from './protocol';
+
+const FRAME_MAGIC = 0x45535250; // 'ESRP'
+
+// =============================================================================
+// Field shapes
+// =============================================================================
+
+export type FieldShape =
+ | { kind: 'f32' }
+ | { kind: 'bool' }
+ | { kind: 'string' }
+ | { kind: 'entity' }
+ | { kind: 'object'; keys: string[]; shapes: FieldShape[] }
+ | { kind: 'json' };
+
+function buildShape(defaultValue: unknown): FieldShape {
+ switch (typeof defaultValue) {
+ case 'number': return { kind: 'f32' };
+ case 'boolean': return { kind: 'bool' };
+ case 'string': return { kind: 'string' };
+ case 'object': {
+ if (defaultValue === null || Array.isArray(defaultValue)) return { kind: 'json' };
+ const keys = Object.keys(defaultValue as Record<string, unknown>);
+ return {
+ kind: 'object',
+ keys,
+ shapes: keys.map((k) => buildShape((defaultValue as Record<string, unknown>)[k])),
+ };
+ }
+ default: return { kind: 'json' };
+ }
+}
+
+// =============================================================================
+// Replication table
+// =============================================================================
+
+export interface ReplicationTableEntry {
+ /** Wire component id — the index in the name-sorted table. */
+ id: number;
+ name: string;
+ def: AnyComponentDef;
+ fields: string[];
+ shapes: FieldShape[];
+}
+
+export interface ReplicationTable {
+ entries: ReplicationTableEntry[];
+ byName: Map<string, ReplicationTableEntry>;
+}
+
+/**
+ * Build the wire table from every registered component with a non-empty
+ * `replicated` declaration, name-sorted so both ends derive identical ids.
+ * The handshake compares the two tables field-by-field before any frame flows.
+ */
+export function buildReplicationTable(): ReplicationTable {
+ const entries: ReplicationTableEntry[] = [];
+ const names = [...getComponentRegistry().entries()]
+ .filter(([, def]) => def.replicatedFields.length > 0)
+ .map(([name]) => name)
+ .sort();
+ for (const name of names) {
+ const def = getComponentRegistry().get(name)!;
+ const fields = [...def.replicatedFields];
+ if (fields.length > 32) {
+ throw new Error(`[repl] component "${name}" declares ${fields.length} replicated fields; the field mask caps at 32`);
+ }
+ const defaults = def._default as Record<string, unknown>;
+ const entityFields = new Set(def.entityFields);
+ entries.push({
+ id: entries.length,
+ name,
+ def,
+ fields,
+ shapes: fields.map((f) => (entityFields.has(f) ? { kind: 'entity' } : buildShape(defaults[f]))),
+ });
+ }
+ return { entries, byName: new Map(entries.map((e) => [e.name, e])) };
+}
+
+export function tableSchemas(table: ReplicationTable): ReplComponentSchema[] {
+ return table.entries.map((e) => ({ name: e.name, fields: [...e.fields] }));
+}
+
+/** Exact-schema comparison for the handshake: same components, same fields,
+ * same order. Returns a human-readable mismatch, or null when compatible. */
+export function diffSchemas(mine: ReplComponentSchema[], theirs: ReplComponentSchema[]): string | null {
+ if (mine.length !== theirs.length) {
+ return `replication table size mismatch (${mine.length} vs ${theirs.length})`;
+ }
+ for (let i = 0; i < mine.length; i++) {
+ if (mine[i].name !== theirs[i].name) {
+ return `component #${i} differs ("${mine[i].name}" vs "${theirs[i].name}")`;
+ }
+ if (mine[i].fields.join(',') !== theirs[i].fields.join(',')) {
+ return `component "${mine[i].name}" field list differs ([${mine[i].fields}] vs [${theirs[i].fields}])`;
+ }
+ }
+ return null;
+}
+
+// =============================================================================
+// Byte streams
+// =============================================================================
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+export class ByteWriter {
+ private buf_: Uint8Array;
+ private view_: DataView;
+ private len_ = 0;
+
+ constructor(initialCapacity = 256) {
+ this.buf_ = new Uint8Array(initialCapacity);
+ this.view_ = new DataView(this.buf_.buffer);
+ }
+
+ get length(): number { return this.len_; }
+
+ private ensure_(bytes: number): void {
+ if (this.len_ + bytes <= this.buf_.byteLength) return;
+ let cap = this.buf_.byteLength * 2;
+ while (cap < this.len_ + bytes) cap *= 2;
+ const next = new Uint8Array(cap);
+ next.set(this.buf_.subarray(0, this.len_));
+ this.buf_ = next;
+ this.view_ = new DataView(next.buffer);
+ }
+
+ u8(v: number): void { this.ensure_(1); this.view_.setUint8(this.len_, v); this.len_ += 1; }
+ u16(v: number): void { this.ensure_(2); this.view_.setUint16(this.len_, v, true); this.len_ += 2; }
+ u32(v: number): void { this.ensure_(4); this.view_.setUint32(this.len_, v >>> 0, true); this.len_ += 4; }
+ f32(v: number): void { this.ensure_(4); this.view_.setFloat32(this.len_, v, true); this.len_ += 4; }
+
+ string(s: string): void {
+ const bytes = textEncoder.encode(s);
+ if (bytes.byteLength > 0xffff) throw new Error('[repl] string field exceeds 65535 utf-8 bytes');
+ this.u16(bytes.byteLength);
+ this.ensure_(bytes.byteLength);
+ this.buf_.set(bytes, this.len_);
+ this.len_ += bytes.byteLength;
+ }
+
+ /** Patch a previously written u16 (e.g. a count written before the loop). */
+ patchU16(offset: number, v: number): void { this.view_.setUint16(offset, v, true); }
+
+ finish(): Uint8Array {
+ return this.buf_.slice(0, this.len_);
+ }
+}
+
+export class ByteReader {
+ private readonly view_: DataView;
+ private readonly bytes_: Uint8Array;
+ private pos_ = 0;
+
+ constructor(data: Uint8Array) {
+ this.bytes_ = data;
+ this.view_ = new DataView(data.buffer, data.byteOffset, data.byteLength);
+ }
+
+ get remaining(): number { return this.bytes_.byteLength - this.pos_; }
+
+ u8(): number { const v = this.view_.getUint8(this.pos_); this.pos_ += 1; return v; }
+ u16(): number { const v = this.view_.getUint16(this.pos_, true); this.pos_ += 2; return v; }
+ u32(): number { const v = this.view_.getUint32(this.pos_, true); this.pos_ += 4; return v; }
+ f32(): number { const v = this.view_.getFloat32(this.pos_, true); this.pos_ += 4; return v; }
+
+ string(): string {
+ const len = this.u16();
+ const s = textDecoder.decode(this.bytes_.subarray(this.pos_, this.pos_ + len));
+ this.pos_ += len;
+ return s;
+ }
+}
+
+// =============================================================================
+// Value codec
+// =============================================================================
+
+/** Entity-ref translation at the wire boundary: the encoder maps a live Entity
+ * to its netId, the decoder maps a netId back to the local Entity (0 when the
+ * target is unknown/not replicated). */
+export interface EntityRefMap {
+ toWire(entity: number): number;
+ fromWire(netId: number): number;
+}
+
+const IDENTITY_REFS: EntityRefMap = { toWire: (e) => e, fromWire: (n) => n };
+
+export function encodeValue(w: ByteWriter, shape: FieldShape, value: unknown, refs: EntityRefMap = IDENTITY_REFS): void {
+ switch (shape.kind) {
+ case 'f32': w.f32(typeof value === 'number' ? value : 0); break;
+ case 'bool': w.u8(value ? 1 : 0); break;
+ case 'string': w.string(typeof value === 'string' ? value : ''); break;
+ case 'entity': w.u32(refs.toWire(typeof value === 'number' ? value : 0)); break;
+ case 'object': {
+ const rec = (value ?? {}) as Record<string, unknown>;
+ for (let i = 0; i < shape.keys.length; i++) {
+ encodeValue(w, shape.shapes[i], rec[shape.keys[i]], refs);
+ }
+ break;
+ }
+ case 'json': w.string(JSON.stringify(value ?? null)); break;
+ }
+}
+
+export function decodeValue(r: ByteReader, shape: FieldShape, refs: EntityRefMap = IDENTITY_REFS): unknown {
+ switch (shape.kind) {
+ case 'f32': return r.f32();
+ case 'bool': return r.u8() !== 0;
+ case 'string': return r.string();
+ case 'entity': return refs.fromWire(r.u32());
+ case 'object': {
+ const out: Record<string, unknown> = {};
+ for (let i = 0; i < shape.keys.length; i++) {
+ out[shape.keys[i]] = decodeValue(r, shape.shapes[i], refs);
+ }
+ return out;
+ }
+ case 'json': return JSON.parse(r.string());
+ }
+}
+
+// =============================================================================
+// State frames
+// =============================================================================
+
+export interface StateEntry {
+ netId: number;
+ componentId: number;
+ fieldMask: number;
+ /** Decoded values for set mask bits, in field-declaration order. */
+ values: unknown[];
+}
+
+export interface StateFrame {
+ tick: number;
+ entries: StateEntry[];
+}
+
+export class FrameWriter {
+ private readonly w_ = new ByteWriter();
+ private readonly countOffset_: number;
+ private count_ = 0;
+
+ constructor(tick: number) {
+ this.w_.u32(FRAME_MAGIC);
+ this.w_.u8(REPLICATION_PROTOCOL_VERSION);
+ this.w_.u32(tick);
+ this.countOffset_ = this.w_.length;
+ this.w_.u16(0);
+ }
+
+ get entryCount(): number { return this.count_; }
+
+ entry(netId: number, table: ReplicationTableEntry, fieldMask: number, data: Record<string, unknown>, refs?: EntityRefMap): void {
+ this.w_.u32(netId);
+ this.w_.u16(table.id);
+ this.w_.u32(fieldMask);
+ for (let i = 0; i < table.fields.length; i++) {
+ if (fieldMask & (1 << i)) {
+ encodeValue(this.w_, table.shapes[i], data[table.fields[i]], refs);
+ }
+ }
+ this.count_++;
+ }
+
+ finish(): Uint8Array {
+ this.w_.patchU16(this.countOffset_, this.count_);
+ return this.w_.finish();
+ }
+}
+
+export function decodeStateFrame(payload: Uint8Array, table: ReplicationTable, refs?: EntityRefMap): StateFrame {
+ const r = new ByteReader(payload);
+ if (r.u32() !== FRAME_MAGIC) throw new Error('[repl] bad state frame magic');
+ const version = r.u8();
+ if (version !== REPLICATION_PROTOCOL_VERSION) {
+ throw new Error(`[repl] state frame protocol v${version}, expected v${REPLICATION_PROTOCOL_VERSION}`);
+ }
+ const tick = r.u32();
+ const count = r.u16();
+ const entries: StateEntry[] = [];
+ for (let n = 0; n < count; n++) {
+ const netId = r.u32();
+ const componentId = r.u16();
+ const fieldMask = r.u32();
+ const te = table.entries[componentId];
+ if (!te) throw new Error(`[repl] state frame names unknown component id ${componentId}`);
+ const values: unknown[] = [];
+ for (let i = 0; i < te.fields.length; i++) {
+ if (fieldMask & (1 << i)) values.push(decodeValue(r, te.shapes[i], refs));
+ }
+ entries.push({ netId, componentId, fieldMask, values });
+ }
+ return { tick, entries };
+}
diff --git a/sdk/src/net/replication/components.ts b/sdk/src/net/replication/components.ts
new file mode 100644
index 000000000..25d6d395c
--- /dev/null
+++ b/sdk/src/net/replication/components.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file components.ts
+ * @brief The replication marker components. `Replicated` is the authoring
+ * surface: put it on a server entity and the entity replicates —
+ * which fields flow is declared per component (`replicated`
+ * 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.
+ */
+import { defineComponent, defineTag } from '../../component';
+
+export interface ReplicatedData {
+ /** Stable network identity, allocated by the server (0 = unassigned). */
+ netId: number;
+ /** Owning connection id (0 = the server) — input/authority routing (N4). */
+ owner: number;
+}
+
+export const Replicated = defineComponent<ReplicatedData>('Replicated', {
+ netId: 0,
+ owner: 0,
+});
+
+/** Client-side proxy of a server entity: state arrives over the wire. */
+export const NetGhost = defineTag('NetGhost');
+
+/**
+ * Re-register after a user-component registry reset (project reload wipes the
+ * per-context catalogue; the interned-by-name _id keeps old const handles and
+ * fresh registrations pointing at the same storage). ReplicationPlugin.build
+ * calls this, so any app built after a reset still serializes these.
+ */
+export function ensureReplicationComponentsRegistered(): void {
+ defineComponent<ReplicatedData>('Replicated', { netId: 0, owner: 0 });
+ defineTag('NetGhost');
+}
diff --git a/sdk/src/net/replication/index.ts b/sdk/src/net/replication/index.ts
new file mode 100644
index 000000000..9e068f1fc
--- /dev/null
+++ b/sdk/src/net/replication/index.ts
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+export {
+ REPLICATION_PROTOCOL_VERSION,
+ REPLICATION_CHANNEL,
+ ReplMsg,
+ type ReplComponentSchema,
+ type ReplHelloRequest,
+ type ReplHelloResponse,
+ type ReplSpawnEntity,
+ type ReplSpawnBatch,
+ type ReplDespawnBatch,
+} from './protocol';
+export {
+ buildReplicationTable,
+ tableSchemas,
+ diffSchemas,
+ encodeValue,
+ decodeValue,
+ decodeStateFrame,
+ ByteWriter,
+ ByteReader,
+ FrameWriter,
+ type FieldShape,
+ type ReplicationTable,
+ type ReplicationTableEntry,
+ type EntityRefMap,
+ type StateEntry,
+ type StateFrame,
+} from './codec';
+export { Replicated, NetGhost, type ReplicatedData } from './components';
+export { NetIds } from './NetIds';
+export { ReplicationServer } from './server';
+export { ReplicationClient } from './client';
+export {
+ ReplicationPlugin,
+ replicationPlugin,
+ NetSession,
+ Net,
+ type NetRoleKind,
+} from './ReplicationPlugin';
diff --git a/sdk/src/net/replication/protocol.ts b/sdk/src/net/replication/protocol.ts
new file mode 100644
index 000000000..46461e522
--- /dev/null
+++ b/sdk/src/net/replication/protocol.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file protocol.ts
+ * @brief The replication wire contract — one dependency-free module both
+ * endpoints import (the playProtocol pattern). The control plane
+ * rides NetChannel JSON events/RPC; the state plane rides the binary
+ * 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.
+ */
+import type { SceneComponentData } from '../../scene';
+
+export const REPLICATION_PROTOCOL_VERSION = 1;
+
+/** NetChannel binary channel id the snapshot frames ride on. */
+export const REPLICATION_CHANNEL = 1;
+
+/** Control-plane message types (NetChannel event / request names). */
+export const ReplMsg = {
+ hello: 'repl:hello',
+ spawn: 'repl:spawn',
+ despawn: 'repl:despawn',
+} as const;
+
+/** One component's replication schema, as exchanged for handshake comparison. */
+export interface ReplComponentSchema {
+ name: string;
+ fields: string[];
+}
+
+export interface ReplHelloRequest {
+ protocolVersion: number;
+ /** EHT layout hash — builtins replicate by heap layout, so both ends must
+ * run the same component ABI. */
+ abiHash: string;
+ /** The client's full replication table, for exact schema comparison. */
+ components: ReplComponentSchema[];
+}
+
+export interface ReplHelloOk {
+ ok: true;
+ /** Server-assigned connection id — the ownership handle (0 = the server). */
+ connectionId: number;
+ /** The server's current fixed tick, so the client can offset its buffers. */
+ tick: number;
+ fixedDelta: number;
+}
+
+export interface ReplHelloError {
+ ok: false;
+ error: string;
+}
+
+export type ReplHelloResponse = ReplHelloOk | ReplHelloError;
+
+/** One replicated entity's spawn payload. Component data is the scene
+ * serialization shape (loadComponent applies it, out-of-band codecs and
+ * validation included); entity-ref fields arrive rewritten to netIds. */
+export interface ReplSpawnEntity {
+ netId: number;
+ name: string;
+ /** netId of the replicated parent, or 0 for a root. */
+ parentNetId: number;
+ components: SceneComponentData[];
+}
+
+export interface ReplSpawnBatch {
+ tick: number;
+ entities: ReplSpawnEntity[];
+}
+
+export interface ReplDespawnBatch {
+ tick: number;
+ netIds: number[];
+}
diff --git a/sdk/src/net/replication/server.ts b/sdk/src/net/replication/server.ts
new file mode 100644
index 000000000..11f8894d2
--- /dev/null
+++ b/sdk/src/net/replication/server.ts
@@ -0,0 +1,284 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file server.ts
+ * @brief The authoritative endpoint. Owns connections (one NetChannel per
+ * transport), answers the handshake, and each fixed tick: replicates
+ * spawns/despawns of `Replicated` entities on the JSON control plane
+ * 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.
+ */
+import type { World } from '../../world';
+import type { Entity } from '../../types';
+import { Name, Parent, getComponent } from '../../component';
+import { ABI_LAYOUT_HASH } from '../../component.generated';
+import { serializeEntityComponents, type SceneComponentData } from '../../scene';
+import { NetChannel, type NetTransport } from '../NetChannel';
+import { log } from '../../logger';
+import {
+ REPLICATION_CHANNEL, REPLICATION_PROTOCOL_VERSION, ReplMsg,
+ type ReplDespawnBatch, type ReplHelloRequest, type ReplHelloResponse, type ReplSpawnBatch, type ReplSpawnEntity,
+} from './protocol';
+import {
+ buildReplicationTable, diffSchemas, tableSchemas, FrameWriter,
+ type EntityRefMap, type ReplicationTable,
+} from './codec';
+import { Replicated, type ReplicatedData } from './components';
+import { NetIds } from './NetIds';
+
+interface Connection {
+ id: number;
+ channel: NetChannel;
+ /** Handshake completed and the initial world spawn has been sent. */
+ ready: boolean;
+}
+
+function deepClone<T>(v: T): T {
+ if (v === null || typeof v !== 'object') return v;
+ if (Array.isArray(v)) return v.map(deepClone) as T;
+ const out: Record<string, unknown> = {};
+ for (const k in v) out[k] = deepClone((v as Record<string, unknown>)[k]);
+ return out as T;
+}
+
+function fieldEqual(a: unknown, b: unknown): boolean {
+ if (a === b) return true;
+ if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false;
+ const ra = a as Record<string, unknown>;
+ const rb = b as Record<string, unknown>;
+ const ka = Object.keys(ra);
+ if (ka.length !== Object.keys(rb).length) return false;
+ for (const k of ka) if (!fieldEqual(ra[k], rb[k])) return false;
+ return true;
+}
+
+export class ReplicationServer {
+ private readonly world_: World;
+ private readonly netIds_ = new NetIds();
+ private readonly connections_ = new Map<number, Connection>();
+ private nextConnectionId_ = 1;
+ private table_: ReplicationTable | null = null;
+ /** Last broadcast value per entity × table entry: entity → componentId → field record. */
+ private readonly shadow_ = new Map<Entity, Map<number, Record<string, unknown>>>();
+ private readonly known_ = new Set<Entity>();
+ /** known entity → netId, owned by sampling. Survives the onDespawn hook
+ * clearing netIds_, so a despawn can still broadcast its id. */
+ private readonly knownNetIds_ = new Map<Entity, number>();
+ private tick_ = 0;
+
+ constructor(world: World) {
+ this.world_ = world;
+ world.onDespawn((e) => {
+ // Sampling handles replicated despawns; this catches direct holes.
+ this.netIds_.unregisterEntity(e);
+ });
+ }
+
+ /** Lazily built so components defined after plugin install still count. */
+ get table(): ReplicationTable {
+ return (this.table_ ??= buildReplicationTable());
+ }
+
+ get netIds(): NetIds {
+ return this.netIds_;
+ }
+
+ get connectionCount(): number {
+ return this.connections_.size;
+ }
+
+ private get refs_(): EntityRefMap {
+ return {
+ toWire: (entity) => this.netIds_.netIdOf(entity as Entity) ?? 0,
+ fromWire: (netId) => (this.netIds_.entityOf(netId) as number | undefined) ?? 0,
+ };
+ }
+
+ /** Accept a transport (server-side end of one client link). */
+ attachConnection(transport: NetTransport): number {
+ const id = this.nextConnectionId_++;
+ const channel = new NetChannel(transport);
+ const conn: Connection = { id, channel, ready: false };
+ this.connections_.set(id, conn);
+
+ channel.handle<ReplHelloRequest, ReplHelloResponse>(ReplMsg.hello, (req) => {
+ if (req.protocolVersion !== REPLICATION_PROTOCOL_VERSION) {
+ return { ok: false, error: `protocol v${req.protocolVersion}, server runs v${REPLICATION_PROTOCOL_VERSION}` };
+ }
+ if (req.abiHash !== ABI_LAYOUT_HASH) {
+ return { ok: false, error: 'component ABI hash mismatch — client and server run different builds' };
+ }
+ const mismatch = diffSchemas(tableSchemas(this.table), req.components);
+ if (mismatch) {
+ return { ok: false, error: `replication schema mismatch: ${mismatch}` };
+ }
+ // The initial world spawn goes out on the next microtask — after this
+ // response is on the wire — and flips the connection hot.
+ Promise.resolve().then(() => this.sendInitialState_(conn));
+ return { ok: true, connectionId: id, tick: this.tick_, fixedDelta: 0 };
+ });
+
+ return id;
+ }
+
+ detachConnection(id: number): void {
+ const conn = this.connections_.get(id);
+ if (!conn) return;
+ conn.channel.dispose();
+ this.connections_.delete(id);
+ }
+
+ /** One replication tick: spawns/despawns on the control plane, dirty
+ * fields as one binary delta frame. Runs in FixedPostUpdate. */
+ sample(tick: number): void {
+ this.tick_ = tick;
+ if (this.connections_.size === 0) return;
+
+ const current = this.world_.getEntitiesWithComponents([Replicated]);
+ const currentSet = new Set(current);
+
+ const spawned: ReplSpawnEntity[] = [];
+ for (const e of current) {
+ if (!this.known_.has(e)) {
+ spawned.push(this.registerEntity_(e));
+ }
+ }
+
+ const despawnedIds: number[] = [];
+ for (const e of [...this.known_]) {
+ if (!currentSet.has(e) || !this.world_.valid(e)) {
+ const netId = this.knownNetIds_.get(e);
+ if (netId !== undefined) {
+ despawnedIds.push(netId);
+ this.netIds_.unregister(netId);
+ }
+ this.known_.delete(e);
+ this.knownNetIds_.delete(e);
+ this.shadow_.delete(e);
+ }
+ }
+
+ if (spawned.length > 0) {
+ this.broadcast_((c) => c.channel.send<ReplSpawnBatch>(ReplMsg.spawn, { tick, entities: spawned }));
+ }
+ if (despawnedIds.length > 0) {
+ this.broadcast_((c) => c.channel.send<ReplDespawnBatch>(ReplMsg.despawn, { tick, netIds: despawnedIds }));
+ }
+
+ const frame = new FrameWriter(tick);
+ for (const e of this.known_) {
+ this.diffEntity_(e, frame);
+ }
+ if (frame.entryCount > 0) {
+ const payload = frame.finish();
+ this.broadcast_((c) => c.channel.sendBinary(REPLICATION_CHANNEL, payload));
+ }
+ }
+
+ private registerEntity_(e: Entity): ReplSpawnEntity {
+ const repl = this.world_.tryGet(e, Replicated) as ReplicatedData;
+ if (repl.netId === 0) {
+ repl.netId = this.netIds_.allocate();
+ this.world_.set(e, Replicated, repl);
+ }
+ this.netIds_.register(repl.netId, e);
+ this.known_.add(e);
+ this.knownNetIds_.set(e, repl.netId);
+ this.seedShadow_(e);
+ return this.spawnPayload_(e, repl.netId);
+ }
+
+ private seedShadow_(e: Entity): void {
+ const perComp = new Map<number, Record<string, unknown>>();
+ for (const te of this.table.entries) {
+ if (!this.world_.has(e, te.def)) continue;
+ const data = this.world_.tryGet(e, te.def) as Record<string, unknown>;
+ const snap: Record<string, unknown> = {};
+ for (const f of te.fields) snap[f] = deepClone(data[f]);
+ perComp.set(te.id, snap);
+ }
+ this.shadow_.set(e, perComp);
+ }
+
+ private spawnPayload_(e: Entity, netId: number): ReplSpawnEntity {
+ const components = serializeEntityComponents(this.world_, e).map((c) => this.rewriteEntityRefs_(c));
+ // Name/Parent are structural components serializeEntityComponents skips
+ // (scene records carry them beside the component list; so does this).
+ const nameComp = this.world_.tryGet(e, Name) as { value: string } | null;
+ const parentComp = this.world_.tryGet(e, Parent) as { entity: number } | null;
+ const parentNetId = parentComp ? (this.netIds_.netIdOf(parentComp.entity as Entity) ?? 0) : 0;
+ return {
+ netId,
+ name: nameComp?.value ?? '',
+ parentNetId,
+ components,
+ };
+ }
+
+ private rewriteEntityRefs_(c: SceneComponentData): SceneComponentData {
+ const entityFields = getComponent(c.type)?.entityFields ?? [];
+ if (entityFields.length === 0) return c;
+ const data = { ...c.data };
+ for (const f of entityFields) {
+ if (typeof data[f] === 'number') {
+ data[f] = this.netIds_.netIdOf(data[f] as Entity) ?? 0;
+ }
+ }
+ return { type: c.type, data };
+ }
+
+ private diffEntity_(e: Entity, frame: FrameWriter): void {
+ const perComp = this.shadow_.get(e);
+ if (!perComp) return;
+ const netId = this.netIds_.netIdOf(e);
+ if (netId === undefined) return;
+ for (const te of this.table.entries) {
+ if (!this.world_.has(e, te.def)) continue;
+ const data = this.world_.tryGet(e, te.def) as Record<string, unknown>;
+ let snap = perComp.get(te.id);
+ if (!snap) {
+ // Component added after spawn: replicate all fields.
+ snap = {};
+ perComp.set(te.id, snap);
+ }
+ let mask = 0;
+ for (let i = 0; i < te.fields.length; i++) {
+ const f = te.fields[i];
+ if (!(f in snap) || !fieldEqual(data[f], snap[f])) {
+ mask |= 1 << i;
+ snap[f] = deepClone(data[f]);
+ }
+ }
+ if (mask !== 0) {
+ frame.entry(netId, te, mask, data, this.refs_);
+ }
+ }
+ }
+
+ private sendInitialState_(conn: Connection): void {
+ if (!this.connections_.has(conn.id)) return;
+ // Everything known right now, full component payloads (current state
+ // included — no separate baseline frame needed).
+ const entities: ReplSpawnEntity[] = [];
+ for (const e of this.known_) {
+ const netId = this.netIds_.netIdOf(e);
+ if (netId !== undefined) entities.push(this.spawnPayload_(e, netId));
+ }
+ if (entities.length > 0) {
+ conn.channel.send<ReplSpawnBatch>(ReplMsg.spawn, { tick: this.tick_, entities });
+ }
+ conn.ready = true;
+ }
+
+ private broadcast_(fn: (conn: Connection) => void): void {
+ for (const conn of this.connections_.values()) {
+ if (!conn.ready) continue;
+ try {
+ fn(conn);
+ } catch (err) {
+ log.warn('repl', `broadcast to connection ${conn.id} failed`, err);
+ }
+ }
+ }
+}
diff --git a/sdk/src/resource.ts b/sdk/src/resource.ts
index 0a534cc9b..2c47d6899 100644
--- a/sdk/src/resource.ts
+++ b/sdk/src/resource.ts
@@ -167,6 +167,12 @@ export interface TimeData {
* fixed-step simulation (e.g. physics) onto the variable render rate.
*/
fixedAlpha: number;
+ /**
+ * Monotonic count of completed FixedUpdate steps — the simulation's own
+ * time axis (frameCount counts render frames, which vary per machine).
+ * Netcode stamps snapshots and input commands with this.
+ */
+ fixedTick: number;
}
export const Time = defineResource<TimeData>({
@@ -175,5 +181,6 @@ export const Time = defineResource<TimeData>({
frameCount: 0,
fixedDelta: 1 / 60,
fixedAlpha: 0,
+ fixedTick: 0,
}, 'Time');
diff --git a/sdk/src/scene.ts b/sdk/src/scene.ts
index 66cf4a317..91ed7bae5 100644
--- a/sdk/src/scene.ts
+++ b/sdk/src/scene.ts
@@ -528,6 +528,36 @@ export function loadComponent(world: World, entity: Entity, compData: SceneCompo
// fields rather than from the components list, so we omit them here.
const STRUCTURAL_COMPONENTS = new Set(['Name', 'Parent', 'Children', 'WorldTransform']);
+/**
+ * One entity's serializable component payloads — the per-entity primitive
+ * serializeScene is built from, also the spawn-replication payload (RC11):
+ * skips structural + transient components, folds out-of-band codec state in.
+ * Round-trips through {@link loadComponent}.
+ */
+export function serializeEntityComponents(world: World, entity: Entity): SceneComponentData[] {
+ const entityNum = entity as unknown as number;
+ const components: SceneComponentData[] = [];
+ for (const typeName of world.getComponentTypes(entity)) {
+ if (STRUCTURAL_COMPONENTS.has(typeName)) continue;
+ const comp = getComponent(typeName);
+ if (!comp) continue;
+ // Runtime-only components (per-frame pointer/drag/hover state) never
+ // persist — their systems rebuild them each frame. See ComponentMetadata.transient.
+ if (comp.transient) continue;
+ const data = world.tryGet(entity, comp);
+ if (data === null) continue;
+ const payload = data as Record<string, unknown>;
+ // Components with out-of-band state (e.g. TilemapLayer chunks) fold
+ // it into the record via their registered codec.
+ sceneComponentCodecs.get(typeName)?.exportData?.(entityNum, payload);
+ components.push({
+ type: typeName,
+ data: payload,
+ });
+ }
+ return components;
+}
+
/**
* Walks the live world and produces a SceneData that round-trips through
* loadSceneData. Editors call this on save; external tools (prefab extract,
@@ -575,25 +605,7 @@ export function serializeScene(world: World, sceneName = 'scene'): SceneData {
const nameComp = world.tryGet(entity, Name) as { value: string } | null;
const name = nameComp?.value ?? `Entity_${entityNum}`;
- const components: SceneComponentData[] = [];
- for (const typeName of world.getComponentTypes(entity)) {
- if (STRUCTURAL_COMPONENTS.has(typeName)) continue;
- const comp = getComponent(typeName);
- if (!comp) continue;
- // Runtime-only components (per-frame pointer/drag/hover state) never
- // persist — their systems rebuild them each frame. See ComponentMetadata.transient.
- if (comp.transient) continue;
- const data = world.tryGet(entity, comp);
- if (data === null) continue;
- const payload = data as Record<string, unknown>;
- // Components with out-of-band state (e.g. TilemapLayer chunks) fold
- // it into the record via their registered codec.
- sceneComponentCodecs.get(typeName)?.exportData?.(entityNum, payload);
- components.push({
- type: typeName,
- data: payload,
- });
- }
+ const components = serializeEntityComponents(world, entity);
entities.push({
id: entityNum,
diff --git a/sdk/src/webAppFactory.ts b/sdk/src/webAppFactory.ts
index 70211c251..277157485 100644
--- a/sdk/src/webAppFactory.ts
+++ b/sdk/src/webAppFactory.ts
@@ -14,6 +14,7 @@ import { timelinePlugin } from './timeline';
import { timerPlugin } from './timer';
import { lifecyclePlugin } from './lifecycle';
import { navPlugin, fsmPlugin, btPlugin, perceptionPlugin } from './ai';
+import { replicationPlugin } from './net/replication';
import { SpinePlugin } from './spine';
import { createFetchSideModuleHost, type SideModuleHost } from './sideModules';
@@ -60,7 +61,7 @@ export interface CreateWebAppOptions extends WebAppOptions {
wasmBaseUrl?: string;
}
-const basePlugins = [timerPlugin, lifecyclePlugin(), animationPlugin, audioPlugin, particlePlugin, mesh2dPlugin, tilemapPlugin, postProcessPlugin, timelinePlugin, perceptionPlugin, fsmPlugin, btPlugin, navPlugin];
+const basePlugins = [timerPlugin, lifecyclePlugin(), animationPlugin, audioPlugin, particlePlugin, mesh2dPlugin, tilemapPlugin, postProcessPlugin, timelinePlugin, perceptionPlugin, fsmPlugin, btPlugin, navPlugin, replicationPlugin];
export function createWebApp(module: ESEngineModule, options?: CreateWebAppOptions): App {
const sideModules: SideModuleHost | undefined = options?.sideModules
diff --git a/sdk/tests/replication-wasm.test.ts b/sdk/tests/replication-wasm.test.ts
new file mode 100644
index 000000000..a286d2117
--- /dev/null
+++ b/sdk/tests/replication-wasm.test.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file RC11 N2 over the real boundary: Transform (C++-backed, heap storage,
+ * vec3/quat object shapes) replicates between two Apps that each own a
+ * C++ Registry in the shared wasm module. The `replicated` annotation
+ * on Transform.hpp drives the whole pipeline — no per-component code.
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { App } from '../src/app';
+import { Transform, getReplicatedFields } from '../src/component';
+import type { ESEngineModule, CppRegistry } from '../src/wasm';
+import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
+import { MemoryTransport } from '../src/net/MemoryTransport';
+import { replicationPlugin, Net, Replicated, NetGhost } from '../src/net/replication';
+
+const STEP = 1 / 60;
+
+describe.skipIf(!HAS_WASM)('replication over the wasm boundary (Transform)', () => {
+ let module: ESEngineModule;
+
+ beforeAll(async () => {
+ module = await loadWasmModule();
+ });
+
+ function makeWasmApp(): App {
+ const app = App.new();
+ const registry = new (module as any).Registry() as CppRegistry;
+ app.connectCpp(registry, module);
+ app.addPlugin(replicationPlugin);
+ return app;
+ }
+
+ it('replicates the annotated Transform pose, f32-exact, computed fields untouched', async () => {
+ expect(getReplicatedFields('Transform')).toEqual(['position', 'rotation', 'scale']);
+
+ const serverApp = makeWasmApp();
+ const clientApp = makeWasmApp();
+ const server = serverApp.getResource(Net).startServer();
+ const [ta, tb] = MemoryTransport.pair();
+ server.attachConnection(ta);
+ await clientApp.getResource(Net).connect(tb);
+
+ const e = serverApp.world.spawn('hero');
+ serverApp.world.insert(e, Transform, { position: { x: 10.5, y: -3.25, z: 0 } });
+ serverApp.world.insert(e, Replicated, {});
+
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+
+ const ghosts = clientApp.world.getEntitiesWithComponents([Replicated]);
+ expect(ghosts).toHaveLength(1);
+ const ghost = ghosts[0];
+ expect(clientApp.world.has(ghost, NetGhost)).toBe(true);
+ const t0 = clientApp.world.tryGet(ghost, Transform)!;
+ expect(t0.position.x).toBe(10.5);
+ expect(t0.position.y).toBe(-3.25);
+
+ // Move on the server — only the annotated pose fields travel.
+ const st = serverApp.world.tryGet(e, Transform)!;
+ st.position.x = 99.75;
+ st.scale.x = 2;
+ serverApp.world.set(e, Transform, st);
+
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+
+ const t1 = clientApp.world.tryGet(ghost, Transform)!;
+ expect(t1.position.x).toBe(99.75);
+ expect(t1.position.y).toBe(-3.25);
+ expect(t1.scale.x).toBe(2);
+
+ // Server-side despawn tears the ghost down.
+ serverApp.world.despawn(e);
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+ expect(clientApp.world.getEntitiesWithComponents([Replicated])).toHaveLength(0);
+ });
+});
diff --git a/sdk/tests/replication.test.ts b/sdk/tests/replication.test.ts
new file mode 100644
index 000000000..fc0726c81
--- /dev/null
+++ b/sdk/tests/replication.test.ts
@@ -0,0 +1,309 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file RC11 N2 keystone gate: two Apps in one process — an authoritative
+ * server and a replica client wired through MemoryTransport — step
+ * fixed ticks and must agree field-by-field. Covers the handshake
+ * (version/ABI/schema fail-loud), spawn/despawn ghosts, delta frames
+ * (only dirty fields move), late-joiner current-state spawn, and the
+ * reflection-driven codec round trip.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { App } from '../src/app';
+import { defineComponent, clearUserComponents } from '../src/component';
+import { ABI_LAYOUT_HASH } from '../src/component.generated';
+import { MemoryTransport } from '../src/net/MemoryTransport';
+import { NetChannel } from '../src/net/NetChannel';
+import {
+ replicationPlugin, Net, Replicated, NetGhost,
+ ReplMsg, REPLICATION_PROTOCOL_VERSION,
+ buildReplicationTable, tableSchemas, diffSchemas,
+ ByteWriter, ByteReader, encodeValue, decodeValue, FrameWriter, decodeStateFrame,
+ type ReplHelloResponse, type FieldShape,
+} from '../src/net/replication';
+
+const STEP = 1 / 60;
+
+function makeApp(): App {
+ const app = App.new();
+ app.addPlugin(replicationPlugin);
+ return app;
+}
+
+/** One server + one client, already handshaken over a MemoryTransport pair. */
+async function makePair() {
+ const serverApp = makeApp();
+ const clientApp = makeApp();
+ const server = serverApp.getResource(Net).startServer();
+ const [ta, tb] = MemoryTransport.pair();
+ server.attachConnection(ta);
+ const client = await clientApp.getResource(Net).connect(tb);
+ return { serverApp, clientApp, server, client };
+}
+
+let NetPos: ReturnType<typeof defineComponent<{ x: number; y: number; secret: number }>>;
+let NetTag: ReturnType<typeof defineComponent<{ label: string; active: boolean }>>;
+
+beforeEach(() => {
+ clearUserComponents();
+ NetPos = defineComponent('NetPos', { x: 0, y: 0, secret: 0 }, {
+ replicatedFields: ['x', 'y'],
+ });
+ NetTag = defineComponent('NetTag', { label: '', active: false }, {
+ replicatedFields: ['label', 'active'],
+ });
+});
+
+describe('replication handshake', () => {
+ it('accepts a matching client and assigns a connection id', async () => {
+ const { client } = await makePair();
+ expect(client.connected).toBe(true);
+ expect(client.connectionId).toBeGreaterThan(0);
+ });
+
+ it('refuses a protocol version mismatch', async () => {
+ const serverApp = makeApp();
+ serverApp.getResource(Net).startServer().attachConnection(MemoryTransport.pair()[0]);
+ const [ta, tb] = MemoryTransport.pair();
+ serverApp.getResource(Net).server!.attachConnection(ta);
+ const raw = new NetChannel(tb);
+ const res = await raw.request<ReplHelloResponse>(ReplMsg.hello, {
+ protocolVersion: REPLICATION_PROTOCOL_VERSION + 1,
+ abiHash: ABI_LAYOUT_HASH,
+ components: [],
+ });
+ expect(res.ok).toBe(false);
+ if (!res.ok) expect(res.error).toMatch(/protocol/);
+ });
+
+ it('refuses an ABI hash mismatch', async () => {
+ const serverApp = makeApp();
+ const server = serverApp.getResource(Net).startServer();
+ const [ta, tb] = MemoryTransport.pair();
+ server.attachConnection(ta);
+ const raw = new NetChannel(tb);
+ const res = await raw.request<ReplHelloResponse>(ReplMsg.hello, {
+ protocolVersion: REPLICATION_PROTOCOL_VERSION,
+ abiHash: 'deadbeef',
+ components: tableSchemas(buildReplicationTable()),
+ });
+ expect(res.ok).toBe(false);
+ if (!res.ok) expect(res.error).toMatch(/ABI/);
+ });
+
+ it('refuses a replication schema mismatch', async () => {
+ const serverApp = makeApp();
+ const server = serverApp.getResource(Net).startServer();
+ const [ta, tb] = MemoryTransport.pair();
+ server.attachConnection(ta);
+ const raw = new NetChannel(tb);
+ const schemas = tableSchemas(buildReplicationTable());
+ schemas[0] = { ...schemas[0], fields: [...schemas[0].fields, 'phantom'] };
+ const res = await raw.request<ReplHelloResponse>(ReplMsg.hello, {
+ protocolVersion: REPLICATION_PROTOCOL_VERSION,
+ abiHash: ABI_LAYOUT_HASH,
+ components: schemas,
+ });
+ expect(res.ok).toBe(false);
+ if (!res.ok) expect(res.error).toMatch(/schema/);
+ });
+});
+
+describe('spawn / state / despawn replication', () => {
+ it('replicates a spawned entity to the client as a NetGhost', async () => {
+ const { serverApp, clientApp, client } = await makePair();
+
+ const e = serverApp.world.spawn('player');
+ serverApp.world.insert(e, Replicated, {});
+ serverApp.world.insert(e, NetPos, { x: 10, y: 20, secret: 42 });
+
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+
+ const netId = clientApp.world.getEntitiesWithComponents([Replicated]);
+ expect(netId).toHaveLength(1);
+ const ghost = netId[0];
+ expect(clientApp.world.has(ghost, NetGhost)).toBe(true);
+ const pos = clientApp.world.tryGet(ghost, NetPos)!;
+ expect(pos.x).toBe(10);
+ expect(pos.y).toBe(20);
+ // Spawn carries the full component payload — including non-replicated
+ // fields (spawn is scene-shaped); only per-tick deltas are filtered.
+ expect(pos.secret).toBe(42);
+ const repl = clientApp.world.tryGet(ghost, Replicated)!;
+ expect(repl.netId).toBeGreaterThan(0);
+ expect(client.netIds.entityOf(repl.netId)).toBe(ghost);
+ });
+
+ it('streams only dirty replicated fields, and goes quiet when nothing changes', async () => {
+ const serverApp = makeApp();
+ const clientApp = makeApp();
+ const server = serverApp.getResource(Net).startServer();
+ // Manual flush so the test can observe exactly what each tick emits.
+ const [ta, tb] = MemoryTransport.pair();
+ server.attachConnection(ta);
+ const connectP = clientApp.getResource(Net).connect(tb);
+ await connectP;
+
+ const e = serverApp.world.spawn('mover');
+ serverApp.world.insert(e, Replicated, {});
+ serverApp.world.insert(e, NetPos, { x: 1, y: 2, secret: 3 });
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+ const ghost = clientApp.world.getEntitiesWithComponents([Replicated])[0];
+
+ //
+
+ // Move on the server; secret (not replicated) also changes.
+ const pos = serverApp.world.tryGet(e, NetPos)!;
+ pos.x = 100;
+ pos.secret = 999;
+ serverApp.world.set(e, NetPos, pos);
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+
+ const gpos = clientApp.world.tryGet(ghost, NetPos)!;
+ expect(gpos.x).toBe(100);
+ expect(gpos.y).toBe(2);
+ // secret keeps its spawn-time value: never re-sent per tick.
+ expect(gpos.secret).toBe(3);
+ });
+
+ it('a quiet server sends no state frames', async () => {
+ const serverApp = makeApp();
+ const server = serverApp.getResource(Net).startServer();
+ const [ta, tb] = MemoryTransport.pair({ manualFlush: true });
+ server.attachConnection(ta);
+
+ const clientApp = makeApp();
+ const connectP = clientApp.getResource(Net).connect(tb);
+ // Manual flush: pump the handshake both ways.
+ for (let i = 0; i < 8; i++) { ta.flush(); tb.flush(); await Promise.resolve(); }
+ await connectP;
+
+ const e = serverApp.world.spawn('idle');
+ serverApp.world.insert(e, Replicated, {});
+ serverApp.world.insert(e, NetPos, {});
+ await serverApp.tick(STEP);
+ ta.flush();
+
+ // Nothing changed since the spawn tick → subsequent ticks emit nothing.
+ await serverApp.tick(STEP);
+ await serverApp.tick(STEP);
+ expect(ta.pendingCount).toBe(0);
+ });
+
+ it('replicates despawn', async () => {
+ const { serverApp, clientApp } = await makePair();
+ const e = serverApp.world.spawn('temp');
+ serverApp.world.insert(e, Replicated, {});
+ serverApp.world.insert(e, NetPos, {});
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+ expect(clientApp.world.getEntitiesWithComponents([Replicated])).toHaveLength(1);
+
+ serverApp.world.despawn(e);
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+ expect(clientApp.world.getEntitiesWithComponents([Replicated])).toHaveLength(0);
+ });
+
+ it('a late joiner receives current state, not spawn-time state', async () => {
+ const serverApp = makeApp();
+ const server = serverApp.getResource(Net).startServer();
+
+ // First client so the server starts replicating at all.
+ const clientA = makeApp();
+ const [a1, a2] = MemoryTransport.pair();
+ server.attachConnection(a1);
+ await clientA.getResource(Net).connect(a2);
+
+ const e = serverApp.world.spawn('veteran');
+ serverApp.world.insert(e, Replicated, {});
+ serverApp.world.insert(e, NetPos, { x: 1, y: 1, secret: 0 });
+ await serverApp.tick(STEP);
+
+ // Mutate long after spawn.
+ const pos = serverApp.world.tryGet(e, NetPos)!;
+ pos.x = 777;
+ serverApp.world.set(e, NetPos, pos);
+ await serverApp.tick(STEP);
+
+ // Now a second client joins.
+ const clientB = makeApp();
+ const [b1, b2] = MemoryTransport.pair();
+ server.attachConnection(b1);
+ await clientB.getResource(Net).connect(b2);
+ await clientB.tick(STEP);
+
+ const ghosts = clientB.world.getEntitiesWithComponents([Replicated]);
+ expect(ghosts).toHaveLength(1);
+ expect(clientB.world.tryGet(ghosts[0], NetPos)!.x).toBe(777);
+ });
+
+ it('replicates multiple components and string/bool fields', async () => {
+ const { serverApp, clientApp } = await makePair();
+ const e = serverApp.world.spawn('tagged');
+ serverApp.world.insert(e, Replicated, {});
+ serverApp.world.insert(e, NetPos, { x: 5, y: 6, secret: 0 });
+ serverApp.world.insert(e, NetTag, { label: 'boss', active: true });
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+
+ const ghost = clientApp.world.getEntitiesWithComponents([Replicated])[0];
+ expect(clientApp.world.tryGet(ghost, NetTag)).toEqual({ label: 'boss', active: true });
+
+ const tag = serverApp.world.tryGet(e, NetTag)!;
+ tag.label = 'minion';
+ tag.active = false;
+ serverApp.world.set(e, NetTag, tag);
+ await serverApp.tick(STEP);
+ await clientApp.tick(STEP);
+ expect(clientApp.world.tryGet(ghost, NetTag)).toEqual({ label: 'minion', active: false });
+ });
+});
+
+describe('codec round trip', () => {
+ it('encodes and decodes every shape kind exactly', () => {
+ const shapes: [FieldShape, unknown][] = [
+ [{ kind: 'f32' }, 1.5],
+ [{ kind: 'bool' }, true],
+ [{ kind: 'string' }, '你好 world'],
+ [{ kind: 'object', keys: ['x', 'y'], shapes: [{ kind: 'f32' }, { kind: 'f32' }] }, { x: -2.25, y: 8 }],
+ [{ kind: 'json' }, [1, 'two', { three: 3 }]],
+ ];
+ const w = new ByteWriter();
+ for (const [shape, value] of shapes) encodeValue(w, shape, value);
+ const r = new ByteReader(w.finish());
+ for (const [shape, value] of shapes) expect(decodeValue(r, shape)).toEqual(value);
+ expect(r.remaining).toBe(0);
+ });
+
+ it('entity shapes remap through the ref map at both ends', () => {
+ const w = new ByteWriter();
+ encodeValue(w, { kind: 'entity' }, 12345, { toWire: () => 7, fromWire: (n) => n });
+ const r = new ByteReader(w.finish());
+ expect(decodeValue(r, { kind: 'entity' }, { toWire: (e) => e, fromWire: (n) => n + 1 })).toBe(8);
+ });
+
+ it('state frames round-trip mask-selected fields through the table', () => {
+ const table = buildReplicationTable();
+ const te = table.byName.get('NetPos')!;
+ const fw = new FrameWriter(42);
+ fw.entry(9, te, 0b01, { x: 3.5, y: 0, secret: 1 }); // only x
+ const frame = decodeStateFrame(fw.finish(), table);
+ expect(frame.tick).toBe(42);
+ expect(frame.entries).toHaveLength(1);
+ expect(frame.entries[0].netId).toBe(9);
+ expect(frame.entries[0].fieldMask).toBe(0b01);
+ expect(frame.entries[0].values).toEqual([3.5]);
+ });
+
+ it('diffSchemas pinpoints drift', () => {
+ const a = [{ name: 'A', fields: ['x'] }];
+ expect(diffSchemas(a, [{ name: 'A', fields: ['x'] }])).toBeNull();
+ expect(diffSchemas(a, [])).toMatch(/size/);
+ expect(diffSchemas(a, [{ name: 'B', fields: ['x'] }])).toMatch(/differs/);
+ expect(diffSchemas(a, [{ name: 'A', fields: ['x', 'y'] }])).toMatch(/field list/);
+ });
+});