A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @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 '../../ecs/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' };
}
}
/**
* Deep-clone a replicated field value (plain JSON-shaped data). Shared by the
* server's shadow snapshots and the client's prediction authority copies —
* both must never alias live component objects.
*/
export function cloneValue<T>(v: T): T {
if (v === null || typeof v !== 'object') return v;
if (Array.isArray(v)) return v.map(cloneValue) as T;
const out: Record<string, unknown> = {};
for (const k in v) out[k] = cloneValue((v as Record<string, unknown>)[k]);
return out as T;
}
// =============================================================================
// 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])) };
}
/**
* 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],
shapes: e.shapes.map(shapeSignature),
}));
}
/** 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}])`;
}
// 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;
}
// =============================================================================
// Byte streams
// =============================================================================
// Lazy: WeChat installs its TextEncoder/TextDecoder polyfill during platform
// init, after this module is evaluated — a module-level `new` would
// ReferenceError on a real device (the devtools has them natively).
let textEncoder_: TextEncoder | undefined;
let textDecoder_: TextDecoder | undefined;
const textEncoder = (): TextEncoder => textEncoder_ ?? (textEncoder_ = new TextEncoder());
const textDecoder = (): TextDecoder => textDecoder_ ?? (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 };
}