Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

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.mdx
index 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, interpolated
state (`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 to
its entities; `client.ownsEntity(e)` answers "is this ghost mine".
- **Editor preview**: pick **2–4 Players** in the Play-mode dropdown — a listen
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx
index 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.md
index 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 @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 @experimental
diff --git a/sdk/src/net/replication/client.ts b/sdk/src/net/replication/client.ts
index 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.ts
index 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: ReplComponentSc
if (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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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);
+ });
+});