A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(replication): server-authoritative state replication core — RC11 N2 keystone
esengine54be32664278
diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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?.sideModulesdiff --git a/sdk/tests/replication-wasm.test.ts b/sdk/tests/replication-wasm.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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/);+ });+});