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
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.
The following commands can be called immediately after making a websocket connection. These commands allow users to create and join rooms.
Join the game as a player.
Name | Type | Description | Required |
---|---|---|---|
roomCode | string | Existing room code to join as a player | yes |
name | string | The player's name | yes |
send("play", { roomCode: "BASH", name: "toadboy123" })
Event | Condition |
---|---|
join room | successfully join a room as a player |
error | failed to join a room (e.g. room does not exist) |
Host a new game.
None
send("host new", {})
Event | Condition |
---|---|
join room | successfully created a new room |
error | failed to create a room |
Host an existing game. The user sending this command must already be the host of the room.
Name | Type | Description | Required |
---|---|---|---|
roomCode | string | Existing room code to join as host | yes |
send("host existing", { roomCode: "BZZR" })
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) |
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.
Arms the buzzer, allowing players to buzz.
None
send("arm buzzer", {})
Event | Condition |
---|---|
buzzer | buzzer was successfully armed |
Disarms the buzzer, resetting players' buzzes. Players that are locked out will remain locked out.
None
send("disarm buzzer", {})
Event | Condition |
---|---|
buzzer | buzzer was successfully disarmed |
Locks players, preventing them from buzzing in.
Name | Type | Description | Required |
---|---|---|---|
userIds | string[] | Array of user IDs to lockout | yes |
send("lock players", { userIds: ["123e4567-e89b-12d3-a456-426614174000"] })
Event | Condition |
---|---|
buzzer | buzzer was successfully disarmed |
Unlocks players, allowing them to buzz in when the buzzer is armed. Pass the optional parameter everyone: true
to unlock all players.
Name | Type | Description | Required | Default |
---|---|---|---|---|
userIds | string[] | Array of user IDs to lockout | yes | |
everyone | boolean | Unlock everyone if true | no | false |
send("unlock players", { userIds: ["123e4567-e89b-12d3-a456-426614174000"] })
send("unlock players", { userIds: [], everyone: true })
Event | Condition |
---|---|
players | player was successfully unlocked |
Remove a player from the game. This does not ban them from re-entry.
Name | Type | Description | Required |
---|---|---|---|
userId | string | User ID of the player to kick | yes |
send("kick player", { userId: "123e4567-e89b-12d3-a456-426614174000" })
Event | Condition |
---|---|
players | player was successfully kicked |
Update a player's details.
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 |
- "red"
- "orange"
- "yellow"
- "olive"
- "green"
- "teal"
- "blue"
- "violet"
- "purple"
- "pink"
- "brown"
- "grey"
send(
"edit player",
{
userId: "123e4567-e89b-12d3-a456-426614174000",
name: "toadboy456",
color: "teal"
}
)
Event | Condition |
---|---|
players | player was successfully updated |
The player API is currently unstable. Players should use the UI at bzzr.dev to play the game.
These are events that the server may send to clients.
The server will send this event to a client who joins a room successfully from the lobby, whether as a host or a player.
Name | Type | Description |
---|---|---|
roomCode | string | The joined room |
userId | string | The client's user ID |
{
event: "join room",
payload: {
roomCode: "BZZR",
userId: "123e4567-e89b-12d3-a456-426614174000"
}
}
This event contains an object representing the current state of the buzzer. It is sent whenever the buzzer's state changes.
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. |
{
event: "buzzer",
payload: {
status: "armed",
buzzes: [
{
"123e4567-e89b-12d3-a456-426614174000": {
speed: 1000
}
}
],
lockouts: []
}
}
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)
Name | Type | Description |
---|---|---|
players | Player[] | Array of Player objects. |
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" |
{
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 }
]
}
}
This event is sent to a client when an error occurs.
Name | Type | Description |
---|---|---|
message | string | The error message. |
{
event: "error",
payload: {
message: "You are not the host of this room!
}
}