BZZR API - v2

bzzr_api_v2.md

BZZR API v2

This documentation makes a distinction between a "command" and an "event."

• Commands are sent by the client to the server. e.g. arming the buzzer, buzzing in
• Events are sent by the server to the client. They are sometimes sent in response to a command, or because the app's state has changed. e.g. the buzzer is armed, a player has joined

Scheduled Downtime

For its server's health, BZZR is scheduled to restart daily at 10:00 UTC. The downtime experienced should be no more than a few seconds, but any games in progress at that time will be destroyed. When developing a game that makes use of the BZZR platform, it is advised to develop a method change rooms without losing your game state in case of server failure.

Eventually I'll add a database so rooms can persist after restarts. If you'd like to be notified of this, let me know on discord at dev#8885.

Lobby Commands

The following commands can be called immediately after making a websocket connection. These commands allow users to create and join rooms.

play

Join the game as a player.

Parameters

Name	Type	Description	Required
roomCode	string	Existing room code to join as a player	yes
name	string	The player's name	yes

Example

send("play", { roomCode: "BASH", name: "toadboy123" }) 

Responses

Event	Condition
join room	successfully join a room as a player
error	failed to join a room (e.g. room does not exist)

host new

Host a new game.

Parameters

None

Example

send("host new", {})

Responses

Event	Condition
join room	successfully created a new room
error	failed to create a room

host existing

Host an existing game. The user sending this command must already be the host of the room.

Parameters

Name	Type	Description	Required
roomCode	string	Existing room code to join as host	yes

Example

send("host existing", { roomCode: "BZZR" })

Responses

Event	Condition
join room	successfully continued hosting an existing room
error	failed to join a room (invalid room code, tried to host a room that is not owned by this user)

Host Commands

The following commands can be called after joining a room as host, using host new or host existing in the lobby. They provide hosts control of the buzzer and players.

arm buzzer

Arms the buzzer, allowing players to buzz.

Parameters

None

Example

send("arm buzzer", {})

Responses

Event	Condition
buzzer	buzzer was successfully armed

disarm buzzer

Disarms the buzzer, resetting players' buzzes. Players that are locked out will remain locked out.

Parameters

None

Example

send("disarm buzzer", {})

Responses

Event	Condition
buzzer	buzzer was successfully disarmed

lock players

Locks players, preventing them from buzzing in.

Parameters

Name	Type	Description	Required
userIds	string[]	Array of user IDs to lockout	yes

Example

send("lock players", { userIds: ["123e4567-e89b-12d3-a456-426614174000"] }) 

Responses

Event	Condition
buzzer	buzzer was successfully disarmed

unlock players

Unlocks players, allowing them to buzz in when the buzzer is armed. Pass the optional parameter everyone: true to unlock all players.

Parameters

Name	Type	Description	Required	Default
userIds	string[]	Array of user IDs to lockout	yes
everyone	boolean	Unlock everyone if true	no	false

Example

send("unlock players", { userIds: ["123e4567-e89b-12d3-a456-426614174000"] }) 
send("unlock players", { userIds: [], everyone: true })

Responses

Event	Condition
players	player was successfully unlocked

kick player

Remove a player from the game. This does not ban them from re-entry.

Parameters

Name	Type	Description	Required
userId	string	User ID of the player to kick	yes

Example

send("kick player", { userId: "123e4567-e89b-12d3-a456-426614174000" }) 

Responses

Event	Condition
players	player was successfully kicked

edit player

Update a player's details.

Parameters

Name	Type	Description	Required
userId	string	User ID of the player to update	yes
name	string	Player name	yes
color	string	Player color - used as a visual aid or to represent team	no

Color Options

• "red"
• "orange"
• "yellow"
• "olive"
• "green"
• "teal"
• "blue"
• "violet"
• "purple"
• "pink"
• "brown"
• "grey"

Example

send(
  "edit player",
  {
    userId: "123e4567-e89b-12d3-a456-426614174000",
    name: "toadboy456",
    color: "teal"
  }
) 

Responses

Event	Condition
players	player was successfully updated

Player Commands

The player API is currently unstable. Players should use the UI at bzzr.dev to play the game.

Events

These are events that the server may send to clients.

join room

The server will send this event to a client who joins a room successfully from the lobby, whether as a host or a player.

Data

Name	Type	Description
roomCode	string	The joined room
userId	string	The client's user ID

Example

{
  event: "join room",
  payload: {
    roomCode: "BZZR",
    userId: "123e4567-e89b-12d3-a456-426614174000"
  }
}

buzzer

This event contains an object representing the current state of the buzzer. It is sent whenever the buzzer's state changes.

Buzzer Data

Name	Type	Description
status	`"armed"	"disarmed"`
buzzes	[userId: string]: { speed: number }	A hashmap of keys and values. Each key is a user ID. Each object is that player's buzz. Speed is the calculated buzz-in speed in milliseconds.
lockouts	string[]	An array of user IDs. User IDs in this array are locked out.
arm	boolean	If true, the buzzer was just armed.

Example

{
  event: "buzzer",
  payload: {
    status: "armed",
    buzzes: [
	  {
	    "123e4567-e89b-12d3-a456-426614174000": {
          speed: 1000
        }
	  }
    ],
    lockouts: []
  }
}

players

This event contains the current state of the players. It is sent whenever the players state changes. (e.g. a player joins, leaves, or is modified)

Data

Name	Type	Description
players	Player[]	Array of Player objects.

Player Object Type

Name	Type	Description
userId	string	The player's ID.
name	string	The player's name.
color	string	The player's color.
connectionStatus	"connected"	The player's connection status. Currently, this is always "connected"

Example

{
  event: "players",
  payload: {
    players: [
      { userId: "1111-11-11-1111", name: "ape", color: "yellow", cx: true },
      { userId: "2222-22-22-2222", name: "clive", color: "red", cx: false },
      { userId: "3333-33-33-3333", name: "ash", color: "green", cx: true }
    ]
  }
}

error

This event is sent to a client when an error occurs.

Data

Name	Type	Description
message	string	The error message.

Example

{
  event: "error",
  payload: {
    message: "You are not the host of this room!
  }
}