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.

28.9 KB
Raw Blame
// 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.
 *
 *          With {@link PredictionOptions} enabled, the entities this connection
 *          owns are simulated locally: `sendInput` applies the command to them
 *          immediately (zero perceived latency) and keeps it in a pending
 *          buffer; authoritative state for owned entities lands in a shadow
 *          "authority copy" instead of the live components; each fixed tick the
 *          live state is rebuilt as authority ⊕ replay of the unacknowledged
 *          commands (one server tick each — the server consumes the input
 *          queue at the same cadence, see `tickInputOf`). Mispredictions can
 *          therefore never accumulate: every field snaps back to the last
 *          authoritative value before the replay. Owned entities bypass
 *          snapshot interpolation entirely.
 */
import type { World } from '../../ecs/world';
import { replay, type ReplayReport, type SpeculationScope } from '../../ecs/speculation';
import type { Entity } from '../../types';
import { getComponent } from '../../ecs/component';
import { ABI_LAYOUT_HASH } from '../../ecs/component.generated';
import { loadComponent } from '../../scene/scene';
import { NetChannel, type ReliableOrderedTransport } from '../NetChannel';
import { log } from '../../util/logger';
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,
    type EntityRefMap, type FieldShape, type ReplicationTable, type ReplicationTableEntry, type StateFrame,
} from './codec';
import { NetGhost, Replicated, type ReplicatedData } from './components';
import { getReplicationArchetype } from './archetype';
import { NetIds } from './NetIds';
import { InterpolationState } from './interpolation';

/**
 * Client-side prediction for owned entities. `apply` is the same input-to-
 * state logic the server's gameplay runs (register one function, use it on
 * both ends — the single source of the movement rules); with it enabled,
 * `sendInput` also applies the command locally and unacknowledged commands
 * replay on top of every authoritative update.
 */
export interface PredictionOptions {
    /** Advance one owned entity by one fixed tick of `actions`. Must depend
     *  only on world state + actions + dt (it re-runs during reconciliation). */
    apply: (world: World, entity: Entity, actions: Record<string, unknown>, dt: number) => void;
    /** Cap on unacknowledged commands kept for replay (default 120). */
    maxPendingInputs?: number;
    /**
     * Ease reconciliation corrections out instead of hard-snapping: the
     * numeric fields of owned entities keep a decaying visual error toward
     * their pre-correction value. Purely presentational — the simulation
     * rebuilds from the authority copy every tick regardless, so the error can
     * never accumulate. Off by default (corrections snap).
     */
    smoothing?: PredictionSmoothing;
}

/**
 * Ask whether an `apply` is what reconciliation needs it to be.
 *
 * The promise above is the one the rebuild rests on, and until now only a
 * desync could report it broken. Runs the step twice from the same state and
 * takes both back, so a game can ask in a test without paying for it in play.
 *
 * @experimental
 */
export function predictionReplays(
    scope: SpeculationScope,
    prediction: PredictionOptions,
    entity: Entity,
    actions: Record<string, unknown>,
    dt: number,
): ReplayReport {
    return replay(scope, () => {
        prediction.apply(scope.world, entity, actions, dt);
        return 'commit';
    });
}

export interface PredictionSmoothing {
    /** Seconds for the visual error to halve (typical: 0.05–0.15). */
    halfLife: number;
    /**
     * Corrections larger than this (per numeric component) snap immediately —
     * a teleport must look like a teleport. Default: no limit.
     */
    maxError?: number;
}

/** next + decayed (prev − next) over the numeric parts of a replicated field —
 *  shape-driven (the codec's FieldShape is the single source of what's numeric). */
function smoothValue(shape: FieldShape, prev: unknown, next: unknown, keep: number, maxError: number): unknown {
    if (shape.kind === 'f32') {
        if (typeof prev !== 'number' || typeof next !== 'number') return next;
        const err = prev - next;
        if (Math.abs(err) > maxError) return next;
        return next + err * keep;
    }
    if (shape.kind === 'object') {
        if (prev === null || next === null || typeof prev !== 'object' || typeof next !== 'object') return next;
        const out: Record<string, unknown> = { ...(next as Record<string, unknown>) };
        for (let i = 0; i < shape.keys.length; i++) {
            const k = shape.keys[i];
            out[k] = smoothValue(
                shape.shapes[i],
                (prev as Record<string, unknown>)[k],
                (next as Record<string, unknown>)[k],
                keep, maxError,
            );
        }
        return out;
    }
    return next;
}

export interface ReplicationClientOptions {
    /**
     * How many server ticks the presented state trails the newest received
     * data. Two ticks absorbs one lost/late delivery without a visible hitch;
     * 0 disables buffering (state applies the moment it drains).
     */
    interpolationDelayTicks?: number;
    /** Enable client-side prediction for the entities this connection owns. */
    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();
    private offDespawn_: (() => void) | null = null;
    private channel_: NetChannel | null = null;
    private table_: ReplicationTable | null = null;
    private connectionId_ = 0;
    private serverTick_ = 0;
    /** 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;
    /** Sent-but-unacknowledged input commands, oldest first (replay order). */
    private readonly pendingInputs_: ReplInputMsg[] = [];
    private ackedSeq_ = 0;
    /** Last authoritative value of every replicated field of every OWNED
     *  entity: netId → componentId → field record. Deltas land here (never in
     *  the live components); reconciliation rebuilds live = this ⊕ replay. */
    private readonly authority_ = new Map<number, Map<number, Record<string, unknown>>>();
    private fixedDelta_ = 1 / 60;

    constructor(world: World, options: ReplicationClientOptions = {}) {
        this.world_ = world;
        const delay = options.interpolationDelayTicks ?? 2;
        this.interp_ = delay > 0 ? new InterpolationState(delay) : null;
        this.prediction_ = options.prediction ?? null;
        this.offDespawn_ = 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: ReliableOrderedTransport): 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.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.inbox_.push({ kind: 'state', frame: 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;
        if (res.fixedDelta > 0) this.fixedDelta_ = res.fixedDelta;
    }

    /** @internal Keep the replay dt in lockstep with the app (plugin-fed). */
    setFixedDelta(dt: number): void {
        if (dt > 0) this.fixedDelta_ = dt;
    }

    get predictionEnabled(): boolean {
        return this.prediction_ !== null;
    }

    /**
     * Enable (or reconfigure) prediction after construction — the path for
     * game code whose connection a HOST made (the editor's multiplayer
     * preview connects the client realm itself, options-free): call from a
     * fixed-tick system once the session is a client. Owned entities that
     * already spawned get their authority copies seeded from current state.
     */
    enablePrediction(options: PredictionOptions): void {
        this.prediction_ = options;
        for (const e of this.ownedEntities_()) {
            const netId = this.netIds_.netIdOf(e);
            if (netId !== undefined && !this.authority_.has(netId)) {
                this.seedAuthority_(netId, e);
            }
        }
    }

    disconnect(): void {
        this.channel_?.dispose();
        this.channel_ = null;
        this.connectionId_ = 0;
        // Retire the despawn subscription and all accumulated state — otherwise
        // every Play→Stop / reconnect cycle leaks a closure that keeps this dead
        // client alive (and mutating it on future despawns), plus stale queues.
        this.offDespawn_?.();
        this.offDespawn_ = null;
        this.netIds_.clear();
        this.authority_.clear();
        this.inbox_.length = 0;
        this.pendingInputs_.length = 0;
    }

    /** Send an input command (typically the InputMap's evaluated action values,
     *  once per fixed tick — with prediction enabled that cadence is the
     *  contract, since the server consumes one command per tick). The seq
     *  stamp makes stale deliveries harmless. With prediction the command also
     *  applies to the owned entities immediately. */
    sendInput(actions: Record<string, unknown>): void {
        if (!this.channel_) return;
        const msg: ReplInputMsg = { seq: ++this.inputSeq_, actions };
        this.channel_.send<ReplInputMsg>(ReplMsg.input, msg);
        if (!this.prediction_) return;
        this.pendingInputs_.push(msg);
        const cap = this.prediction_.maxPendingInputs ?? 120;
        if (this.pendingInputs_.length > cap) this.pendingInputs_.shift();
        for (const e of this.ownedEntities_()) {
            this.prediction_.apply(this.world_, e, actions, this.fixedDelta_);
        }
    }

    /** True when this client's connection owns the entity (Replicated.owner). */
    ownsEntity(entity: Entity): boolean {
        const repl = this.world_.tryGet(entity, Replicated) as { owner: number } | null;
        return repl !== null && repl.owner === this.connectionId_ && this.connectionId_ !== 0;
    }

    /** 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.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_) {
                this.pendingInputs_.shift();
            }
            this.reconcilePredicted_();
        }
    }

    /** Rebuild every owned entity's live state as authority ⊕ pending replay
     *  (⊕ a decaying visual error when smoothing is on). Idempotent modulo the
     *  error decay — it runs unconditionally each fixed step. */
    private reconcilePredicted_(): void {
        const owned = this.ownedEntities_();
        if (owned.length === 0) return;

        // Smoothing: what the player SAW before this rebuild. The snap below
        // replaces field references (never mutates them), so these stay valid.
        const smoothing = this.prediction_!.smoothing;
        const seen = smoothing ? new Map<Entity, Map<number, Record<string, unknown>>>() : null;
        if (seen) {
            for (const e of owned) {
                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 prev: Record<string, unknown> = {};
                    for (const f of te.fields) prev[f] = data[f];
                    perComp.set(te.id, prev);
                }
                seen.set(e, perComp);
            }
        }

        for (const e of owned) {
            const netId = this.netIds_.netIdOf(e);
            if (netId === undefined) continue;
            const perComp = this.authority_.get(netId);
            if (!perComp) continue;
            for (const [componentId, snap] of perComp) {
                const te = this.table.entries[componentId];
                if (!te) continue;
                const existing = this.world_.tryGet(e, te.def) as Record<string, unknown> | null;
                const target = existing ?? {};
                for (const f of te.fields) {
                    // Clone: replay mutates live objects in place; the
                    // authority copy must never alias them.
                    if (f in snap) target[f] = cloneValue(snap[f]);
                }
                if (existing) {
                    this.world_.set(e, te.def, target);
                } else {
                    this.world_.insert(e, te.def, target);
                }
            }
        }
        // Replay tick-by-tick across all owned entities — the same order the
        // server applies the queue to the connection's entities.
        for (const input of this.pendingInputs_) {
            for (const e of owned) {
                this.prediction_!.apply(this.world_, e, input.actions, this.fixedDelta_);
            }
        }

        // Smoothing: blend the rebuilt state toward what was on screen, with
        // the error halving every halfLife seconds. Next tick's rebuild wipes
        // it, so the error decays instead of compounding.
        if (smoothing && seen) {
            const keep = Math.pow(0.5, this.fixedDelta_ / smoothing.halfLife);
            const maxError = smoothing.maxError ?? Infinity;
            for (const e of owned) {
                // Annotated: some tsc releases flag this chain as circular
                // inference (TS7022) without them.
                const perComp: Map<number, Record<string, unknown>> | undefined = seen.get(e);
                if (!perComp) continue;
                for (const [componentId, prev] of perComp) {
                    const te: ReplicationTableEntry | undefined = this.table.entries[componentId];
                    if (!te || !this.world_.has(e, te.def)) continue;
                    const data = this.world_.tryGet(e, te.def) as Record<string, unknown>;
                    let changed = false;
                    for (let i = 0; i < te.fields.length; i++) {
                        const f = te.fields[i];
                        if (!(f in prev)) continue;
                        const blended = smoothValue(te.shapes[i], prev[f], data[f], keep, maxError);
                        if (blended !== data[f]) {
                            data[f] = blended;
                            changed = true;
                        }
                    }
                    if (changed) this.world_.set(e, te.def, data);
                }
            }
        }
    }

    private ownedEntities_(): Entity[] {
        const out: Entity[] = [];
        if (this.connectionId_ === 0) return out;
        for (const e of this.world_.getEntitiesWithComponents([Replicated])) {
            const repl = this.world_.tryGet(e, Replicated) as ReplicatedData | null;
            if (repl && repl.owner === this.connectionId_) out.push(e);
        }
        return out;
    }

    /** Whether this netId's state is under local prediction (owned + enabled). */
    private isPredicted_(netId: number): boolean {
        if (!this.prediction_) return false;
        const e = this.netIds_.entityOf(netId);
        if (e === undefined || !this.world_.valid(e)) return false;
        const repl = this.world_.tryGet(e, Replicated) as ReplicatedData | null;
        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) {
            if (this.netIds_.entityOf(spawn.netId) !== undefined) continue; // duplicate delivery
            // Refused BEFORE anything exists: a ghost the client cannot build is
            // not a ghost it should half-build, and a registered netId pointing
            // at a stripped entity would take deltas for the rest of the session.
            if (spawn.archetype !== '' && !getReplicationArchetype(spawn.archetype)) {
                log.error('repl', `no replication archetype registered for "${spawn.archetype}"`
                    + ` — refusing to construct netId ${spawn.netId}`);
                continue;
            }
            const e = this.world_.spawn(spawn.name || undefined);
            this.world_.insert(e, NetGhost, {});
            // Protocol identity, from the spawn rather than from a component the
            // authority happened to be holding.
            this.world_.insert(e, Replicated, {
                netId: spawn.netId, owner: spawn.owner, archetype: spawn.archetype,
            });
            this.netIds_.register(spawn.netId, e);
            fresh.push({ spawn, entity: e });
        }
        // Construction first, then the baseline on top: what the authority
        // declares outranks what the archetype defaults to, so an entity that
        // left interest and came back arrives at the current state.
        for (const { spawn, entity } of fresh) {
            if (spawn.archetype === '') continue;
            getReplicationArchetype(spawn.archetype)!(this.world_, entity);
        }
        for (const { spawn, entity } of fresh) {
            for (const comp of spawn.baseline) {
                const data = this.remapEntityRefs_(comp.type, comp.data);
                loadComponent(this.world_, entity, { 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);
        }
    }

    /** Seed the authority copy for a freshly spawned OWNED entity from its
     *  just-loaded state (the spawn payload IS the authoritative baseline). */
    private seedAuthority_(netId: number, e: Entity): void {
        if (!this.isPredicted_(netId)) return;
        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] = cloneValue(data[f]);
            perComp.set(te.id, snap);
        }
        this.authority_.set(netId, perComp);
    }

    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;
    }

    /** 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);
            this.netIds_.unregister(netId);
            this.interp_?.drop(netId);
            this.authority_.delete(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) {
            // Predicted (owned) entities: authoritative values land in the
            // authority copy — never the live components, never interpolation.
            // Reconciliation rebuilds the live state at the end of the flush.
            if (this.isPredicted_(entry.netId)) {
                this.updateAuthority_(entry.netId, entry.componentId, entry.fieldMask, entry.values);
                continue;
            }
            if (this.interp_) {
                let v = 0;
                const te = this.table.entries[entry.componentId];
                if (!te) continue;
                for (let i = 0; i < te.fields.length; i++) {
                    if (entry.fieldMask & (1 << i)) {
                        this.interp_.push(entry.netId, entry.componentId, i, frame.tick, entry.values[v++]);
                    }
                }
            } else {
                this.applyEntryNow_(entry.netId, entry.componentId, entry.fieldMask, entry.values);
            }
        }
    }

    private updateAuthority_(netId: number, componentId: number, fieldMask: number, values: unknown[]): void {
        const te = this.table.entries[componentId];
        if (!te) return;
        let perComp = this.authority_.get(netId);
        if (!perComp) {
            perComp = new Map();
            this.authority_.set(netId, perComp);
        }
        let snap = perComp.get(componentId);
        if (!snap) {
            snap = {};
            perComp.set(componentId, snap);
        }
        let v = 0;
        for (let i = 0; i < te.fields.length; i++) {
            if (fieldMask & (1 << i)) {
                snap[te.fields[i]] = values[v++];
            }
        }
    }

    private applyEntryNow_(netId: number, componentId: number, fieldMask: number, values: unknown[]): void {
        const e = this.netIds_.entityOf(netId);
        if (e === undefined || !this.world_.valid(e)) return;
        const te = this.table.entries[componentId];
        if (!te) return;
        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 (fieldMask & (1 << i)) {
                target[te.fields[i]] = values[v++];
            }
        }
        if (existing) {
            this.world_.set(e, te.def, target);
        } else {
            this.world_.insert(e, te.def, target);
        }
    }

    /** Present the buffered state at the trailing render clock. Runs each
     *  render frame (PostUpdate); `deltaTicks` = render delta in tick units. */
    sampleInterpolation(deltaTicks: number): void {
        if (!this.interp_ || this.interp_.newestTick === 0) return;
        const t = this.interp_.advance(deltaTicks);
        for (const [netId, perComp] of this.interp_.buffers) {
            const e = this.netIds_.entityOf(netId);
            if (e === undefined || !this.world_.valid(e)) continue;
            for (const [componentId, buf] of perComp) {
                const te = this.table.entries[componentId];
                if (!te) continue;
                const existing = this.world_.tryGet(e, te.def) as Record<string, unknown> | null;
                const target = existing ?? {};
                let changed = false;
                for (const [fieldIndex, series] of buf.byField) {
                    const value = series.sample(te.shapes[fieldIndex], t);
                    if (value !== undefined) {
                        target[te.fields[fieldIndex]] = value;
                        changed = true;
                    }
                }
                if (!changed) continue;
                if (existing) {
                    this.world_.set(e, te.def, target);
                } else {
                    this.world_.insert(e, te.def, target);
                }
            }
        }
    }
}