@netforge/engine/net API reference

import { InputQueue, encodeSnapshot } from "@netforge/engine/net";

function bitsForSigned(maxAbs: number): number;

function connectReservation<W, I>(sim: SimAdapter<W, I>, endpoint: string, reservation: Parameters<Client["consumeSeatReservation"]>[0]): Promise<RoomConnection<W, I>>;

function decodeInputPacket<I>(codec: InputCodec<I>, bytes: Uint8Array): InputPacket<I>;

function decodeSnapshot(schema: EntitySchema, bytes: Uint8Array, baselineFor: (tick: number) => ReadonlyMap<number, QEntity> | undefined): DecodedSnapshot;

function dequantize(f: FieldSpec, q: number): number;

function dequantizeValues(schema: EntitySchema, q: readonly number[]): number[];

function encodeInputPacket<I>(codec: InputCodec<I>, p: InputPacket<I>): Uint8Array;

function encodeSnapshot(schema: EntitySchema, header: SnapshotHeader, current: readonly QEntity[], baseline: ReadonlyMap<number, QEntity> | null): Uint8Array;

function fieldBits(f: FieldSpec): number;

function fieldDeltaBits(f: FieldSpec): number;

function guestId(): string;

function interpolateField(f: FieldSpec, a: number, b: number, t: number): number;

function joinRoom<W, I>(sim: SimAdapter<W, I>, p: JoinParams): Promise<RoomConnection<W, I>>;

function kindFieldIndices(schema: EntitySchema, kind: number): readonly number[];

function pageGame(): string | null;

function quantize(f: FieldSpec, v: number): number;

function quantizeEntity(schema: EntitySchema, e: EntityState, only?: readonly number[]): number[];

function rotateGuestId(): string;

function savedSession(endpoint: string): { token: string; address: string; } | null;

function saveSession(endpoint: string, s: { token: string; address: string; expiresAt: number; } | null): void;

function signInWithWallet(endpoint: string, provider: Eip1193, statement?: string): Promise<{ token: string; address: string; expiresAt: number; }>;

function unzigzag(z: number): number;

function zigzag(n: number): number;

class BaselineMissingError {
  constructor(baselineTick: number);
}

class BitReader {
  constructor(buf: Uint8Array);
  readBits(bits: number): number;
  readBool(): boolean;
  readSigned(bits: number): number;
  readVarUint(): number;
  get remainingBits(): number;
}

class BitWriter {
  constructor(initialBytes?: number);
  writeBits(value: number, bits: number): void;
  writeBool(b: boolean): void;
  writeSigned(value: number, bits: number): void;
  writeVarUint(value: number): void;
  get bitLength(): number;
  finish(): Uint8Array;
}

class InputQueue {
  constructor<I>(opts?: InputQueueOptions);
  lastAppliedSeq: number;
  dropped: number;
  starved: number;
  receive(commands: readonly InputCommand<I>[]): void;
  consume(): InputCommand<I>[];
  get pending(): number;
}

class InterpolationBuffer {
  constructor(schema: EntitySchema, capacity?: number);
  push(tick: number, entities: ReadonlyMap<number, QEntity>): void;
  sample(renderTick: number, exclude?: number): InterpolatedEntity[];
  get newestTick(): number;
}

class NetClient {
  constructor<W, I>(sim: SimAdapter<W, I>, player: PlayerId, selfEntity: number, send: (bytes: Uint8Array) => void, opts?: NetClientOptions);
  readonly stats: ClientStats;
  get nextSeq(): number;
  receiveSnapshot(bytes: Uint8Array, nowMs: number): void;
  tick(input: I, nowMs: number): void;
  tickIntervalMs(): number;
  get serverInputBuffer(): number | null;
  renderTick(nowMs: number): number;
  render(nowMs: number): { self: EntityState | undefined; others: InterpolatedEntity[]; };
  authoritativeSelf(): EntityState | undefined;
  interpolatedSelf(nowMs: number): InterpolatedEntity | undefined;
  predicted(): EntityState | undefined;
  get ready(): boolean;
  get corrections(): number;
  get lastCorrection(): number;
  get pendingInputs(): number;
}

class Predictor {
  constructor<W, I>(sim: SimAdapter<W, I>, player: PlayerId, selfEntity: number, seed?: number, firstSeq?: number);
  lastCorrection: number;
  corrections: number;
  get upcomingSeq(): number;
  get isReady(): boolean;
  predict(input: I, viewTick16: number): InputCommand<I> | null;
  unacked(): readonly InputCommand<I>[];
  reconcile(ackSeq: number, serverSelf: EntityState): void;
  state(): EntityState | undefined;
  renderState(dtMs: number): EntityState | undefined;
}

class ProfileApi {
  constructor(endpoint: string, game: string);
  get(auth: ProfileAuth): Promise<GameProfile>;
  importLocal(guest: string, local: LocalProgress): Promise<GameProfile>;
  claim(session: string, guest: string): Promise<GameProfile>;
  setSettings(auth: ProfileAuth, settings: Readonly<Record<string, unknown>>): Promise<GameProfile>;
  setName(auth: ProfileAuth, displayName: string): Promise<GameProfile>;
  redeem(session: string, item: string, key: string): Promise<GameProfile>;
}

class ServerClock {
  constructor(tickMs: number);
  observe(tick: number, localMs: number): void;
  serverTick(localMs: number): number;
  get ready(): boolean;
}

class SnapshotHistory {
  constructor(capacity?: number);
  put(tick: number, entities: readonly QEntity[] | ReadonlyMap<number, QEntity>): void;
  get(tick: number): ReadonlyMap<number, QEntity> | undefined;
  pruneBefore(tick: number): void;
  get size(): number;
}

class VirtualNet {
  constructor(seed?: number);
  now: number;
  sent: number;
  dropped: number;
  random(): number;
  send(link: LinkOptions, deliver: () => void): void;
  advanceTo(t: number): void;
}

const DEFAULT_CLIENT: NetClientOptions;

const DEFAULT_INPUT_QUEUE: InputQueueOptions;

const GAME_SLUG_RE: RegExp;

const GUEST_ID_RE: RegExp;

const GUEST_KEY: "netnet:guest:v1";

const MSG_INPUT: 1;

const MSG_SNAPSHOT: 2;

const REDUNDANCY: 4;

const ROOM_NAME: "instance";

interface ClientStats {
  snapshots: number;
  snapshotBytes: number;
  inputPackets: number;
  inputBytes: number;
  baselineMisses: number;
  staleSnapshots: number;
}

interface CommandMessage {
  readonly name: string;
  readonly value?: number;
  readonly proof?: string;
}

interface CommandResult {
  readonly name: string;
  readonly ok: boolean;
  readonly reason?: string;
}

interface CreateOptions {
  readonly place: string;
  readonly template: string;
  readonly game?: string;
}

interface DecodedSnapshot {
  readonly header: SnapshotHeader;
  readonly entities: ReadonlyMap<number, QEntity>;
  readonly removed: readonly number[];
}

interface EarnEvent {
  readonly type: 'earn';
  readonly player: PlayerId;
  readonly rule: string;
  readonly units: number;
}

interface EarnMessage {
  readonly rule: string;
  readonly units: number;
}

type EarnRefusal = 'guest' | 'wallet-busy' | 'session';

interface Eip1193 {
  request(args: { method: string; params?: unknown[] }): Promise<unknown>;
}

interface EntitySchema {
  readonly fields: readonly FieldSpec[];
  readonly xField: number;
  readonly yField: number;
  readonly unitsPerWorld: number;
  readonly kindFields?: Readonly<Record<number, readonly number[]>>;
}

interface EntityState {
  readonly id: number;
  readonly kind: number;
  readonly owner: number;
  readonly values: readonly number[];
}

type FieldSpec =
  | { readonly name: string; readonly kind: 'uint'; readonly bits: number; readonly interp?: Interp; readonly deltaBits?: number }
  | { readonly name: string; readonly kind: 'int'; readonly bits: number; readonly interp?: Interp; readonly deltaBits?: number }
  | {
      readonly name: string;
      readonly kind: 'quant';
      readonly min: number;
      readonly max: number;
      readonly bits: number;
      readonly interp?: Interp;
      readonly deltaBits?: number;
    }
  | { readonly name: string; readonly kind: 'angle16'; readonly deltaBits?: number }
  | { readonly name: string; readonly kind: 'bool' };

interface GameProfile {
  readonly game: string;
  readonly kind: 'wallet' | 'guest' | null;
  readonly wallet: string | null;
  readonly displayName: string | null;
  readonly achievements: readonly { readonly id: string; readonly at: number; readonly source: 'sim' | 'import' }[];
  readonly keepers: readonly string[];
  readonly owned: readonly string[];
  readonly cosmetics: readonly number[];
  readonly meta: Readonly<Record<string, number>>;
  readonly goals: { readonly day: number; readonly today: readonly string[]; readonly done: readonly string[] };
  readonly titles: Readonly<Record<string, number>>;
  readonly settings: Readonly<Record<string, unknown>>;
  readonly store: readonly ProfileStoreItem[];
  readonly imported: boolean;
  readonly credit: number;
  readonly totals: { readonly achievements: number; readonly titles: number; readonly games: number };
}

interface Hitbox {
  readonly entity: number;
  readonly owner: PlayerId;
  readonly x: number;
  readonly y: number;
  readonly r: number;
}

interface HitscanRequest {
  readonly shooter: PlayerId;
  readonly ox: number;
  readonly oy: number;
  readonly dx: number;
  readonly dy: number;
  readonly range: number;
}

interface InputCodec<I> {
  write(w: BitWriter, input: I): void;
  read(r: BitReader): I;
  readonly idle: I;
}

interface InputCommand<I> {
  readonly seq: number;
  readonly viewTick16: number;
  readonly input: I;
}

interface InputPacket<I> {
  readonly ackTick: number;
  readonly commands: readonly InputCommand<I>[];
}

interface InputQueueOptions {
  readonly maxQueue: number;
  readonly maxCredits: number;
  readonly targetDepth?: number;
}

type Interp = 'lerp' | 'step';

interface InterpolatedEntity {
  readonly id: number;
  readonly kind: number;
  readonly owner: number;
  readonly values: readonly number[];
}

interface JoinOptions {
  readonly wallet?: string;
  readonly session?: string;
  readonly guest?: string;
}

interface JoinParams {
  readonly endpoint: string; // http(s)://host:port
  readonly place: string;
  readonly template: string;
  readonly game?: string;
  readonly wallet?: string;
  readonly session?: string;
  readonly guest?: string;
  readonly friendRoomId?: string;
}

interface LinkOptions {
  readonly latencyMs: number;
  readonly jitterMs: number;
  readonly loss: number;
}

interface LocalProgress {
  readonly achievements?: readonly string[];
  readonly goals?: { readonly day: number; readonly done: readonly string[] };
  readonly settings?: Readonly<Record<string, unknown>>;
}

interface NetClientOptions {
  readonly interpDelayMs: number;
  readonly inputBufferTarget?: number;
  readonly firstSeq?: number;
}

type PlayerId = number;

interface PlayerRights {
  readonly keepers: readonly number[] | null;
}

interface PotMessage {
  readonly state: 'in' | 'waiting' | 'closed' | 'refused';
  readonly entry: number;
  readonly pot?: number;
  readonly paid?: number;
  readonly reason?: string;
}

type ProfileAuth = { readonly session: string } | { readonly guest: string };

interface ProfileStoreItem {
  readonly id: string;
  readonly kind: 'cosmetic' | 'unlock' | 'meta' | 'gear';
  readonly coins: number | null;
  readonly owned: boolean;
  readonly cosmetic?: number;
  readonly keeper?: string;
  readonly gear?: string;
  readonly loseBelow?: number;
  readonly stat?: string;
  readonly step?: number;
  readonly level?: number;
  readonly levels?: number;
  readonly bonus?: number;
}

interface ProgressEvent {
  readonly type: 'progress';
  readonly player: PlayerId;
  readonly kind: 'achievement' | 'goal' | 'title';
  readonly id: string;
}

interface QEntity {
  readonly id: number;
  readonly kind: number;
  readonly owner: number;
  readonly q: readonly number[];
}

interface RebaseMessage {
  readonly entity: number;
  readonly sim: string;
  readonly version: string;
}

interface RoomConnection<W, I> {
  readonly room: Room;
  readonly net: NetClient<W, I>;
  readonly welcome: WelcomeMessage;
  readonly roomId: string;
  bytesIn(): number;
  messagesIn(): number;
  onEarn(cb: (e: EarnMessage) => void): void;
  onRun(cb: (info: unknown) => void): void;
  latestRun(): unknown;
  onRunId(cb: (m: RunIdMessage) => void): void;
  onRebase(cb: (m: RebaseMessage) => void): void;
  signIn(session: string): Promise<SignInResult>;
  onProfile(cb: (p: GameProfile) => void): void;
  latestProfile(): GameProfile | null;
  stake(amount?: number): void;
  onStake(cb: (m: StakeMessage) => void): void;
  latestStake(): StakeMessage | null;
  pot(): void;
  onPot(cb: (m: PotMessage) => void): void;
  command(cmd: CommandMessage): Promise<CommandResult>;
  claim(): Promise<unknown>;
  leave(): Promise<void>;
}

interface RunIdMessage {
  readonly runId: string | null;
}

interface RunResetEvent {
  readonly type: 'run.reset';
}

interface SignInMessage {
  readonly session: string;
}

interface SignInResult {
  readonly ok: boolean;
  readonly runId: string | null;
  readonly earnRefused?: EarnRefusal;
}

interface SimAdapter<W, I> {
  readonly name: string;
  readonly version: string;
  readonly tickHz: number;
  readonly schema: EntitySchema;
  readonly input: InputCodec<I>;
  readonly maxInputsPerTick?: number;
  createWorld(seed: number, role: 'server' | 'client'): W;
  addPlayer(world: W, player: PlayerId): number;
  removePlayer(world: W, player: PlayerId): void;
  step(world: W, inputsByPlayer: ReadonlyMap<PlayerId, readonly I[]>): readonly SimEvent[];
  snapshot(world: W): readonly EntityState[];
  applySnapshot(world: W, entities: readonly EntityState[]): void;
  hitscans?(world: W, player: PlayerId, input: I): HitscanRequest | null;
  hitboxes?(world: W): readonly Hitbox[];
  applyHit?(world: W, shooter: PlayerId, target: Hitbox): readonly SimEvent[];
  info?(world: W): unknown;
  infoFor?(world: W, player: PlayerId): unknown;
  readonly infoEveryTicks?: number;
  restrictInput?(input: I, rights: PlayerRights): I;
  command?(world: W, player: PlayerId, cmd: SimCommand): boolean;
  startRun?(world: W, player: PlayerId): void;
  disposeWorld?(world: W): void;
}

interface SimCommand {
  readonly name: string;
  readonly value?: number;
}

type SimEvent = EarnEvent | RunResetEvent | ProgressEvent;

interface SnapshotHeader {
  readonly tick: number;
  readonly baselineTick: number;
  readonly ackSeq: number;
  readonly self: number;
  readonly inputBuffer?: number;
}

interface StakeMessage {
  readonly state: 'live' | 'waiting' | 'closed' | 'refused';
  readonly stake: number;
  readonly ceiling?: number;
  readonly paid?: number;
  readonly reason?: string;
  readonly gear?: readonly string[];
  readonly lost?: readonly string[];
}

interface StakeRequest {
  readonly amount?: number;
}

interface StakeTermsView {
  readonly min: number;
  readonly max: number;
  readonly multiple: number;
}

interface WelcomeMessage {
  readonly player: number;
  readonly entity: number;
  readonly tickHz: number;
  readonly snapshotHz: number;
  readonly sim: string;
  readonly version: string;
  readonly place: string;
  readonly template: string;
  readonly runId: string | null;
  readonly earnLive: boolean;
  readonly earnRefused?: EarnRefusal;
  readonly stake?: StakeTermsView;
  readonly pot?: { readonly entry: number; readonly recycle: number };
}