API Reference

insertCoin({ InitOptions })

Tell Playroom to start! Playroom Kit will then handle room creation, players joining and also let players pick their names, colors and avatars. Once host taps "Launch", the promise resolves. At this point you can start your game.

// Show Playroom UI, let it handle players joining etc and wait for host to tap "Launch"
await insertCoin();
 
// Start your game!

InitOptions is an object with the following properties:

getState(key: string): any

Returns the current value of the given key in the game state.

const winnerId = getState('winner');

setState(key: string, value: any, reliable: boolean = false): void

Sets the value of the given key in the game state. If reliable is true, the state is synced reliably to all players via Websockets. This is useful for game state that is critical to the game, like the winner.

If reliable is false, the state is synced via WebRTC, which is faster but less reliable. This is useful for game state that is not critical to the game, like the player's current position (you can always rely on next position update).

setState('winner', 'player1');

onPlayerJoin(callback)

Register a callback that will be called when a new player joins the room. The callback will be called with the player's PlayerState object.

If a new player joins after the game has started, the callback is called with all existing PlayerState objects, exclusively for the new player.

onPlayerJoin((player) => {
  console.log(`${player.id} joined!`);
});

isHost()

Returns true if the current player is the host.

if (isHost()) {
  // Do something only the host should do, like reading player input and setting game state
}

isStreamScreen()

Returns true if the current screen is the stream screen; a non-player screen that is shown when the game is in stream mode .

if (isStreamScreen()) {
  // Do something only the stream screen should do, like showing a countdown
}

myPlayer() or me()

Returns the current player's PlayerState object.

const player = myPlayer();
console.log(`Hello ${player.getProfile().name}!`);

waitForState(stateKey: string): Promise<any>

Returns a promise that resolves to the state value only when the game state has the given key set, to any truthy value.

In other words, it waits until a game state is set. This is useful for waiting for the host to set the winner, for example.

// Wait for the winner to be set
const winnerId = await waitForState('winner');
// Do something with the winner

PlayerState

A PlayerState object represents a player in the room. It has the following methods:

getProfile(): PlayerProfile

Returns the player's profile, which has the following properties:

The Color type is an object with the following properties:

getState(key: string): any

Returns the value of the given key in the player's state.

const score = player.getState('score');

setState(key: string, value: any)

Sets the value of the given key in the player's state.

player.setState('score', 10);

onQuit(callback)

Register a callback that will be called when the player quits the room.

player.onQuit(() => {
  console.log(`${player.id} quit!`);
});

Hooks for React

useMultiplayerState(key: string, defaultValue: any)

Use this hook to listen and update a value in the Playroom state. The value will be synced across all players.

The return value is an array with two values:

• state: any
• setState: (value: any, reliable?: boolean) => void

If reliable is true, the state is synced reliably to all players via Websockets. This is useful for game state that is critical to the game, like the winner.

If reliable is false, the state is synced via WebRTC, which is faster but less reliable. This is useful for game state that is not critical to the game, like the player's current position (you can always rely on next position update).

import { useMultiplayerState } from 'playroomkit'
...
const [count, setCount] = useMultiplayerState('count', 0);

usePlayersList(triggerOnPlayerStateChange?: boolean)

Use this hook to get a list of all players in the game. The list will be updated as players join and leave the game.

If triggerOnPlayerStateChange is true, the hook will trigger a re-render when a player's state changes. This is useful for times when you want to display a list of players and their state values like scores.

import { usePlayersList } from 'playroomkit'
...
const players = usePlayersList();

usePlayersState(key: string)

This will give you a list of all players and their state values for a given key. The list will be updated as players state change. This is useful for times when you want to display a list of players and their state values like scores.

The return value is an array of objects with the following shape:

• player: PlayerState
• state: any

import { usePlayersState } from 'playroomkit'
...
const players = usePlayersState('count'); 
// players = [{player: PlayerState, state: 10}, {player: PlayerState, state: 20}]

useIsHost()

This will be true if the current player is the host of the game. The host is the player who started the game. Another player can become host if the current host leaves the game, this value changes automatically to reflect that.

import { useIsHost } from 'playroomkit'
...
const isHost = useIsHost();