Interface: PlayerDataApi
Synchronized session data owned separately by each party player. Use this
only for extra state specific to one player; put common state in
Plot.gameState, and send transient or high-frequency data through
Plot.realtime.channels. 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. Values belong to the current game session; do not use
this store as permanent account or saved-progress storage.
Extends
Properties
host
readonlyhost:SyncedObject
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.
Inherited from
self
readonlyself:SyncedObject
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.
Inherited from
Methods
as()
as<
T>():TypedPlayerDataApi<T>
Returns an unchecked typed view over the same player-data store.
The type is a compile-time assertion only. Plot still validates supported
synchronized values and returns deeply immutable snapshots, but it
does not verify that existing or future objects match T. Every newly
known player starts with an empty object, so use optional/defaulted fields
or initialize the object before relying on required fields.
Type Parameters
T
T
The game-defined root object shape for every player.
Returns
A typed view over the same synchronized Player Data.
get()
get(
playerId):SyncedObject|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
SyncedObject | 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.
Inherited from
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
An idempotent function that stops this subscription.
Throws
TypeError when listener is not a function.
Inherited from
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
The complete replacement for the current player's object.
Returns
Promise<void>
See
Inherited from
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
An idempotent function that stops this subscription.
Throws
TypeError when listener is not a function.
Inherited from
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) => SyncedObject
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
Inherited from
withSchema()
withSchema<
T>(schema):TypedPlayerDataApi<T>
Returns a schema-validated view over the same player-data 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.
Every new or rejoining player begins with {}, 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 object shape.
Parameters
schema
A deterministic parser for one player's complete object.
Returns
A schema-validated view over the same Player Data.
Throws
TypeError when schema does not provide a parse function.