#Interface: TypedGameStateApi<T>

The primary synchronized shared-state API for the current game session, with a game-defined root object type. Every game copy can read it, and only the host can write it. Use realtime channels instead for transient or high-frequency data. After readiness, get returns the latest cached immutable snapshot. It remains available during a recoverable disconnect, but may be stale until Plot recovers.

Calls to set and update share one call-order queue with Player Data writes from this page. Plot may briefly hold them during automatic recovery. When a write resolves, its accepted value is already installed for synchronous reads and callbacks. An operation-timeout has an unknown outcome, so reconcile current state before deciding whether to try again. At most 32 writes may be pending; an additional write rejects with too-many-pending-writes before submission.

A valid write made before Plot installs the complete ready state rejects with PlotNotReadyError and does not start Plot.ready(). Other Plot failures reject with PlotError; local value validation and the selected schema may reject with their own errors.

#Extended by

• GameStateApi

#Type Parameters

#T

T

#Methods

#get()

get(): ImmutableSynced<T>

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

#Returns

ImmutableSynced<T>

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when Plot cannot guarantee consistent cached state.

---

#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.

---

#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

T

The complete replacement Game State object.

#Returns

Promise<void>

#See

Error handling

---

#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.

---

#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) => T

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