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 = true): 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 and properties:

id: string

The player's unique ID.

console.log(`Player ID: ${player.id}`);

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, reliable: boolean = false)

Sets the value of the given key in the player's 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).

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!`);
});

Joystick Controller

Joystick(state: PlayerState, options: JoystickOptions)

A component that renders a joystick controller. The joystick can be used to control the player's position in the game.

import { Joystick, myPlayer } from 'playroomkit';
 
new Joystick(myPlayer(), {
  type: "dpad"
})

JoystickOptions is an object with the following properties:

ButtonOptions is an object with the following properties:

ZoneOptions let's you define zones on Joystick that are triggered when player drags Joystick in that zone. This behaves same as buttons above, isPressed method can be used to detect if a zone button is active or not. ZoneOptions is an object with the following properties:

isPressed(id: string): boolean

Returns true if the button with the given ID is pressed.

if (joystick.isPressed('jump')) {
  // Jump!
}

isJoystickPressed(): boolean

Returns true if the joystick is pressed.

if (joystick.isJoystickPressed()) {
  // Do something?
}

angle(): float

Returns the angle of the joystick, in radians.

const angle = joystick.angle();

dpad(): { x: string, y: string }

Returns the direction of the joystick, as a string. The string can be one of the following:

• up
• down
• left
• right

destroy(): void

Destroy and remove the Joystick and its UI.

Hooks for React

See the React API here.

Unity (C#) API

See the Unity API here.