#Interface: TypedPlayerDataApi<T>

Additional synchronized per-player session data with a game-defined root object type.

Every game copy can read every player's object; only the owner can write their own. Player Data is not private, so never store secrets in it. Common game state belongs in Plot.gameState. Transient or high-frequency data belongs on a realtime channel, not in this synchronized store. After readiness, getters return the latest cached immutable snapshot. They remain available during a recoverable disconnect, but may be stale until Plot recovers.

Calls to setSelf and updateSelf share one call-order queue with Game State 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

• PlayerDataApi

#Type Parameters

#T

T

#Properties

#host

readonly host: ImmutableSynced<T>

The latest cached object owned by the party host (player 0). It may be stale during a recoverable disconnect.

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when Plot cannot guarantee a consistent cached snapshot.

---

#self

readonly self: ImmutableSynced<T>

The latest cached object owned by the current player. It may be stale during a recoverable disconnect.

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when Plot cannot guarantee a consistent cached snapshot.

#Methods

#get()

get(playerId): ImmutableSynced<T> | undefined

Returns the latest cached object for a player, or undefined when no party player has that valid ID. A cached object may be stale during a recoverable disconnect.

#Parameters

#playerId

number

The player's stable session ID.

#Returns

ImmutableSynced<T> | undefined

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when Plot cannot guarantee a consistent cached snapshot.

#Throws

TypeError when playerId is invalid.

---

#onChanged()

onChanged(listener): Unsubscribe

Subscribes to accepted Player Data writes 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 state, recovery snapshots, and Player Data installed or reset by a player join or rejoin do not create these events; use subscribe for complete state. Plot installs the new value 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 write.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.

---

#setSelf()

setSelf(value): Promise<void>

Replaces the complete object owned by the current player.

This is an unconditional replacement. Plot captures value when called and never recomputes it against newer state. An unchanged replacement resolves successfully without creating a revision or emitting an onChanged event.

#Parameters

#value

T

The complete replacement for the current player's object.

#Returns

Promise<void>

#See

Error handling

---

#subscribe()

subscribe(listener): Unsubscribe

Subscribes to complete player-data 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 snapshot and SnapshotReason.Initial.

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

#Parameters

#listener

(snapshot, info) => void

Receives each complete Player Data snapshot.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.

---

#updateSelf()

updateSelf(updater): Promise<void>

Replaces this player's object using its latest cached value.

The updater must be pure. If another accepted write wins first, 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 object to its complete replacement. Plot may call it again after a definite conflict.

#Returns

Promise<void>

#See

Error handling