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
fix(net): the wire carries structure and order, not just field values
yhh811b23eac809
diff --git a/docs/astro/src/content/docs/scripting/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdxindex 81c1e1d77..c72b3681f 100644--- a/docs/astro/src/content/docs/scripting/networking.mdx+++ b/docs/astro/src/content/docs/scripting/networking.mdx@@ -105,7 +105,14 @@ clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // per-tick input uplin- **Authority**: only the server simulates; clients see replicated, interpolatedstate (`NetGhost` tags the proxies). The handshake refuses a protocol/ABI/schema- mismatch fail-loud, so drifted builds never desync silently.+ mismatch fail-loud, so drifted builds never desync silently — the schema it+ compares is field names *and* their wire shapes, since a field defaulting to+ `0` on one end and `false` on the other agrees on the name and disagrees on+ the byte count.+- **Structure replicates, not just values**: adding a replicated component to a+ live entity sends its full state; removing one removes it from every ghost.+ Spawn → component add → updates → component remove → despawn all cross the+ wire, and arrive in the order the authority sent them.- **Ownership**: `Replicated.owner` routes a connection's `sendInput` commands toits entities; `client.ownsEntity(e)` answers "is this ghost mine".- **Editor preview**: pick **2–4 Players** in the Play-mode dropdown — a listendiff --git a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdxindex 454236bd2..cd46c6534 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx@@ -103,6 +103,12 @@ clientNet.client?.sendInput({ move: { x: 1, y: 0 } }); // 每 tick 输入上- **权威**:只有服务器做模拟;客户端看到的是复制且插值后的状态(`NetGhost`标记代理实体)。握手会对协议/ABI/schema 不匹配直接拒连,漂移的构建永远不会静默失步。+- **schema 比的是字节布局,不只是字段名**:握手比对字段名**和**它们的 wire+ shape。一端默认 `0`、另一端默认 `false` 的字段,名字相同、字节数不同,+ 光看名字发现不了。+- **结构本身也会复制,不只是值**:给活着的实体加一个 replicated 组件会发送+ 它的完整状态,移除则会从每个 ghost 上移除。spawn → 组件加入 → 更新 →+ 组件移除 → despawn 全部过线,并按权威端发出的顺序抵达。- **归属**:`Replicated.owner` 把某连接的 `sendInput` 命令路由到它的实体;`client.ownsEntity(e)` 回答"这个 ghost 是不是我的"。- **编辑器预览**:在 Play 模式下拉里选 **2–4 Players**——listen server 和diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 4bac995b6..965144976 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6322,7 +6322,7 @@ ReadonlyMap<string, string>## REPLICATION_PROTOCOL_VERSION — const @experimental```-2+3```## RETIRED_COMPONENT_TYPES — const @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 1e5828d11..539ca47ab 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -6510,7 +6510,7 @@ ReadonlyMap<string, string>## REPLICATION_PROTOCOL_VERSION — const @experimental```-2+3```## RESOURCE_BINDINGS — const @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 2c349f916..5a839901b 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6317,7 +6317,7 @@ ReadonlyMap<string, string>## REPLICATION_PROTOCOL_VERSION — const @experimental```-2+3```## RETIRED_COMPONENT_TYPES — const @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 94f741831..c188b38e7 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -6563,7 +6563,7 @@ ReadonlyMap<string, string>## REPLICATION_PROTOCOL_VERSION — const @experimental```-2+3```## RETIRED_COMPONENT_TYPES — const @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 88707e33a..62ecc320e 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -6324,7 +6324,7 @@ ReadonlyMap<string, string>## REPLICATION_PROTOCOL_VERSION — const @experimental```-2+3```## RETIRED_COMPONENT_TYPES — const @experimentaldiff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.tsindex 3a693a264..2edd9ef83 100644--- a/sdk/src/net/replication/client.ts+++ b/sdk/src/net/replication/client.ts@@ -32,6 +32,7 @@ import {REPLICATION_CHANNEL, REPLICATION_PROTOCOL_VERSION, ReplMsg,type ReplAckMsg, type ReplDespawnBatch, type ReplHelloRequest, type ReplHelloResponse,type ReplInputMsg, type ReplSpawnBatch, type ReplSpawnEntity,+ type ReplComponentRemoveBatch,} from './protocol';import {buildReplicationTable, cloneValue, decodeStateFrame, tableSchemas,@@ -111,6 +112,13 @@ export interface ReplicationClientOptions {prediction?: PredictionOptions;}+/** One received message, tagged so the inbox can stay a single ordered queue. */+type PendingOp =+ | { kind: 'spawn'; batch: ReplSpawnBatch }+ | { kind: 'despawn'; batch: ReplDespawnBatch }+ | { kind: 'remove'; batch: ReplComponentRemoveBatch }+ | { kind: 'state'; frame: Uint8Array };+export class ReplicationClient {private readonly world_: World;private readonly netIds_ = new NetIds();@@ -119,9 +127,11 @@ export class ReplicationClient {private table_: ReplicationTable | null = null;private connectionId_ = 0;private serverTick_ = 0;- private readonly pendingFrames_: Uint8Array[] = [];- private readonly pendingSpawns_: ReplSpawnBatch[] = [];- private readonly pendingDespawns_: ReplDespawnBatch[] = [];+ /** Everything received since the last fixed step, in ARRIVAL order — one+ * queue, not one per kind. Sorting by kind reorders across ticks: a leave+ * at tick N and a re-enter at N+1 arriving together replay as+ * re-enter-then-leave, and the entity is gone on the client for good. */+ private readonly inbox_: PendingOp[] = [];private readonly interp_: InterpolationState | null;private inputSeq_ = 0;private prediction_: PredictionOptions | null;@@ -179,14 +189,15 @@ export class ReplicationClient {// 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.on<ReplSpawnBatch>(ReplMsg.spawn, (batch) => this.inbox_.push({ kind: 'spawn', batch }));+ channel.on<ReplDespawnBatch>(ReplMsg.despawn, (batch) => this.inbox_.push({ kind: 'despawn', batch }));+ channel.on<ReplComponentRemoveBatch>(ReplMsg.componentRemove, (batch) => this.inbox_.push({ kind: 'remove', batch }));channel.on<ReplAckMsg>(ReplMsg.ack, (ack) => {if (ack.seq > this.ackedSeq_) this.ackedSeq_ = ack.seq;});channel.onBinary(REPLICATION_CHANNEL, (payload) => {// Copy out: the payload view may alias a transport-owned buffer.- this.pendingFrames_.push(payload.slice());+ this.inbox_.push({ kind: 'state', frame: payload.slice() });});const hello: ReplHelloRequest = {@@ -247,9 +258,7 @@ export class ReplicationClient {this.offDespawn_ = null;this.netIds_.clear();this.authority_.clear();- this.pendingFrames_.length = 0;- this.pendingSpawns_.length = 0;- this.pendingDespawns_.length = 0;+ this.inbox_.length = 0;this.pendingInputs_.length = 0;}@@ -277,19 +286,21 @@ export class ReplicationClient {return repl !== null && repl.owner === this.connectionId_ && 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).+ /** Apply everything received since the last fixed step, in the order it+ * arrived — which is the order the authority sent it. Within one server+ * tick that is already spawn → remove → despawn → state, so a frame never+ * precedes the spawn it references and nothing has to be re-sorted here.* With prediction enabled, ends by reconciling every owned entity:* live state ← authority copy ⊕ replay of unacknowledged inputs. */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()!);+ while (this.inbox_.length > 0) {+ const op = this.inbox_.shift()!;+ switch (op.kind) {+ case 'spawn': this.applySpawnBatch_(op.batch); break;+ case 'despawn': this.applyDespawnBatch_(op.batch); break;+ case 'remove': this.applyComponentRemoveBatch_(op.batch); break;+ case 'state': this.applyStateFrame_(decodeStateFrame(op.frame, this.table, this.refs_)); break;+ }}if (this.prediction_) {while (this.pendingInputs_.length > 0 && this.pendingInputs_[0].seq <= this.ackedSeq_) {@@ -404,32 +415,36 @@ export class ReplicationClient {return repl !== null && repl.owner === this.connectionId_;}+ /**+ * Three phases, because a payload may name an entity that appears LATER in+ * the same batch — or itself. Register every netId before reading any+ * component data and every reference resolves; hydrating as it goes writes+ * 0 for a forward reference and never revisits it.+ */private applySpawnBatch_(batch: ReplSpawnBatch): void {+ const fresh: { spawn: ReplSpawnEntity; entity: Entity }[] = [];for (const spawn of batch.entities) {- this.spawnGhost_(spawn);+ if (this.netIds_.entityOf(spawn.netId) !== undefined) continue; // duplicate delivery+ const e = this.world_.spawn(spawn.name || undefined);+ this.world_.insert(e, NetGhost, {});+ this.netIds_.register(spawn.netId, e);+ fresh.push({ spawn, entity: e });}- // 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);- }+ for (const { spawn, entity } of fresh) {+ for (const comp of spawn.components) {+ const data = this.remapEntityRefs_(comp.type, comp.data);+ loadComponent(this.world_, entity, { type: comp.type, data }, spawn.name);}}- }-- 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);+ // Baseline before hierarchy, as it has always been: reparenting runs+ // through the C++ registry and the prediction baseline must be the+ // state the authority sent, not whatever that leaves behind.+ for (const { spawn, entity } of fresh) this.seedAuthority_(spawn.netId, entity);+ for (const { spawn, entity } of fresh) {+ if (spawn.parentNetId === 0) continue;+ const parent = this.netIds_.entityOf(spawn.parentNetId);+ if (parent !== undefined) this.world_.setParent(entity, parent);}- this.world_.insert(e, NetGhost, {});- this.netIds_.register(spawn.netId, e);- this.seedAuthority_(spawn.netId, e);}/** Seed the authority copy for a freshly spawned OWNED entity from its@@ -459,6 +474,24 @@ export class ReplicationClient {return out;}+ /** A replicated component left an entity that lives on. The ghost keeps+ * existing; the component, its interpolation buffer and its authority+ * snapshot all go. */+ private applyComponentRemoveBatch_(batch: ReplComponentRemoveBatch): void {+ for (const entry of batch.entries) {+ const e = this.netIds_.entityOf(entry.netId);+ for (const componentId of entry.componentIds) {+ const te = this.table.entries[componentId];+ if (!te) continue;+ this.interp_?.dropComponent(entry.netId, componentId);+ this.authority_.get(entry.netId)?.delete(componentId);+ if (e !== undefined && this.world_.valid(e) && this.world_.has(e, te.def)) {+ this.world_.remove(e, te.def);+ }+ }+ }+ }+private applyDespawnBatch_(batch: ReplDespawnBatch): void {for (const netId of batch.netIds) {const e = this.netIds_.entityOf(netId);diff --git a/sdk/src/net/replication/codec.ts b/sdk/src/net/replication/codec.tsindex 3611a505c..f05291c21 100644--- a/sdk/src/net/replication/codec.ts+++ b/sdk/src/net/replication/codec.ts@@ -115,8 +115,27 @@ export function buildReplicationTable(): ReplicationTable {return { entries, byName: new Map(entries.map((e) => [e.name, e])) };}+/**+ * A field shape as one canonical string, so the handshake can compare byte+ * layouts and not just names. `entity` is its own signature rather than the+ * `f32` its default `0` would derive: the two are both four bytes and mean+ * completely different things on the wire.+ */+export function shapeSignature(shape: FieldShape): string {+ switch (shape.kind) {+ case 'object':+ return `{${shape.keys.map((k, i) => `${k}:${shapeSignature(shape.shapes[i])}`).join(',')}}`;+ default:+ return shape.kind;+ }+}+export function tableSchemas(table: ReplicationTable): ReplComponentSchema[] {- return table.entries.map((e) => ({ name: e.name, fields: [...e.fields] }));+ return table.entries.map((e) => ({+ name: e.name,+ fields: [...e.fields],+ shapes: e.shapes.map(shapeSignature),+ }));}/** Exact-schema comparison for the handshake: same components, same fields,@@ -132,6 +151,16 @@ export function diffSchemas(mine: ReplComponentSchema[], theirs: ReplComponentScif (mine[i].fields.join(',') !== theirs[i].fields.join(',')) {return `component "${mine[i].name}" field list differs ([${mine[i].fields}] vs [${theirs[i].fields}])`;}+ // The layout, not just the vocabulary. Matching names over different+ // shapes is the mismatch that reads as a working connection and then+ // decodes garbage from the second entry of every frame onward.+ for (let f = 0; f < mine[i].fields.length; f++) {+ const a = mine[i].shapes?.[f];+ const b = theirs[i].shapes?.[f];+ if (a !== b) {+ return `component "${mine[i].name}" field "${mine[i].fields[f]}" has wire shape ${a} here and ${b} there`;+ }+ }}return null;}diff --git a/sdk/src/net/replication/index.ts b/sdk/src/net/replication/index.tsindex f07782fac..973da1489 100644--- a/sdk/src/net/replication/index.ts+++ b/sdk/src/net/replication/index.ts@@ -10,12 +10,14 @@ export {type ReplSpawnEntity,type ReplSpawnBatch,type ReplDespawnBatch,+ type ReplComponentRemoveBatch,type ReplInputMsg,type ReplAckMsg,} from './protocol';export {buildReplicationTable,tableSchemas,+ shapeSignature,diffSchemas,encodeValue,decodeValue,diff --git a/sdk/src/net/replication/interpolation.ts b/sdk/src/net/replication/interpolation.tsindex 47c81af82..369193926 100644--- a/sdk/src/net/replication/interpolation.ts+++ b/sdk/src/net/replication/interpolation.ts@@ -154,6 +154,12 @@ export class InterpolationState {buf.push(fieldIndex, tick, value);}+ /** Forget one component's history on one entity — the component left, but+ * the entity did not. */+ dropComponent(netId: number, componentId: number): void {+ this.buffers.get(netId)?.delete(componentId);+ }+drop(netId: number): void {this.buffers.delete(netId);}diff --git a/sdk/src/net/replication/protocol.ts b/sdk/src/net/replication/protocol.tsindex 787dcbc9e..6e9933120 100644--- a/sdk/src/net/replication/protocol.ts+++ b/sdk/src/net/replication/protocol.ts@@ -11,7 +11,7 @@*/import type { SceneComponentData } from '../../scene/scene';-export const REPLICATION_PROTOCOL_VERSION = 2;+export const REPLICATION_PROTOCOL_VERSION = 3;/** NetChannel binary channel id the snapshot frames ride on. */export const REPLICATION_CHANNEL = 1;@@ -21,14 +21,21 @@ export const ReplMsg = {hello: 'repl:hello',spawn: 'repl:spawn',despawn: 'repl:despawn',+ componentRemove: 'repl:crm',input: 'repl:input',ack: 'repl:ack',} as const;-/** One component's replication schema, as exchanged for handshake comparison. */+/**+ * One component's replication schema, as exchanged for handshake comparison.+ * `shapes` is parallel to `fields`: each field's wire shape as a canonical+ * signature. Names alone do not pin the byte layout — `0` against `false`+ * agrees on the name and writes 4 bytes against 1.+ */export interface ReplComponentSchema {name: string;fields: string[];+ shapes: string[];}export interface ReplHelloRequest {@@ -79,6 +86,17 @@ export interface ReplDespawnBatch {netIds: number[];}+/**+ * Server → client: replicated components that LEFT an entity that lives on.+ * Field deltas cannot carry this — a removed component stops being sampled, so+ * without its own op the client keeps the last values it saw for good.+ * `componentIds` are wire table ids (codec.ts), the same ids frames carry.+ */+export interface ReplComponentRemoveBatch {+ tick: number;+ entries: { netId: number; componentIds: number[] }[];+}+/*** Client → server input command. `actions` is game-defined (typically one* InputMap's evaluated values per fixed tick: booleans, axes, {x,y} pairs);diff --git a/sdk/src/net/replication/server.ts b/sdk/src/net/replication/server.tsindex b1f7f1884..955ee1503 100644--- a/sdk/src/net/replication/server.ts+++ b/sdk/src/net/replication/server.ts@@ -27,6 +27,7 @@ import {REPLICATION_CHANNEL, REPLICATION_PROTOCOL_VERSION, ReplMsg,type ReplAckMsg, type ReplDespawnBatch, type ReplHelloRequest, type ReplHelloResponse,type ReplInputMsg, type ReplSpawnBatch, type ReplSpawnEntity,+ type ReplComponentRemoveBatch,} from './protocol';import {buildReplicationTable, cloneValue, diffSchemas, tableSchemas, FrameWriter,@@ -49,12 +50,21 @@ interface Connection {applied: ReplInputMsg | null;/** Highest input seq acknowledged to the client (0 = none yet). */ackedSeq: number;+ /** Highest input seq ACCEPTED from the client. Anything at or below it is a+ * repeat or a rewind and never reaches the queue. */+ lastSeq: number;+ /** Input commands refused (repeat, rewind, or a full queue). Non-zero means+ * this connection's prediction is replaying against a history the+ * authority did not run. */+ droppedInputs: number;/** Entities this connection currently knows (has been sent a spawn for). */interest: Set<Entity>;}-/** Queued-but-unconsumed input cap; beyond it the oldest commands drop (a- * client flooding faster than the tick rate loses history, not the server). */+/** Queued-but-unconsumed input cap. Beyond it the NEW command is refused, not+ * the oldest dropped: the queue is drained one per tick from the front, so+ * shifting the front skips a command the client already predicted. Refusing+ * the tail only denies credit to a client 128 ticks ahead of the authority. */const INPUT_QUEUE_CAP = 128;/** One dirty component on one entity this tick — diffed once, written into@@ -68,6 +78,31 @@ interface DirtyEntry {data: Record<string, unknown>;}+/** One replicated component that LEFT an entity that is still replicated.+ * Topology, not values — it rides the control plane beside spawn/despawn. */+interface RemovalEntry {+ entity: Entity;+ netId: number;+ componentId: number;+}++/** What one sample tick found: values that moved, and components that left. */+interface DirtySample {+ dirty: DirtyEntry[];+ removals: RemovalEntry[];+}++/** Group removals into the wire batch, one entry per entity. */+function removeBatch(tick: number, removals: readonly RemovalEntry[]): ReplComponentRemoveBatch {+ const byNetId = new Map<number, number[]>();+ for (const r of removals) {+ const ids = byNetId.get(r.netId);+ if (ids) ids.push(r.componentId);+ else byNetId.set(r.netId, [r.componentId]);+ }+ return { tick, entries: [...byNetId].map(([netId, componentIds]) => ({ netId, componentIds })) };+}+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;@@ -153,16 +188,26 @@ export class ReplicationServer {const conn: Connection = {id, channel, ready: false,input: null, queue: [], applied: null, ackedSeq: 0,+ lastSeq: 0, droppedInputs: 0,interest: new Set(),};this.connections_.set(id, conn);channel.on<ReplInputMsg>(ReplMsg.input, (msg) => {- if (!conn.input || msg.seq > conn.input.seq) conn.input = msg;- // The per-tick queue keeps every command in order for exactly-once- // consumption (tickInputOf) — the contract prediction replays against.+ // Exactly-once starts here: a repeat or a rewind must not enter the+ // queue tickInputOf drains. Running one command twice moves the+ // authority somewhere the client never predicted.+ if (typeof msg?.seq !== 'number' || msg.seq <= conn.lastSeq) {+ this.refuseInput_(conn);+ return;+ }+ conn.lastSeq = msg.seq;+ conn.input = msg;+ if (conn.queue.length >= INPUT_QUEUE_CAP) {+ this.refuseInput_(conn);+ return;+ }conn.queue.push(msg);- if (conn.queue.length > INPUT_QUEUE_CAP) conn.queue.shift();});channel.handle<ReplHelloRequest, ReplHelloResponse>(ReplMsg.hello, (req) => {@@ -185,6 +230,15 @@ export class ReplicationServer {return id;}+ /** Count a refused command, and say so the first time — a drop that only a+ * counter knows about reads exactly like a healthy connection. */+ private refuseInput_(conn: Connection): void {+ conn.droppedInputs++;+ if (conn.droppedInputs === 1) {+ log.warn('repl', `connection ${conn.id}: input refused (repeat, rewind, or queue full) — its prediction will reconcile`);+ }+ }+detachConnection(id: number): void {const conn = this.connections_.get(id);if (!conn) return;@@ -260,12 +314,12 @@ export class ReplicationServer {}// Diff once against the shadow; frames below share the result.- const dirty = this.collectDirty_();+ const sample = this.collectDirty_();if (!this.policy_) {- this.sampleBroadcast_(tick, spawnedEntities, despawned, dirty);+ this.sampleBroadcast_(tick, spawnedEntities, despawned, sample);} else {- this.sampleWithInterest_(tick, despawned, dirty);+ this.sampleWithInterest_(tick, despawned, sample);}// Acknowledge consumed inputs: this tick's state incorporates each@@ -284,7 +338,7 @@ export class ReplicationServer {tick: number,spawnedEntities: Entity[],despawned: { entity: Entity; netId: number }[],- dirty: DirtyEntry[],+ { dirty, removals }: DirtySample,): void {if (spawnedEntities.length > 0) {const entities = spawnedEntities.map((e) => this.spawnPayload_(e, this.knownNetIds_.get(e)!));@@ -315,6 +369,13 @@ export class ReplicationServer {}}+ // After the spawns (an entity that just entered carries a payload that+ // already lacks the component) and before the delta frame.+ if (removals.length > 0) {+ const batch = removeBatch(tick, removals);+ this.broadcast_((c) => c.channel.send<ReplComponentRemoveBatch>(ReplMsg.componentRemove, batch));+ }+if (dirty.length > 0) {const frame = new FrameWriter(tick);for (const d of dirty) frame.entry(d.netId, d.te, d.mask, d.data, this.refs_);@@ -329,7 +390,7 @@ export class ReplicationServer {private sampleWithInterest_(tick: number,despawned: { entity: Entity; netId: number }[],- dirty: DirtyEntry[],+ { dirty, removals }: DirtySample,): void {const despawnedNetIds = new Map(despawned.map((d) => [d.entity, d.netId]));const candidates = [...this.known_];@@ -368,10 +429,16 @@ export class ReplicationServer {if (leaveIds.length > 0) {c.channel.send<ReplDespawnBatch>(ReplMsg.despawn, { tick, netIds: leaveIds });}+ const entered = new Set(enters);+ // Same rule as the delta below: an entity that just entered was+ // serialized without the component, so it owes no removal.+ const mine = removals.filter((r) => visible.has(r.entity) && !entered.has(r.entity));+ if (mine.length > 0) {+ c.channel.send<ReplComponentRemoveBatch>(ReplMsg.componentRemove, removeBatch(tick, mine));+ }// Entities that just entered skip the delta — their spawn// payload already carries this tick's state.let frame: FrameWriter | null = null;- const entered = new Set(enters);for (const d of dirty) {if (!visible.has(d.entity) || entered.has(d.entity)) continue;frame ??= new FrameWriter(tick);@@ -451,15 +518,22 @@ export class ReplicationServer {/** Diff every known entity against its shadow (updating the shadow), and* return this tick's dirty component entries. */- private collectDirty_(): DirtyEntry[] {+ private collectDirty_(): DirtySample {const out: DirtyEntry[] = [];+ const removals: RemovalEntry[] = [];for (const e of this.known_) {const perComp = this.shadow_.get(e);if (!perComp) continue;const netId = this.knownNetIds_.get(e);if (netId === undefined) continue;for (const te of this.table.entries) {- if (!this.world_.has(e, te.def)) continue;+ if (!this.world_.has(e, te.def)) {+ // The shadow is the record of what the clients were told+ // exists. Its snapshot disappearing IS the removal — there+ // is no other trace, since a gone component is never sampled.+ if (perComp.delete(te.id)) removals.push({ entity: e, netId, componentId: te.id });+ continue;+ }const data = this.world_.tryGet(e, te.def) as Record<string, unknown>;let snap = perComp.get(te.id);if (!snap) {@@ -480,7 +554,7 @@ export class ReplicationServer {}}}- return out;+ return { dirty: out, removals };}private sendInitialState_(conn: Connection): void {diff --git a/sdk/tests/replication.test.ts b/sdk/tests/replication.test.tsindex ed5caf2cf..c5fa3286e 100644--- a/sdk/tests/replication.test.ts+++ b/sdk/tests/replication.test.ts@@ -17,7 +17,7 @@ import { NetChannel } from '../src/net/NetChannel';import {replicationPlugin, Net, Replicated, NetGhost,ReplMsg, REPLICATION_PROTOCOL_VERSION,- buildReplicationTable, tableSchemas, diffSchemas,+ buildReplicationTable, tableSchemas, diffSchemas, ReplicationServer,ByteWriter, ByteReader, encodeValue, decodeValue, FrameWriter, decodeStateFrame,type ReplHelloResponse, type FieldShape,} from '../src/net/replication';@@ -43,6 +43,7 @@ async function makePair() {let NetPos: ReturnType<typeof defineComponent<{ x: number; y: number; secret: number }>>;let NetTag: ReturnType<typeof defineComponent<{ label: string; active: boolean }>>;+let NetLink: ReturnType<typeof defineComponent<{ target: number }>>;beforeEach(() => {clearUserComponents();@@ -52,6 +53,11 @@ beforeEach(() => {NetTag = defineComponent('NetTag', { label: '', active: false }, {replicatedFields: ['label', 'active'],});+ // An entity reference: `0` on the wire is a netId, not a coordinate.+ NetLink = defineComponent('NetLink', { target: 0 }, {+ replicatedFields: ['target'],+ entityFields: ['target'],+ });});describe('replication handshake', () => {@@ -119,6 +125,47 @@ describe('replication handshake', () => {if (!res.ok) expect(res.error).toMatch(/ABI/);});+ it('refuses a field whose wire SHAPE differs, with the names identical', async () => {+ // The mismatch names alone cannot see. Both ends call the component+ // NetPos and the field x; one writes 4 bytes and the other 1, so every+ // entry after it in the frame decodes from the wrong offset.+ 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());+ const i = schemas.findIndex((c) => c.name === 'NetPos');+ schemas[i] = { ...schemas[i], shapes: schemas[i].shapes.map((sh, f) => (f === 0 ? 'bool' : sh)) };+ 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(/wire shape/);+ });++ it('refuses an entity-ref field the other end thinks is a plain number', async () => {+ // Same width, so nothing desynchronizes — one end just reads a netId as+ // a coordinate forever. `entity` is its own signature for this reason.+ 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());+ const i = schemas.findIndex((c) => c.name === 'NetPos');+ schemas[i] = { ...schemas[i], shapes: schemas[i].shapes.map((sh, f) => (f === 0 ? 'entity' : sh)) };+ 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(/wire shape/);+ });+it('refuses a replication schema mismatch', async () => {const serverApp = makeApp();const server = serverApp.getResource(Net).startServer();@@ -335,3 +382,202 @@ describe('codec round trip', () => {expect(diffSchemas(a, [{ name: 'A', fields: ['x', 'y'] }])).toMatch(/field list/);});});++describe('component topology', () => {+ it('a replicated component leaving the authority leaves the ghost too', async () => {+ // The delta plane cannot say this: a removed component stops being+ // sampled, so without its own op the ghost keeps the last values it saw+ // for the rest of the session.+ const { serverApp, clientApp, client } = await makePair();+ const e = serverApp.world.spawn('unit');+ serverApp.world.insert(e, NetPos, { x: 5, y: 6, secret: 0 });+ serverApp.world.insert(e, NetTag, { label: 'shielded', active: true });+ serverApp.world.insert(e, Replicated, {});+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);++ const ghost = clientApp.world.getEntitiesWithComponents([NetGhost])[0];+ expect(clientApp.world.has(ghost, NetTag)).toBe(true);++ serverApp.world.remove(e, NetTag);+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);++ expect(clientApp.world.has(ghost, NetTag)).toBe(false);+ // The entity and its other components are untouched — this is a+ // component leaving, not a despawn.+ expect(clientApp.world.valid(ghost)).toBe(true);+ expect((clientApp.world.tryGet(ghost, NetPos) as { x: number }).x).toBe(5);+ expect(client.connected).toBe(true);+ });++ it('re-adding the component after a removal replicates it again', async () => {+ const { serverApp, clientApp } = await makePair();+ const e = serverApp.world.spawn('unit');+ serverApp.world.insert(e, NetPos, { x: 0, y: 0, secret: 0 });+ serverApp.world.insert(e, NetTag, { label: 'first', active: true });+ serverApp.world.insert(e, Replicated, {});+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ const ghost = clientApp.world.getEntitiesWithComponents([NetGhost])[0];++ serverApp.world.remove(e, NetTag);+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ expect(clientApp.world.has(ghost, NetTag)).toBe(false);++ // The shadow snapshot goes with the removal, so a re-add replicates+ // every field rather than diffing against a component that is gone.+ serverApp.world.insert(e, NetTag, { label: 'second', active: false });+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ expect(clientApp.world.has(ghost, NetTag)).toBe(true);+ expect((clientApp.world.tryGet(ghost, NetTag) as { label: string }).label).toBe('second');+ });+});++describe('inbound timeline', () => {+ it('a despawn and a re-spawn arriving together apply in the order they were sent', async () => {+ // The AOI edge: leave interest at tick N, come back at N+1. Sorting the+ // inbox by KIND replays that as re-enter-then-leave — and permanently,+ // since the server sends only deltas for it from then on.+ 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, { interpolationDelayTicks: 0 });+ expect(client.connected).toBe(true);++ const e = serverApp.world.spawn('blinker');+ serverApp.world.insert(e, NetPos, { x: 1, y: 2, secret: 0 });+ serverApp.world.insert(e, Replicated, {});+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);+ expect(clientApp.world.getEntitiesWithComponents([NetGhost])).toHaveLength(1);++ // Leave, then re-enter, with the client not stepping in between — both+ // batches land in one flush.+ let visible = false;+ server.setInterestPolicy(({ candidates }) => (visible ? new Set(candidates) : new Set<never>()));+ await serverApp.tick(STEP); // leaves → despawn+ visible = true;+ await serverApp.tick(STEP); // re-enters → spawn+ await clientApp.tick(STEP);++ const ghosts = clientApp.world.getEntitiesWithComponents([NetGhost]);+ expect(ghosts).toHaveLength(1);+ expect((clientApp.world.tryGet(ghosts[0], NetPos) as { x: number }).x).toBe(1);+ });+});++describe('spawn batch references', () => {+ it('an entity reference to something later in the same batch resolves', async () => {+ // Hydrating entity-by-entity looked up a netId that had not been+ // registered yet and wrote 0 — a reference to nothing, never revisited.+ const { serverApp, clientApp, client } = await makePair();+ // Replicated on the holder FIRST, so it is the earlier of the two in+ // the batch and its reference genuinely points forward.+ const holder = serverApp.world.spawn('holder');+ serverApp.world.insert(holder, Replicated, {});+ const target = serverApp.world.spawn('target');+ serverApp.world.insert(target, NetPos, { x: 9, y: 9, secret: 0 });+ serverApp.world.insert(target, Replicated, {});+ serverApp.world.insert(holder, NetLink, { target });+ // Both are new this tick, so they ride ONE spawn batch.+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);++ const ghosts = clientApp.world.getEntitiesWithComponents([NetGhost]);+ expect(ghosts).toHaveLength(2);+ const ghostHolder = ghosts.find((g) => clientApp.world.has(g, NetLink))!;+ const ghostTarget = ghosts.find((g) => clientApp.world.has(g, NetPos))!;+ // netIds are allocated in batch order, so this pins the precondition:+ // without it the test would still pass on a BACKWARD reference and+ // quietly stop covering the bug it exists for.+ expect(client.netIds.netIdOf(ghostHolder)!).toBeLessThan(client.netIds.netIdOf(ghostTarget)!);+ const link = clientApp.world.tryGet(ghostHolder, NetLink) as { target: number };+ expect(link.target).not.toBe(0);+ expect(link.target).toBe(ghostTarget);+ });++ it('an entity that references itself resolves to itself', async () => {+ // Self-reference failed for the same reason: the netId was registered+ // only after its own components had been read.+ const { serverApp, clientApp } = await makePair();+ const e = serverApp.world.spawn('ouroboros');+ serverApp.world.insert(e, NetLink, { target: e });+ serverApp.world.insert(e, Replicated, {});+ await serverApp.tick(STEP);+ await clientApp.tick(STEP);++ const ghost = clientApp.world.getEntitiesWithComponents([NetGhost])[0];+ expect((clientApp.world.tryGet(ghost, NetLink) as { target: number }).target).toBe(ghost);+ });+});++describe('input sequence', () => {+ /** A raw client channel, so the test can send any seq it likes. */+ async function rawInputPair() {+ const serverApp = makeApp();+ const server = serverApp.getResource(Net).startServer();+ const [ta, tb] = MemoryTransport.pair();+ const id = server.attachConnection(ta);+ const raw = new NetChannel(tb);+ const res = await raw.request<ReplHelloResponse>(ReplMsg.hello, {+ protocolVersion: REPLICATION_PROTOCOL_VERSION,+ abiHash: ABI_LAYOUT_HASH,+ components: tableSchemas(buildReplicationTable()),+ });+ expect(res.ok).toBe(true);+ return { serverApp, server, raw, id };+ }++ /** The seq the authority runs on each of `n` consecutive ticks. */+ function ticked(server: ReplicationServer, id: number, n: number): (number | null)[] {+ const out: (number | null)[] = [];+ for (let i = 0; i < n; i++) {+ server.beginTick(STEP);+ out.push(server.tickInputOf(id)?.seq ?? null);+ }+ return out;+ }++ it('a repeated seq does not delay the command behind it', async () => {+ // Queued as [1,1,2] the authority runs 1, 1, 2 — seq 2 lands a tick+ // late, and the client that predicted [1,2] over two ticks is now+ // somewhere the server is not. Deduped it is [1,2].+ const { server, raw, id } = await rawInputPair();+ raw.send(ReplMsg.input, { seq: 1, actions: { n: 1 } });+ raw.send(ReplMsg.input, { seq: 1, actions: { n: 1 } });+ raw.send(ReplMsg.input, { seq: 2, actions: { n: 2 } });++ expect(ticked(server, id, 2)).toEqual([1, 2]);+ });++ it('never runs a seq that goes backwards', async () => {+ // A rewind queued like any other command walks the authority back to an+ // older input a tick after it passed it.+ const { server, raw, id } = await rawInputPair();+ raw.send(ReplMsg.input, { seq: 7, actions: { a: 1 } });+ raw.send(ReplMsg.input, { seq: 3, actions: { a: 2 } });++ // Second tick starves and repeats 7 (documented) rather than running 3.+ expect(ticked(server, id, 2)).toEqual([7, 7]);+ expect(server.inputOf(id)?.seq).toBe(7);+ });++ it('a flooding client loses its NEWEST commands, never the queued ones', async () => {+ // Shifting the front would skip a command the client already predicted+ // and never revisit it. The front is the contract; the tail is credit.+ const { server, raw, id } = await rawInputPair();+ for (let seq = 1; seq <= 200; seq++) {+ raw.send(ReplMsg.input, { seq, actions: { n: seq } });+ }+ const run = ticked(server, id, 129);+ expect(run.slice(0, 128)).toEqual(Array.from({ length: 128 }, (_, i) => i + 1));+ // Starved after the cap — it repeats the last command it actually ran,+ // rather than jumping to a seq the client sent long after.+ expect(run[128]).toBe(128);+ });+});