SDK reference - OpenGame

Every export of @opengamehq/sdk 0.1.0, read from the type declarations the package ships. For worked examples, read Connect the SDK, Add a leaderboard and Add multiplayer.

Pick an entry point

Each entry is its own module. The core leaves out the multiplayer transport, and multiplayer, bridge and global include it.

Import	Use it to
`@opengamehq/sdk`	Start the game, read the player, send events, and use leaderboards and achievements.
`@opengamehq/sdk/multiplayer`	Host and join rooms by code.
`@opengamehq/sdk/netcode`	Build a host-authoritative simulation.
`@opengamehq/sdk/avatar`	Name the parts and colors of the player’s OG.
`@opengamehq/sdk/bridge`	Call the SDK from a native engine adapter.
`@opengamehq/sdk/global`	Install the `OpenGame` browser global.
`@opengamehq/sdk/og-platform`	Keep an older game that loads `js/og-platform.js` working.

Handle a failed call

Calls	On failure
Core actions and leaderboards	Return `{ ok: false, error, reason? }`. Success is `{ ok: true, value }`. `init` resolves with the environment; `ready` and `dispose` return no result.
Achievements	Return `{ ok: false, error }` on failure or `{ ok: true, value }` on success. Require a published game session.
Multiplayer `host()` and `join()`	Reject with a `RoomError`.
Netcode helpers	Throw on invalid input.

@opengamehq/sdk

The handshake and lifecycle, player identity, events, leaderboards and achievements. Preview sessions withhold profile details, isolate scores and rooms, and exclude events from public analytics. Achievements require a published game session. The injected /_og/sdk.js build exposes this client as OpenGame.og and starts the hosted handshake during script loading. Call init before tracking events and ready when the game is playable. The opengame.js build provides the core for games without a bundler.

import { og } from "@opengamehq/sdk";

Values: og, OpenGameClient
Functions: trustedParent
Types: Achievement, AchievementResult, AchievementUnlock, AvatarRecipe, Capability, DevPlayer, Environment, InitOptions, Leaderboard, LeaderboardPage, Player, Result, ScoreEntry, ScoreMeta, ScoreReceipt
Referenced: Achievements, Client, Listener, Session

og

const og: Client;

See Client for its methods and fields.

OpenGameClient

type OpenGameClient = Client;
const OpenGameClient: typeof Client;

See Client for its methods and fields.

Client

The class behind og and OpenGameClient. The SDK does not export it by name.

class Client {
    readonly achievements: Achievements;
    get env(): Environment;
    get capabilities(): readonly Capability[];
    readonly player: {
        readonly id: string | null;
        readonly handle: string | null;
        readonly ogNumber: number | null;
        readonly signedIn: boolean;
        readonly avatar: Readonly<{
            seed: number;
            palette: string;
            look?: string;
            character?: string;
        }> | null;
        onChange: (
            listener: Listener<Player>
        ) => () => void;
        requestSignIn: () => Result;
    };
    readonly audio: {
        readonly muted: boolean;
        onHostMute: (
            listener: Listener<boolean>
        ) => () => void;
    };
    readonly fullscreen: {
        readonly active: boolean;
        request: () => Result;
        onChange: (
            listener: Listener<boolean>
        ) => () => void;
    };
    onPause(
        listener: Listener<boolean>
    ): () => void;
    openLink(url: string): Promise<Result>;
    leaderboard(key: string): Leaderboard;
    init(
        options?: InitOptions
    ): Promise<Environment>;
    ready(): void;
    track(
        name: string,
        props?: Record<string, unknown>
    ): Result;
    dispose(): void;
}

achievements

readonly achievements: Achievements;

env

get env(): Environment;

capabilities

get capabilities(): readonly Capability[];

player property

Current player, sign-in action and subscription. onChange calls the listener immediately, then on player changes, and returns an unsubscribe function. Subscribe while loading to receive identity from the injected handshake.

readonly player: {
    readonly id: string | null;
    readonly handle: string | null;
    readonly ogNumber: number | null;
    readonly signedIn: boolean;
    readonly avatar: Readonly<{
        seed: number;
        palette: string;
        look?: string;
        character?: string;
    }> | null;
    onChange: (
        listener: Listener<Player>
    ) => () => void;
    requestSignIn: () => Result;
};

audio

readonly audio: {
    readonly muted: boolean;
    onHostMute: (
        listener: Listener<boolean>
    ) => () => void;
};

fullscreen

readonly fullscreen: {
    readonly active: boolean;
    request: () => Result;
    onChange: (
        listener: Listener<boolean>
    ) => () => void;
};

onPause

onPause(listener: Listener<boolean>): () => void;

openLink

Call directly from a click or key handler. The parent displays the destination; the player then chooses Open site or Keep playing in the parent’s own dialog.

openLink(url: string): Promise<Result>;

leaderboard method

leaderboard(key: string): Leaderboard;

init

Initialize lifecycle listeners and event reporting, reusing any handshake the injected SDK started during loading. Resolves with the available environment, including when hosted services are unavailable. Outside OpenGame hosting, an unanswered handshake uses the local mock. The first call sets the options.

init(options?: InitOptions): Promise<Environment>;

ready

Report that the game is playable, after assets and controls are ready. Starts initialization if needed. Repeated calls have no effect.

ready(): void;

track

Record a custom event after calling init. During startup, valid events wait in a bounded queue for the first analytics session. Success means queued locally, not stored by the server. Batches go to the events API with the game’s session; in the local mock, validated events are printed with console.debug at flush.

track(
    name: string,
    props?: Record<string, unknown>
): Result;

dispose

dispose(): void;

trustedParent

A local parent is trusted only by a local game. A published game must never acquire a localhost exception just because a developer uses the same SDK.

function trustedParent(
    origin: string,
    gameOrigin: string
): boolean;

Achievement

type Achievement = {
    achievementId: string;
    title: string;
    description: string;
    unlocked: boolean;
    unlockedAt: string | null;
    source: 'game_reported';
};

AchievementResult

type AchievementResult<T> = {
    ok: true;
    value: T;
} | {
    ok: false;
    error: string;
};

AchievementUnlock

type AchievementUnlock = {
    achievementId: string;
    unlocked: true;
    firstUnlock: boolean;
    unlockedAt: string;
    source: 'game_reported';
};

AvatarRecipe

look is the head and character the body and clothes, each a recipe string in OpenGame’s stored format. character is present only when look is.

type AvatarRecipe = Readonly<{
    seed: number;
    palette: string;
    look?: string;
    character?: string;
}>;

Capability

type Capability = 'identity'
    | 'leaderboards'
    | 'analytics'
    | 'multiplayer'
    | 'external-links'
    | 'avatar'
    | 'lobby-controls';

DevPlayer

dev.player chooses the local mock’s identity, so a game can be checked as a guest, a signed-in player, or an account that has not claimed a handle yet. ?og-dev-player=guest|signed-in|no-handle on the page URL does the same. The signed-in player shares an avatar with a look and a character, as a hosted player who has turned on profile sharing does.

type DevPlayer = 'guest'
    | 'signed-in'
    | 'no-handle';

Environment

Current connection state and services available to this game. Check capabilities before using a service; previews can have fewer services.

type Environment = Readonly<{
    embedded: boolean;
    connected: boolean;
    preview: boolean;
    sdkVersion: string;
    capabilities: readonly Capability[];
}>;

InitOptions

Options for the first init call. manifest supplies local board and room settings; dev.player selects the local identity. Later calls reuse initialization.

type InitOptions = {
    manifest?: unknown;
    dev?: {
        player?: DevPlayer;
    };
};

Leaderboard

A board declared in opengame.json. Hosted requests use the current game session; the local mock stores scores in this browser. Preview scores stay in that preview.

interface Leaderboard {
    submit(
        value: number,
        meta?: ScoreMeta
    ): Promise<Result<ScoreReceipt>>;
    top(options?: {
        limit?: number;
    }): Promise<Result<LeaderboardPage>>;
    me(): Promise<Result<ScoreEntry | null>>;
    around(): Promise<Result<LeaderboardPage>>;
}

LeaderboardPage

type LeaderboardPage = Readonly<{
    entries: readonly ScoreEntry[];
    order: 'asc' | 'desc';
    preview: boolean;
    source: 'game_reported';
}>;

Player

The game’s player identity. id is scoped to this game. Profile sharing controls handle, ogNumber and avatar, independently of signedIn. Null fields are valid for guests, withheld profiles and unavailable sessions. Previews withhold profiles.

type Player = Readonly<{
    id: string | null;
    handle: string | null;
    ogNumber: number | null;
    signedIn: boolean;
    avatar?: AvatarRecipe | null;
}>;

Result

type Result<T = void> = {
    ok: true;
    value: T;
} | {
    ok: false;
    error: string;
    reason?: string;
};

ScoreEntry

type ScoreEntry = Readonly<{
    name: string | null;
    score: number;
    meta: ScoreMeta;
    createdAt: string;
    rank: number;
    isMe: boolean;
}>;

ScoreMeta

What a score may carry beside its value. These keys and types are the policy the API and the SDK check every submission against: another key, or a value of another type, fails with invalid_meta before anything is sent.

type ScoreMeta = {
    label?: string;
    mode?: string;
    level?: string;
    character?: string;
    duration_ms?: number;
    accuracy?: number;
    combo?: number;
};

ScoreReceipt

type ScoreReceipt = Readonly<{
    score: number;
    state: 'ok' | 'clamped' | 'rejected';
    best: boolean;
    preview: boolean;
}>;

Referenced declarations in core

These declarations describe types used by this entry’s public signatures. They are not additional named exports from this entry. Achievements

class Achievements {
    constructor(session: () => Session);
    unlock(
        id: string
    ): Promise<AchievementResult<AchievementUnlock>>;
    list(): Promise<AchievementResult<Achievement[]>>;
}

Listener

type Listener<T> = (value: T) => void;

Session

type Session = {
    token: string | null;
    preview: boolean;
    disposed: boolean;
    generation: number;
};

@opengamehq/sdk/multiplayer

Rooms by code through the OpenGame broker, with lobby controls, readiness, scheduled phases and connection statistics. Hosted rooms support optional host migration through a game-supplied checkpoint and restore adapter. This entry loads the PeerJS transport.

import { multiplayer, RoomError } from "@opengamehq/sdk/multiplayer";

Values: binaryHeaderBytes, errorCatalogue, Lobby, multiplayer, Multiplayer, Room, RoomError
Functions: mountLobby
Types: AuthorityChange, BinaryPayload, Channel, ErrorEntry, HostOptions, JoinOptions, Json, LobbyOptions, LobbySelection, LobbyState, LobbyTheme, LobbyViewOptions, MigrationAdapter, PeerStats, PhaseOptions, RoomClock, RoomConfiguration, RoomData, RoomEvents, RoomMember, RoomPeer, RoomPhase, RoomReadiness, RoomStats, SendResult, Signalling
Referenced: Achievement, AchievementResult, Achievements, AchievementUnlock, AvatarRecipe, Capability, Client, ClientLobby, ClientRoom, ClientRoomError, DevPlayer, Environment, InitOptions, Leaderboard, LeaderboardPage, Listener, LobbyAllowlist, LobbyConfigurationPolicy, LobbyMember, MultiplayerClient, OpenGameClient, Player, Result, RoomConfig, ScoreEntry, ScoreMeta, ScoreReceipt, Session

binaryHeaderBytes

const binaryHeaderBytes = 12;

errorCatalogue

const errorCatalogue: readonly ErrorEntry[];

Lobby

type Lobby = ClientLobby;
const Lobby: typeof ClientLobby;

See ClientLobby for its methods and fields.

multiplayer

const multiplayer: MultiplayerClient;

See MultiplayerClient for its methods and fields.

Multiplayer class

type Multiplayer = MultiplayerClient;
const Multiplayer: typeof MultiplayerClient;

See MultiplayerClient for its methods and fields.

Room

type Room = ClientRoom;
const Room: typeof ClientRoom;

See ClientRoom for its methods and fields.

RoomError

type RoomError = ClientRoomError;
const RoomError: typeof ClientRoomError;

See ClientRoomError for its methods and fields.

ClientLobby

The class behind Lobby. The SDK does not export it by name.

class ClientLobby {
    readonly started: Promise<Room>;
    constructor(
        multiplayer: Multiplayer,
        options: LobbyOptions,
        capacity: number
    );
    get state(): LobbyState;
    onChange(
        listener: (state: LobbyState) => void
    ): () => void;
    setRelayOnly(value: boolean): void;
    setDisplayName(value: string): Promise<void>;
    setConfiguration(
        value: unknown
    ): Promise<void>;
    host(): Promise<void>;
    join(code: string): Promise<void>;
    ready(value?: boolean): void;
    start(): Promise<void>;
    close(reason?: string): void;
}

ClientRoomError

The class behind RoomError. The SDK does not export it by name.

class ClientRoomError extends Error {
    readonly code: string;
    readonly hint: string;
    readonly retryable: boolean;
    constructor(code: string);
}

code

readonly code: string;

hint

readonly hint: string;

retryable

readonly retryable: boolean;

ClientRoom

The class behind Room. The SDK does not export it by name.

class ClientRoom {
    readonly code: string;
    readonly local: boolean;
    readonly inviteUrl: string | null;
    readonly maxPlayers: number;
    private constructor();
    get maxPacketBytes(): number;
    get role(): 'host' | 'guest';
    get authorityEpoch(): number;
    get self(): RoomPeer;
    get peers(): readonly RoomPeer[];
    get phaseState(): RoomPhase;
    get readyState(): RoomReadiness;
    get lobbyMembers(): readonly RoomMember[];
    get configuration(): LobbySelection;
    get configurationState(): RoomConfiguration | null;
    configure(
        selection: LobbySelection
    ): Promise<RoomConfiguration>;
    startConfiguration(): Promise<void>;
    setDisplayName(name: string): Promise<void>;
    refreshLobby(): Promise<void>;
    playerReadiness(id: string): boolean | null;
    get isClosed(): boolean;
    get isMigrating(): boolean;
    get signalling(): Signalling;
    get clock(): RoomClock;
    now(): number;
    on<K extends keyof RoomEvents>(
        event: K,
        listener: (...args: RoomEvents[K]) => void
    ): () => void;
    static connect(
        client: OpenGameClient,
        role: 'host' | 'guest',
        code: string,
        options: HostOptions,
        config: RoomConfig
    ): Promise<Room>;
    send(data: Json | BinaryPayload, options?: {
        reliable?: boolean;
        peer?: string;
    }): SendResult;
    disconnectPeer(peer: string): void;
    broadcast(data: Json | BinaryPayload, options?: {
        reliable?: boolean;
    }): SendResult;
    ready(value?: boolean): void;
    phase(
        name: string | null,
        options?: number | PhaseOptions
    ): RoomPhase;
    stats(): RoomStats;
    stats(peer: string): PeerStats | null;
    close(reason?: string): void;
}

MultiplayerClient

The class behind multiplayer and Multiplayer. The SDK does not export it by name.

class MultiplayerClient {
    constructor(client?: OpenGameClient);
    get invite(): string | null;
    createLobby(options?: LobbyOptions): Lobby;
    lobby(
        options?: LobbyViewOptions
    ): Promise<Room>;
    host(options?: HostOptions): Promise<Room>;
    join(
        code: string,
        options?: JoinOptions
    ): Promise<Room>;
    joinInvite(
        options?: JoinOptions
    ): Promise<Room | null>;
}

invite

The join code from the invite link this player arrived with, or null. Read it after og.init(); it clears once a room is hosted or joined.

get invite(): string | null;

createLobby

Headless controls for games that render their own lobby.

createLobby(options?: LobbyOptions): Lobby;

lobby method

Optional reference controls. Resolves with the room when its host starts.

lobby(options?: LobbyViewOptions): Promise<Room>;

host

host(options?: HostOptions): Promise<Room>;

join

join(
    code: string,
    options?: JoinOptions
): Promise<Room>;

joinInvite

Join the invite this player arrived with. Resolves to null when there is none, so await multiplayer.joinInvite() ?? await multiplayer.host() covers both.

joinInvite(
    options?: JoinOptions
): Promise<Room | null>;

mountLobby

Render the optional reference controls in the game’s chosen container. Replacement interfaces use the same Lobby methods and subscribe to the same state.

function mountLobby(lobby: Lobby, options: LobbyViewOptions & {
    container: HTMLElement;
}): () => void;

AuthorityChange

type AuthorityChange = Readonly<{
    epoch: number;
    role: 'host' | 'guest';
}>;

BinaryPayload

type BinaryPayload = ArrayBuffer
    | ArrayBufferView;

Channel

type Channel = 'reliable' | 'unreliable';

ErrorEntry

Error code, delivery type, retry advice and recovery text.

type ErrorEntry = Readonly<{
    code: string;
    where: 'room' | 'result' | 'both';
    retryable: boolean;
    hint: string;
}>;

HostOptions

relayOnly hides this player’s network address from peers by using relay candidates. Players who choose direct connections can expose their own addresses. Relay connections use more bandwidth and may add latency.

type HostOptions = {
    maxPlayers?: number;
    signal?: AbortSignal;
    relayOnly?: boolean;
    migration?: MigrationAdapter;
};

JoinOptions

type JoinOptions = {
    signal?: AbortSignal;
    relayOnly?: boolean;
    migration?: MigrationAdapter;
};

Json

type Json = null
    | boolean
    | number
    | string
    | Json[]
    | {
    [key: string]: Json;
};

LobbyOptions

type LobbyOptions = HostOptions & {
    minPlayers?: number;
};

LobbySelection

type LobbySelection = Readonly<Record<string, string>>;

LobbyState

type LobbyState = Readonly<{
    status: 'idle'
        | 'connecting'
        | 'waiting'
        | 'started'
        | 'ended';
    code: string | null;
    inviteUrl: string | null;
    role: 'host' | 'guest' | null;
    players: number;
    minPlayers: number;
    maxPlayers: number;
    ready: number;
    selfReady: boolean;
    configuration?: LobbySelection;
    configurationRevision?: number;
    roster: readonly LobbyMember[];
    canStart: boolean;
    signalling: Signalling;
    relayOnly: boolean;
    error: RoomError | null;
}>;

LobbyTheme

type LobbyTheme = Partial<Record<'background' | 'text' | 'muted' | 'border' | 'accent' | 'font', string>>;

LobbyViewOptions

type LobbyViewOptions = LobbyOptions & {
    container?: HTMLElement;
    theme?: LobbyTheme;
};

MigrationAdapter

Opt-in state format owned by the game. Every peer must supply the same schema and a restore function. A failed restore ends the match.

type MigrationAdapter = {
    schema: string;
    checkpoint(): Json | Promise<Json>;
    restore(state: Json, context: Readonly<{
        epoch: number;
        role: 'host' | 'guest';
    }>): void | Promise<void>;
};

PeerStats

One peer, as this side measures it. rtt is smoothed (RFC 6298), minRtt the best sample, jitter the smoothed deviation, and loss covers the last few heartbeats.

type PeerStats = Readonly<{
    id: string;
    rtt: number | null;
    minRtt: number | null;
    jitter: number | null;
    loss: number;
    relay: boolean;
}>;

PhaseOptions

type PhaseOptions = {
    delayMs?: number;
    waitForReady?: boolean;
};

RoomClock

Estimated host time: sample count, sync status and uncertainty in milliseconds. After sync, clock corrections are gradual and time never decreases.

type RoomClock = Readonly<{
    synced: boolean;
    samples: number;
    uncertaintyMs: number | null;
}>;

RoomConfiguration

type RoomConfiguration = Readonly<{
    allowlist: LobbyAllowlist;
    selection: LobbySelection;
    revision: number;
    started: boolean;
}>;

RoomData

type RoomData = Json | Uint8Array;

RoomEvents

type RoomEvents = {
    join: [
        peer: RoomPeer
    ];
    leave: [
        peer: RoomPeer,
        reason: string
    ];
    message: [
        peer: RoomPeer,
        data: RoomData,
        channel: Channel
    ];
    phase: [
        phase: RoomPhase
    ];
    readiness: [
        state: RoomReadiness
    ];
    clock: [
        clock: RoomClock
    ];
    signalling: [
        state: Signalling
    ];
    authority: [
        change: AuthorityChange
    ];
    migrating: [
    ];
    members: [
        members: readonly RoomMember[]
    ];
    configuration: [
        configuration: RoomConfiguration
    ];
    'host-left': [
    ];
    close: [
        reason: string
    ];
};

RoomMember

type RoomMember = RoomPeer & Readonly<{
    role: 'host' | 'guest';
    displayName: string | null;
    nameRevision: number;
}>;

RoomPeer

Connection ID; stable member slot across reconnects; reusable zero-based seat for colours and spawn points.

type RoomPeer = Readonly<{
    id: string;
    slot: number;
    seat: number;
    player: Player;
}>;

RoomPhase

type RoomPhase = Readonly<{
    epoch: number;
    name: string | null;
    at: number | null;
}>;

RoomReadiness

type RoomReadiness = Readonly<{
    epoch: number;
    total: number;
    ready: number;
    selfReady: boolean;
    allReady: boolean;
}>;

RoomStats

Maximum peer RTT and jitter, aggregate packet loss and relay status.

type RoomStats = Readonly<{
    local: boolean;
    peers: number;
    rtt: number | null;
    minRtt: number | null;
    jitter: number | null;
    loss: number;
    relay: boolean;
    relayReason: string | null;
    signalling: Signalling;
}>;

SendResult

Counts sent and dropped packets. A closed room sends nothing; an absent recipient counts as dropped.

type SendResult = Readonly<{
    sent: number;
    dropped: number;
    closed: boolean;
}>;

Signalling

Broker status. Existing peer links work during reconnection; joining resumes after recovery.

type Signalling = 'ok'
    | 'reconnecting'
    | 'lost'
    | 'local';

Referenced declarations in multiplayer

These declarations describe types used by this entry’s public signatures. They are not additional named exports from this entry. LobbyMember

type LobbyMember = Readonly<{
    id: string;
    handle: string | null;
    look: null;
    self: boolean;
    ready: boolean | null;
    displayName?: string;
}>;

LobbyAllowlist

type LobbyAllowlist = readonly (readonly [
    key: string,
    choices: readonly string[],
    initial: string
])[];

RoomConfig

type RoomConfig = {
    lobbyPolicy?: LobbyConfigurationPolicy;
    displayNameCharsMax?: number;
    broker: string;
    maxPlayers: number;
    timeoutMs: number;
    heartbeatMs: number;
    livenessMs: number;
    packetBytesMax: number;
    jsonDepthMax: number;
    codeChars: number;
    unreliableChannelId: number;
    clockSamplesMax: number;
    phaseDelayMs: number;
    phaseNameCharsMax: number;
    responseBytesMax: number;
    migration?: {
        checkpointBytesMax: number;
        checkpointAgeMsMax: number;
        leaseMs: number;
        checkpointIntervalMs: number;
        schemaCharsMax: number;
        jsonDepthMax: number;
    };
    dropBytes: number;
    disconnectBytes: number;
    stunUrls: string[];
    handlePattern: string;
    clockBurst: number;
    clockBurstIntervalMs: number;
    clockSyncedSamples: number;
    clockSlewPerMs: number;
    statsWindowTicks: number;
    signallingRetryDelaysMs: number[];
    byeGraceMs: number;
    turnRefreshFraction: number;
    turnTtlSeconds: number;
};

LobbyConfigurationPolicy

type LobbyConfigurationPolicy = Readonly<{
    lobbySettingsMax: number;
    lobbyChoicesMax: number;
    lobbyIdCharsMax: number;
}>;

@opengamehq/sdk/netcode

Helpers for a host-authoritative simulation, covering message tables, input history, quantisation and smoothing.

import {
    defineMessages,
    numberField,
    InputQueue,
    smoothCamera
} from "@opengamehq/sdk/netcode";

Values: booleanField
Functions: arrayField, cyclicLerp, defineMessages, extrapolateScalar, lagCompensationMs, nullable, numberField, objectSchema, oneOf, smoothCamera, stringField, symmetricQuantizer, tupleField
Classes: EventLedger, InputHistory, InputQueue
Types: Fields, GameMessage, InputCommand, LedgerEntry, Validator
Referenced: FieldSet, FieldValue, Json, MessageTable

booleanField

const booleanField: Validator<boolean>;

arrayField

An array of up to maxLength items, each checked by item.

function arrayField<T extends Json>(
    item: Validator<T>,
    maxLength: number
): Validator<T[]>;

cyclicLerp

function cyclicLerp(
    from: number,
    to: number,
    alpha: number,
    period?: number
): number;

defineMessages

function defineMessages<const T extends MessageTable>(
    table: T
): Readonly<{
    read: (
        value: unknown
    ) => GameMessage<T> | null;
    write<K extends keyof T & string>(
        type: K,
        data: FieldValue<T[K]>
    ): Extract<GameMessage<T>, {
        type: K;
    }>;
}>;

extrapolateScalar

function extrapolateScalar(
    position: number,
    velocityPerSecond: number,
    elapsedMs: number,
    maxMs?: number
): number;

lagCompensationMs

Calculate the rewind window from full RTT, snapshot age, interpolation and jitter. Returns null until RTT and jitter are measured; use no rewind then.

function lagCompensationMs(terms: {
    rttMs: number | null;
    snapshotAgeMs: number;
    interpolationMs: number;
    jitterMs: number | null;
}): number | null;

nullable

Accept a value or null. Object schemas require the field and reject extra fields.

function nullable<T extends Json>(
    validator: Validator<T>
): Validator<T | null>;

numberField

function numberField(
    min: number,
    max: number,
    integer?: boolean
): Validator<number>;

objectSchema

The same exact-key validator can be used by a producer and its host.

function objectSchema<const F extends FieldSet>(
    fields: F
): Validator<Fields<F>>;

oneOf

One of a fixed set of literals: a weapon, an emote, a team.

function oneOf<const T extends readonly (string | number | boolean | null)[]>(
    ...literals: T
): Validator<T[number]>;

smoothCamera

Use only for presentation. Apply authoritative positions to simulation immediately, then smooth the camera independently with this function.

function smoothCamera(
    previous: number,
    authoritative: number,
    deltaMs: number,
    halfLifeMs?: number
): number;

stringField

A string of at most maxChars code units, optionally matching pattern in full.

function stringField(
    maxChars: number,
    pattern?: RegExp
): Validator<string>;

symmetricQuantizer

function symmetricQuantizer(
    range: number,
    stepsPerSide?: number
): Readonly<{
    encode(value: number): number;
    decode(value: number): number;
}>;

tupleField

An array of exactly these positions:

tupleField(numberField(-1, 1), numberField(-1, 1)) // for a stick

function tupleField<const T extends readonly Validator<Json>[]>(
    ...items: T
): Validator<{
    -readonly [K in keyof T]: FieldValue<T[K]>;
}>;

EventLedger

class EventLedger<T extends Json> {
    append(value: T): number;
    reader(): () => readonly LedgerEntry<T>[];
    get size(): number;
}

InputHistory

class InputHistory<T extends Json> {
    constructor(validate: Validator<T>);
    push(input: T): InputCommand<T>;
    packet(): readonly InputCommand<T>[];
}

InputQueue

Create one queue per player. Discarding the oldest excess inputs bounds latency when a faster client produces more commands than the host uses.

class InputQueue<T extends Json> {
    constructor(validate: Validator<T>);
    ingest(packet: unknown): {
        accepted: number;
        dropped: number;
    };
    drain(
        tick: number
    ): readonly InputCommand<T>[];
    get size(): number;
}

Fields

type Fields<F extends FieldSet> = {
    [K in keyof F]: FieldValue<F[K]>;
};

GameMessage

type GameMessage<T extends MessageTable> = {
    [K in keyof T]: Readonly<{
        type: K;
        data: FieldValue<T[K]>;
    }>;
}[keyof T];

InputCommand

type InputCommand<T extends Json> = Readonly<{
    sequence: number;
    input: T;
}>;

LedgerEntry

type LedgerEntry<T extends Json> = Readonly<{
    sequence: number;
    value: T;
}>;

Validator

type Validator<T> = (
    value: unknown
) => value is T;

Referenced declarations in netcode

These declarations describe types used by this entry’s public signatures. They are not additional named exports from this entry. FieldSet

type FieldSet = Record<string, Validator<Json>>;

FieldValue

type FieldValue<F> = F extends Validator<infer T> ? T : never;

MessageTable

type MessageTable = Record<string, Validator<Json>>;

@opengamehq/sdk/avatar

Turns og.player.avatar into a head and an outfit with named parts and colors, for a game that draws the player’s OG with custom art. Draw the player’s OG covers each point of view.

import { readAvatar, watchAvatar } from "@opengamehq/sdk/avatar";

Functions: readAvatar, watchAvatar
Types: Avatar, AvatarColor, AvatarHead, AvatarOutfit
Referenced: AvatarRecipe

readAvatar

Names the parts of og.player.avatar. Returns null when there is no look to draw: a guest, a player who has not turned on “Show my OG in games”, a private preview, or a malformed recipe. Use your game’s default character then.

function readAvatar(
    recipe: Pick<AvatarRecipe, 'look' | 'character'>
        | null
        | undefined
): Avatar | null;

watchAvatar

Calls listener with the player’s OG now, and again only when the look or the outfit changes: a guest signing in, a player switching accounts, or signing out (null). A session refresh with the same recipe does not call it, so a game can rebuild the model here and not on every onChange. A listener that throws is reported with console.error. Returns the unsubscribe function.

function watchAvatar(client: {
    readonly player: {
        onChange(listener: (player: {
            readonly avatar?: AvatarRecipe | null;
        }) => void): () => void;
    };
}, listener: (avatar: Avatar | null) => void): () => void;

Avatar

The player’s OG. outfit is null when the player shared no outfit or it is in a version this SDK cannot read: draw your default body under their head.

type Avatar = Readonly<{
    head: AvatarHead;
    outfit: AvatarOutfit | null;
}>;

AvatarColor

A color in the recipe. followsHead is true for avatar and match, which take the head’s color, and hex is then the head’s unshaded swatch: OpenGame draws match as the head and avatar darker by garment, with bottoms at roughly half the head’s brightness and shoes close to it, so darken it to match. hex is null for a color this SDK build does not know.

type AvatarColor = Readonly<{
    id: string;
    hex: string | null;
    followsHead: boolean;
}>;

AvatarHead

The head, from look. color is the current id, so an old ink becomes black. hex is the color’s swatch. finish is true for a patterned, metallic, glowing or translucent color such as plaid, gold, neon pink or glass, which the swatch only approximates; mono (“Auto”) is black on a light page and white on a dark one, and its swatch is the black. accessory is null when there is none. identity picks a face set and is male unless the player chose otherwise: do not read it as gender, pronouns or a voice.

type AvatarHead = Readonly<{
    recipe: string;
    shape: string;
    eyes: string;
    color: string;
    hex: string | null;
    finish: boolean;
    accessory: string | null;
    identity: 'male' | 'female';
}>;

AvatarOutfit

The body and clothes, from character. shirt is "none" when the torso is the head’s color. accessories is empty when none are worn.

type AvatarOutfit = Readonly<{
    recipe: string;
    version: 'c1' | 'c2' | 'c3' | 'c4';
    body: string;
    legs: string;
    shirt: string;
    bottoms: string;
    accessories: readonly string[];
    shoes: string;
    colors: Readonly<{
        shirt: AvatarColor;
        bottoms: AvatarColor;
        shoes: AvatarColor;
        accessories: AvatarColor;
    }>;
}>;

@opengamehq/sdk/bridge

JSON and byte calls for native engine adapters over the existing SDK client. Exports the shared bridge, its types and the createBridge factory; importing this module does not install the browser global.

import { bridge, createBridge } from "@opengamehq/sdk/bridge";

Values: bridge
Functions: createBridge
Types: BridgeEvent, BridgeHandler, BridgeOperation, OpenGameBridge
Referenced: Achievement, AchievementResult, Achievements, AchievementUnlock, AuthorityChange, AvatarRecipe, BinaryPayload, Capability, Channel, Client, ClientLobby, ClientRoom, ClientRoomError, DevPlayer, Environment, HostOptions, InitOptions, JoinOptions, Json, Leaderboard, LeaderboardPage, Listener, Lobby, LobbyAllowlist, LobbyConfigurationPolicy, LobbyMember, LobbyOptions, LobbySelection, LobbyState, LobbyTheme, LobbyViewOptions, MigrationAdapter, Multiplayer, MultiplayerClient, OpenGameClient, PeerStats, PhaseOptions, Player, Result, Room, RoomClock, RoomConfig, RoomConfiguration, RoomData, RoomError, RoomEvents, RoomMember, RoomPeer, RoomPhase, RoomReadiness, RoomService, RoomStats, ScoreEntry, ScoreMeta, ScoreReceipt, SendResult, Session, Signalling

bridge

const bridge: OpenGameBridge;

See OpenGameBridge for its methods and fields.

createBridge

function createBridge(
    client: OpenGameClient,
    service: RoomService
): OpenGameBridge;

BridgeEvent

type BridgeEvent = 'player'
    | 'pause'
    | 'mute'
    | 'fullscreen'
    | 'room.join'
    | 'room.leave'
    | 'room.message'
    | 'room.phase'
    | 'room.close'
    | 'room.readiness'
    | 'room.clock'
    | 'room.signalling'
    | 'room.members'
    | 'room.configuration';

BridgeHandler

type BridgeHandler = (
    kind: 'result' | 'event',
    id: number,
    name: string,
    json: string,
    bytes?: Uint8Array
) => void;

BridgeOperation

Operations accepted by request. Achievement calls use the same published-game session as og.achievements; native adapters receive their results as JSON.

type BridgeOperation = 'init'
    | 'track'
    | 'openLink'
    | 'fullscreen'
    | 'signIn'
    | 'board.submit'
    | 'board.top'
    | 'board.me'
    | 'board.around'
    | 'achievements.unlock'
    | 'achievements.list'
    | 'room.host'
    | 'room.join'
    | 'room.joinInvite'
    | 'room.close'
    | 'room.ready'
    | 'room.phase'
    | 'room.state'
    | 'room.stats'
    | 'room.now';

OpenGameBridge

Native callers copy strings and byte views across their FFI. No engine owns a session or a transport: all validation and network work remains in the core.

interface OpenGameBridge {
    readonly version: string;
    setHandler(
        handler: BridgeHandler | null
    ): void;
    request(
        op: BridgeOperation,
        args: string
    ): number;
    env(): string;
    player(): string;
    ready(): void;
    send(
        room: number,
        data: Uint8Array | string,
        reliable: boolean
    ): string;
    sendTo(
        room: number,
        peer: string,
        data: Uint8Array | string,
        reliable: boolean
    ): string;
    disconnectPeer(
        room: number,
        peer: string
    ): string;
    readonly maxPacketBytes: number;
}

Referenced declarations in bridge

These declarations describe types used by this entry’s public signatures. They are not additional named exports from this entry. RoomService

type RoomService = Pick<Multiplayer, 'host' | 'join' | 'joinInvite'>;

@opengamehq/sdk/global

Side-effect entry that installs the complete OpenGame browser global and starts the handshake in hosted frames. Its declarations export the OpenGameGlobal type and declare globalThis.OpenGame and window.OpenGame; there are no named runtime exports. Use the injected client when it is already present. Same-major SDK bundles reuse the installed core.

import "@opengamehq/sdk/global";
import type { OpenGameGlobal } from "@opengamehq/sdk/global";

Types: OpenGameGlobal
Referenced: Achievement, AchievementResult, Achievements, AchievementUnlock, AuthorityChange, AvatarRecipe, BinaryPayload, BridgeHandler, BridgeOperation, Capability, Channel, Client, ClientLobby, ClientRoom, ClientRoomError, DevPlayer, Environment, errorCatalogue, ErrorEntry, HostOptions, InitOptions, JoinOptions, Json, Leaderboard, LeaderboardPage, Listener, Lobby, LobbyAllowlist, LobbyConfigurationPolicy, LobbyMember, LobbyOptions, LobbySelection, LobbyState, LobbyTheme, LobbyViewOptions, MigrationAdapter, mountLobby, multiplayer, Multiplayer, MultiplayerClient, netcode, OpenGameBridge, OpenGameClient, PeerStats, PhaseOptions, Player, Result, Room, RoomClock, RoomConfig, RoomConfiguration, RoomData, RoomError, RoomEvents, RoomMember, RoomPeer, RoomPhase, RoomReadiness, RoomStats, ScoreEntry, ScoreMeta, ScoreReceipt, SendResult, Session, Signalling, trustedParent

OpenGameGlobal

type OpenGameGlobal = OpenGameClient & {
    readonly og: OpenGameClient;
    readonly bridge: OpenGameBridge;
    readonly multiplayer: typeof multiplayer;
    readonly netcode: typeof netcode;
    readonly OpenGameClient: typeof OpenGameClient;
    readonly trustedParent: typeof trustedParent;
    readonly Multiplayer: typeof Multiplayer;
    readonly Room: typeof Room;
    readonly RoomError: typeof RoomError;
    readonly Lobby: typeof Lobby;
    readonly mountLobby: typeof mountLobby;
    readonly errorCatalogue: typeof errorCatalogue;
};

Referenced declarations in global

These declarations describe types used by this entry’s public signatures. They are not additional named exports from this entry. netcode The @opengamehq/sdk/netcode entry, imported whole as a namespace. Its exports are listed in that section above.

Browser global declarations

declare global {
    var OpenGame: OpenGameGlobal;
    interface Window {
        OpenGame: OpenGameGlobal;
    }
}

@opengamehq/sdk/og-platform

Compatibility module for games using js/og-platform.js. Copy dist/og-platform.js into the build to replace that file. It reuses the installed same-major core, including the injected SDK. New code can use its og export or the core package.

import {
    ogEvent,
    ogIceServers,
    ogIsEmbedded
} from "@opengamehq/sdk/og-platform";

Values: og, OG_API, OG_DIRECT_ONLY_NOTICE, OG_ENABLED, OG_PARENT_ORIGINS, OG_RTC
Functions: ogAuthHeaders, ogAwaitSession, ogEvent, ogHostLabel, ogHostPeerId, ogIceServers, ogInviteBase, ogIsActive, ogIsEmbedded, ogIsFullscreen, ogIsHostMuted, ogJoinCode, ogLobbySession, ogLobbyTicket, ogManageMedia, ogOnActivity, ogOnFullscreenChange, ogOnHostMute, ogPageUrl, ogPeerOptions, ogReady, ogSessionToken, ogUrl
Referenced: Achievement, AchievementResult, Achievements, AchievementUnlock, AvatarRecipe, Capability, Client, DevPlayer, Environment, InitOptions, Leaderboard, LeaderboardPage, Listener, Player, Result, ScoreEntry, ScoreMeta, ScoreReceipt, Session

og in og-platform

const og: Client;

See Client for its methods and fields.

OG_API

const OG_API = "https://api.opengame.gg";

OG_DIRECT_ONLY_NOTICE

const OG_DIRECT_ONLY_NOTICE = "No relay. Other networks may fail to connect. Peers see your IP address.";

OG_ENABLED

const OG_ENABLED: boolean;

OG_PARENT_ORIGINS

Compatibility list of parent origins. The SDK validates trust using the current game origin and the message source.

const OG_PARENT_ORIGINS: readonly string[];

OG_RTC

const OG_RTC = "rtc.opengame.gg";

ogAuthHeaders

function ogAuthHeaders(): Record<string, string>;

ogAwaitSession

function ogAwaitSession(
    timeoutMs?: number
): Promise<boolean>;

ogEvent

function ogEvent(
    name: string,
    props?: Record<string, unknown>
): void;

ogHostLabel

function ogHostLabel(): string | null;

ogHostPeerId

function ogHostPeerId(
    ticket: string | null
): Promise<string | null>;

ogIceServers

function ogIceServers(
    ticket: string | null
): Promise<{
    iceServers: {
        urls: string;
    }[];
    relay: boolean;
    reason: string;
} | {
    iceServers: any[];
    relay: boolean;
    reason: null;
}>;

ogInviteBase

Parent page address for invite links. Empty until an embedded game receives the page address.

function ogInviteBase(): string;

ogIsActive

function ogIsActive(): boolean;

ogIsEmbedded

function ogIsEmbedded(): boolean;

ogIsFullscreen

function ogIsFullscreen(): boolean;

ogIsHostMuted

function ogIsHostMuted(): boolean;

ogJoinCode

function ogJoinCode(): string | null;

ogLobbySession

function ogLobbySession(
    role: 'host' | 'guest',
    code: string
): Promise<{
    ticket: string | null;
    iceServers: any[] | {
        urls: string;
    }[];
    relay: boolean;
    relayReason: string | null;
    options: {
        config: {
            iceServers: any[] | {
                urls: string;
            }[];
            sdpSemantics: string;
        };
        key?: string | undefined;
        host: string;
        secure: boolean;
        port: number;
        path: string;
    };
}>;

ogLobbyTicket

Legacy PeerJS ticket request. New games use @opengamehq/sdk/multiplayer for verified player identity.

function ogLobbyTicket(
    role: 'host' | 'guest',
    code: string,
    timeoutMs?: number
): Promise<string | null>;

ogManageMedia

function ogManageMedia<T extends Element>(
    element: T
): T;

ogOnActivity

function ogOnActivity(
    fn: (active: boolean) => void
): () => void;

ogOnFullscreenChange

function ogOnFullscreenChange(
    fn: (active: boolean) => void
): () => void;

ogOnHostMute

function ogOnHostMute(
    fn: (muted: boolean) => void
): () => void;

ogPageUrl

function ogPageUrl(): string | null;

ogPeerOptions

function ogPeerOptions(): {
    host: string;
    secure: boolean;
    port: number;
    path: string;
};

ogReady

function ogReady(): void;

ogSessionToken

function ogSessionToken(): string | null;

ogUrl

function ogUrl(path: string): string | null;

​Pick an entry point

​Handle a failed call

​@opengamehq/sdk

​og

​OpenGameClient

​Client

​achievements

​env

​capabilities

​player property

​audio

​fullscreen

​onPause

​openLink

​leaderboard method

​init

​ready

​track

​dispose

​trustedParent

​Achievement

​AchievementResult

​AchievementUnlock

​AvatarRecipe

​Capability

​DevPlayer

​Environment

​InitOptions

​Leaderboard

​LeaderboardPage

​Player

​Result

​ScoreEntry

​ScoreMeta

​ScoreReceipt

​Referenced declarations in core

​@opengamehq/sdk/multiplayer

​binaryHeaderBytes

​errorCatalogue

​Lobby

​multiplayer

​Multiplayer class

​Room

​RoomError

​ClientLobby

​ClientRoomError

​code

​hint

​retryable

​ClientRoom

​MultiplayerClient

​invite

​createLobby

​lobby method

​host

​join

​joinInvite

​mountLobby

​AuthorityChange

​BinaryPayload

​Channel

​ErrorEntry

​HostOptions

​JoinOptions

​Json

​LobbyOptions

​LobbySelection

​LobbyState

​LobbyTheme

​LobbyViewOptions

​MigrationAdapter

​PeerStats

​PhaseOptions

​RoomClock

​RoomConfiguration

​RoomData

​RoomEvents

​RoomMember

​RoomPeer

​RoomPhase

Pick an entry point

Handle a failed call

@opengamehq/sdk

og

OpenGameClient

Client

achievements

env

capabilities

player property

audio

fullscreen

onPause

openLink

leaderboard method

init

ready

track

dispose

trustedParent

Achievement

AchievementResult

AchievementUnlock

AvatarRecipe

Capability

DevPlayer

Environment

InitOptions

Leaderboard

LeaderboardPage

Player

Result

ScoreEntry

ScoreMeta

ScoreReceipt

Referenced declarations in core

@opengamehq/sdk/multiplayer

binaryHeaderBytes

errorCatalogue

Lobby

multiplayer

Multiplayer class

Room

RoomError

ClientLobby

ClientRoomError

code

hint

retryable

ClientRoom

MultiplayerClient

invite

createLobby

lobby method

host

join

joinInvite

mountLobby

AuthorityChange

BinaryPayload

Channel

ErrorEntry

HostOptions

JoinOptions

Json

LobbyOptions

LobbySelection

LobbyState

LobbyTheme

LobbyViewOptions

MigrationAdapter

PeerStats

PhaseOptions

RoomClock

RoomConfiguration

RoomData

RoomEvents

RoomMember

RoomPeer

RoomPhase