#Interface: GameStateApi

The primary shared state for this game session, readable by every player and writable only by the party host. Put common game state here so reconnecting and later-joining players can receive the current value. While the session remains active, startup and recovery can restore its current synchronized value, but this is not permanent saved-game storage. Use Plot.realtime.channels for transient or high-frequency data.

#Extends

• TypedGameStateApi<SyncedObject>

#Methods

#as()

as<T>(): TypedGameStateApi<T>

Returns an unchecked typed view over the same game-state store.

The type is a compile-time assertion only. Plot still validates supported values and returns deeply immutable snapshots, but does not verify that current or future Game State matches T. Game State begins as {}, so use optional or defaulted fields, or initialize it before relying on required fields.

#Type Parameters

#T

T

The game-defined root Game State shape.

#Returns

TypedGameStateApi<T>

A typed view over the same synchronized Game State.

---

#get()

get(): SyncedObject

Returns the latest complete cached Game State. It may be stale during a recoverable disconnect.

#Returns

SyncedObject

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when Plot cannot guarantee consistent cached state.

#Inherited from

TypedGameStateApi.get

---

#onChanged()

onChanged(listener): Unsubscribe

Subscribes to every accepted game-state change visible through this view.

While this game copy stays synchronized, events arrive once and in order. Schema-backed views suppress changes that normalize to the same visible value. Initial and recovery snapshots do not create these events; use subscribe for complete state. Plot installs the new state before invoking the listener. Listener errors are reported to the browser and do not stop other listeners.

#Parameters

#listener

(event) => void

Receives complete values before and after each change.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.

#Inherited from

TypedGameStateApi.onChanged

---

#set()

set(value): Promise<void>

Replaces the complete game state.

This is an unconditional, last-write-wins replacement. Plot captures value when called and never recomputes it against newer state. Only the host can write Game State; a non-host call rejects with a not-host PlotOperationError. An unchanged replacement resolves without a new revision or change event.

#Parameters

#value

SyncedObject

The complete replacement Game State object.

#Returns

Promise<void>

#See

Error handling

#Inherited from

TypedGameStateApi.set

---

#subscribe()

subscribe(listener): Unsubscribe

Subscribes to complete game-state snapshots.

Registering before Plot.ready() does not start readiness. Its first callback runs after the complete connected snapshot is installed and before ready() resolves. Registering after readiness invokes the listener synchronously, before this method returns, with the current state and SnapshotReason.Initial.

Later callbacks follow accepted changes. Recovery produces one SnapshotReason.Resync snapshot rather than historical onChanged events. Schema-backed views suppress only ordinary changes that normalize to the same visible value. Plot installs state before invoking the listener; listener errors are reported to the browser and do not stop other listeners.

#Parameters

#listener

(state, info) => void

Receives each complete Game State snapshot.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.

#Inherited from

TypedGameStateApi.subscribe

---

#update()

update(updater): Promise<void>

Replaces game state using the latest cached value.

Only the host can write game state. The updater must be pure: after a definite revision conflict, Plot may invoke it again with the newly installed value and retry up to three times. Plot never retries after a timeout or ambiguous communication failure. An error thrown by updater rejects the returned promise unchanged.

#Parameters

#updater

(current) => SyncedObject

A pure function from the current immutable state to its complete replacement. Plot may call it again after a definite conflict.

#Returns

Promise<void>

#See

Error handling

#Inherited from

TypedGameStateApi.update

---

#withSchema()

withSchema<T>(schema): TypedGameStateApi<T>

Returns a schema-validated view over the same game-state store.

The schema is applied whenever this view reads, writes, runs an updater, or delivers a callback. Creating the view itself does not parse or write data. Game State begins as {}, so the parser must accept it or provide defaults. Plot revalidates parsed values so snapshots remain supported and deeply immutable.

#Type Parameters

#T

T

The validated game-defined root Game State shape.

#Parameters

#schema

SyncedObjectSchema<T>

A deterministic parser for the complete Game State object.

#Returns

TypedGameStateApi<T>

A schema-validated view over the same Game State.

#Throws

TypeError when schema does not provide a parse function.