#Interface: Plot

The shared top-level Plot API exposed to a game.

#Properties

#connection

readonly connection: ConnectionApi

Optional diagnostics for Plot's realtime connection.

#gameState

readonly gameState: GameStateApi

Shared session state that every player can read and only the host can write. Use realtime channels for transient or high-frequency values.

#party

readonly party: PartyApi

The latest party snapshot and party subscriptions.

#playerData

readonly playerData: PlayerDataApi

Additional session state owned separately by each player.

Every game copy can read every player's data, while only the owner can write their own object. It is not private, so never store secrets here. Use it only when a session fact belongs to one player. Common state belongs in gameState; transient or high-frequency values belong in realtime channels.

#ready

readonly ready: (options?) => Promise<void>

Signals that this game copy is prepared to participate, then waits until the Plot SDK is fully ready.

Importing the SDK does not contact Plot or start readiness. Before calling this method, create state views and channels, register a lifecycle listener for startup and recovery, and register channel listeners for early messages. Calling other SDK APIs does not start readiness implicitly.

Call this after local setup that must finish before this player can receive game traffic. The SDK does not wait for your framework to render or for assets to load unless your code waits for them first.

When the promise resolves:

• Plot.party contains the complete party and party.self is connected;
• Game State and every player's Player Data are installed;
• the synchronized game clock is ready; and
• reads, state writes, and channel sends are enabled.

After all of that state is available, existing Party, Player Data, and Game State subscriptions receive their SnapshotReason.Initial snapshots. Then onLifecycleChange reports connected, before retained channel messages and before the promise resolves. Other game copies may see this player as joining before the final connected state; ready() does not add or renumber the player.

Repeated calls are safe and share one attempt. A call without options reuses settings already in use; a supplied parentOrigin must match. If a startup attempt fails with connection-failed, connection-timeout, readiness-timeout, or communication-failed, a later explicit call can start a fresh attempt.

A temporary realtime interruption after readiness is recovered automatically and does not require another call. If recovery becomes terminal, this promise stays resolved and affected APIs report the retained error; reload or exit instead of calling ready() again. A reloaded game iframe is a new page and calls ready() again as part of normal startup.

#Parameters

#options?

PlotReadyOptions

Optional Plot-provided preview or test settings. Normal games omit this argument.

#Returns

Promise<void>

A promise that rejects with PlotError when Plot cannot start the game, and with TypeError when options are invalid.

#Example

Register startup listeners before signaling readiness.

const gameState = Plot.gameState.as<{ phase?: string }>()
const render = () => renderPhase(gameState.get().phase ?? 'lobby')
Plot.onLifecycleChange((status) => {
  if (status === 'connected') render()
})
gameState.onChanged(render)
await Plot.ready()

#See

• Getting started
• Error handling

#realtime

readonly realtime: RealtimeApi

Transient realtime messaging between players.

#showSystemUi

readonly showSystemUi: (target) => Promise<void>

Asks the trusted Plot host to show one of its own interface surfaces.

Call this from the player gesture that should open the interface. The promise resolves when Plot accepts the request and makes that surface current; it does not wait for the player to close it or finish an action. The game never receives access to the parent document or the underlying account and party services.

Calling this method does not start readiness. A request made before Plot.ready() completes rejects with PlotNotReadyError. A request made while this game copy is disconnected rejects with PlotOperationError.

#Parameters

#target

SystemUi

The Plot-owned interface surface to show.

#Returns

Promise<void>

A promise that resolves after Plot accepts the request.

#Example

Open Plot's party controls from a game button.

import Plot, { SystemUi } from '@plot.game/sdk'

partyButton.addEventListener('click', () => {
  void Plot.showSystemUi(SystemUi.Party)
})

#Throws

TypeError by promise rejection when target is invalid.

#Throws

PlotError by promise rejection when Plot cannot show the requested interface.

#See

• Party and players
• Error handling

#time

readonly time: TimeApi

Plot's synchronized clock for this game session.

#toolkit

readonly toolkit: ToolkitApi

Local game helpers built on Plot's public APIs, including synchronized audio.

#version

readonly version: string

The exact SDK package version loaded by this game.

#Methods

#onLifecycleChange()

onLifecycleChange(listener): Unsubscribe

Observes this game copy becoming connected or disconnected.

Register before ready to use one callback for startup and recovery. The first connected callback runs after Party, Game State, every Player Data record, and the clock are installed, before retained channel messages and before ready resolves. Read the existing getters inside that callback. Ordinary state changes and other players' presence changes do not fire it.

Registration does not start readiness or report a pre-ready disconnected state. After readiness, registration synchronously reports the current lifecycle state. Listener errors are isolated; returned promises are not awaited, so perform synchronous setup before returning.

#Parameters

#listener

(status) => void

Receives connected after complete installation, or disconnected.

#Returns

Unsubscribe

An idempotent unsubscribe function.

#Throws

TypeError when listener is not a function.