#Interface: PartyApi

Cached party information and party subscriptions.

Plot updates the cached party before invoking a listener, so getters inside a callback already return the new snapshot. Listener errors are reported to the browser and do not stop other listeners or SDK progress.

#Methods

#get()

get(): PartySnapshot

Returns the latest complete party snapshot.

Call Plot.ready() during startup before ordinary reads. The party is already available inside a pre-registered initial snapshot callback. During a recoverable disconnect, this returns the most recently synchronized snapshot, which may be stale.

#Returns

PartySnapshot

#Throws

PlotNotReadyError when the complete ready state has not been installed.

#Throws

PlotOperationError when Plot cannot guarantee a consistent cached snapshot.

#See

Error handling

#getJoinUrl()

getJoinUrl(): Promise<string>

Returns the current party's player-facing invitation URL.

Share this URL when a game wants to provide its own invite button, QR code, or copy-to-clipboard action. It is the same current join URL shown in Plot's Party tab, such as https://plot.game/join/KM51NS. The value is an absolute HTTP(S) URL; production URLs use HTTPS, while HTTP is permitted only for loopback development.

Every call asks the trusted Plot host for the current authoritative value; the SDK does not derive it from party state or return a previously cached URL. The URL is a shareable invitation, not proof of player identity, authentication, party membership, or permission to perform an action. Keep authorization decisions in Plot rather than treating possession of this string as authority.

Calling this method does not start readiness. A call before Plot.ready() completes rejects with PlotNotReadyError; a call while the runtime is disconnected rejects with PlotOperationError. Other Plot failures, including a temporarily unavailable invite service or a response timeout, also reject with PlotError. Because this is a read-only request, code may try again after connectivity or service health recovers.

#Returns

Promise<string>

A promise for the current authoritative, shareable join URL.

#Example

Copy the current invitation URL from a game control.

inviteButton.addEventListener('click', async () => {
  const joinUrl = await Plot.party.getJoinUrl()
  await navigator.clipboard.writeText(joinUrl)
})

#Throws

PlotNotReadyError by promise rejection before the complete ready state is installed.

#Throws

PlotOperationError by promise rejection when the runtime is disconnected or Plot cannot return the URL.

#See

• Party and players
• Error handling

#getPlayer()

getPlayer(playerId): PartyPlayer | undefined

Returns a party player by stable ID, or undefined when it is unknown.

Valid IDs are integers from 0 through 1023.

#Parameters

#playerId

number

The player's stable session ID.

#Returns

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

#onPlayerAdded()

onPlayerAdded(listener): Unsubscribe

Subscribes to players being added for the first time.

A new player is delivered in joining state after their initial empty Player Data is installed. Rejoins use onPlayerChanged, not this callback. Initial and recovery snapshots do not create synthetic events.

#Parameters

#listener

(event) => void

Receives each newly allocated stable player slot.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.

#onPlayerChanged()

onPlayerChanged(listener): Unsubscribe

Subscribes to changes to an existing player.

This includes presence and profile changes, plus a non-host rejoin from left to joining. Initial and recovery snapshots do not create synthetic events. The complete Party—and a rejoining player's reset Player Data—are installed before the callback runs.

#Parameters

#listener

(event) => void

Receives the player before and after each change.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.

#subscribe()

subscribe(listener): Unsubscribe

Subscribes to complete party snapshots.

Registering before Plot.ready() does not start readiness. Its first callback runs with SnapshotReason.Initial after the complete connected snapshot is installed and before ready() resolves. Registering after readiness calls the listener synchronously, before this method returns, with the current snapshot and SnapshotReason.Initial. Later callbacks use SnapshotReason.Change or SnapshotReason.Resync.

#Parameters

#listener

(party, info) => void

Receives each complete immutable party snapshot.

#Returns

Unsubscribe

An idempotent function that stops this subscription.

#Throws

TypeError when listener is not a function.