MaxDaten/GameState.ts

## README.md

      
    Raw
  

              README.md
            
          
    Buzzar backend-v2

The backend provides two APIs: a REST API and a WebSocket API. To perform any actions on the game, a client must first utilize the REST API to establish a new game or join an existing one. This will provide the necessary credentials. Once the credentials are obtained, the client can connect to the WebSocket API to execute game related commands and receive game state updates.
REST API

POST /api/game

Request the creation of a new game.
Request


Field
Type
Description
Required


title
string
Refers to the name of the game that will be shown in the game room.
No


description
string
Refers to the text that describes the game and will be displayed in the game room.
No


targetWords
string[]
A set of words that, when detected in a user's alias, will trigger the Demotivation Algorithm™ to discourage or dishearten that user.
No


Example

{
    "title": "Game Title",
    "description": "Game Description",
    "targetWords": ["MD", "hamster"]
}
Response


Field
Type
Description


gameCode
string
Refers to the code specific to the game that is utilized to identify and participate in the game.


adminKey
string
This key serves as a verification method to confirm that any actions taken are authorized by the game admin. It is important to keep this key confidential throughout the duration of the game.


´


Example

{
    "gameCode": "013237",
    "adminKey": "00222a64-f9b5-4818-942c-32334ec79960"
}
POST /api/game/join

Request to join a game.
Request


Field
Type
Description
Required


alias
string
The username that will be displayed in the game room.
Yes


gameCode
string
The code of the game to join.
Yes


Example

{
    "alias": "MDGoldhamster",
    "gameCode": "013237"
}
Response


Field
Type
Description
Required


userId
string
Refers to the user identifier that is essential for identifying the user in any subsequent actions.
Yes


userKey
string
This key serves as a verification method to confirm that any actions taken are authorized by the impersonated user. It is important to keep this key confidential throughout the duration of the game.
Yes


Example

{
    "userId": "847afa4e-0cf5-4402-9147-929cf43a9a93",
    "userKey": "5e6fdf74-f284-4fbc-9fa8-1553c04fec0c"
}
WebSocket API

Before you can interact with the WebSocket API, you must establish a connection with the WebSocket server. Once connected, you can send and receive messages to and from the server.
Message

All messages utilize JSON as their message format. The structure of the message is as follows:


Field
Type
Description
Required


destination
string
The destination of the message.
Yes


payload
string
The message payload should contain any of the supported commands.
Yes


Example

{
    "destination": "buzzar.game.enableUserInput",
    "payload": {
        "gameCode": "013237",
        "adminKey": "00222a64-f9b5-4818-942c-32334ec79960"
    }
}
Game Admin Commands

The server offers the following commands that a game admin can send.
EnableUserInput

Enabling user input refers to either unlocking the "buzz" button or permitting participants to submit answers.
Destination

buzzar.game.enableUserInput
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


DisableUserInput

Disabling user input refers to either locking the "buzz" button or preventing participants to submit answers.
Destination

buzzar.game.disableUserInput
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


ChangeQuestionType

Modify the current question type of a specific game to the designated question type.
Destination

buzzar.game.changeQuestionType
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


questionType
string
The question type to change to. Allowed values are (Buzz or Question).
Yes


RevealAnswers

Display the answers submitted by participants in a particular game.
Destination

buzzar.game.revealAnswers
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


HideAnswers

Hide the answers submitted by participants in a particular game.
Destination

buzzar.game.hideAnswers
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


IncreaseParticipantPoints

Increase the points of a participant in a particular game by 1.
Destination

buzzar.game.increaseParticipantPoints
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


userId
string
Id of the participant to increase points for.
Yes


DecreaseParticipantPoints

Decrease the points of a participant in a particular game by 1.
Destination

buzzar.game.decreaseParticipantPoints
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


userId
string
Id of the participant to decrease points for.
Yes


ChangeParticipantTags

Modify the tags of a participant in a particular game.
Destination

buzzar.game.changeParticipantTags
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


userId
string
Id of the participant to decrease points for.
Yes


tags
string[]
The tags to change to.
Yes


Game Participant Commands

The server offers the following commands that a game participant can send.
Buzz

Submit a buzz of a participant in a particular game.
Destination

buzzar.participant.buzz
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


userId
string
Id of the participant that buzzed.
Yes


Answer

Submit an answer of a participant in a particular game.
Destination

buzzar.participant.answer
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


userId
string
Id of the participant that submitted the answered.
Yes


text
string
The answer that was submitted.
Yes


Heartbeat

Signals that the participant in a particular game is still active.
Destination

buzzar.participant.heartbeat
Payload


Field
Type
Description
Required


gameCode
string
Code of the referred game.
Yes


adminKey
string
Admin Key of the game to verify that the action is authorized by the game admin.
Yes


userId
string
Id of the participant that sent the heartbeat.
Yes


Game Events

The server offers the following events that a client can subscribe to.
Update

After every game state modification, a game state update is disseminated. The game state changes whenever a command dispatched to the server has been successfully executed.
Destination

buzzar.game.update
Payload


Field
Type
Description


gameCode
string
Code of the referred game.


type
string
Current question type of the game. Possible values are (Buzz or Question).


hideAnswers
boolean
Whether or not answers should be visible.


inputEnabled
boolean
Whether or not user input should be enabled.


participants
Participant[]
List of participants of the game.


buzzes
Buzz[]
List of buzzes of the game.


answers
Answer[]
List of answers of the game.


Participant


Field
Type
Description


id
string
Id of the participant.


alias
string
Alias of the participant.


points
int
Points of the participant.


tags
string[]
Tags of the participant.


isConnected
boolean
Whether or not the participant is still active. Will be true if a heart beat was recieved during the max timeout interval - otherwise false.


Participant.Minimal


Field
Type
Description


id
string
Id of the participant.


alias
string
Alias of the participant.


Buzz


Field
Type
Description


user
Participant.Minimal
The participant that buzzed.


buzzedAt
string
Time when the participant hit the buzz button.


offsetMilliseconds
int
The time difference, in milliseconds, between the current buzz and the first buzz.


Answer


Field
Type
Description


user
Participant.Minimal
The participant that answered.


text
string
The answer the participant submitted.


Example

{
    "gameCode": "013237",
    "type": "Buzz",
    "hideAnswers": false,
    "inputEnabled": true,
    "participants": [
        {
            "id": "efe825e7-c719-471b-8d37-0d0863eb9478",
            "alias": "MDGoldhamster",
            "points": -5,
            "tags": ["🔨"],
            "isConnected": true
        },
        {
            "id": "68536286-9096-416d-a273-b7bd5c1d228b",
            "alias": "Matsuyama",
            "points": 99,
            "tags": ["🔨", "👑"],
            "isConnected": true
        }
    ],
    "buzzes": [
        {
            "user": {
                "id": "68536286-9096-416d-a273-b7bd5c1d228b",
                "alias": "Matsuyama"
            },
            "buzzedAt": "2020-05-03T20:00:00.000Z",
            "offsetMilliseconds": 0
        },
        {
            "user": {
                "id": "efe825e7-c719-471b-8d37-0d0863eb9478",
                "alias": "MDGoldhamster"
            },
            "buzzedAt": "2020-05-03T20:00:01.000Z",
            "offsetMilliseconds": 1000
        }
    ],
    "answers": [
        {
            "user": {
                "id": "68536286-9096-416d-a273-b7bd5c1d228b",
                "alias": "Matsuyama"
            },
            "text": "correct answer"
        },
        {
            "user": {
                "id": "efe825e7-c719-471b-8d37-0d0863eb9478",
                "alias": "MDGoldhamster"
            },
            "text": "bullshit answer"
        }
    ]
}

  
## GameState.ts
type GameType = 'Buzz' | 'Question';

export interface GameState {
	gameCode: string;
	type: GameType;
	hideAnswers: boolean;
	inputEnabled: boolean;
	participants: Participant[];
	buzzes: Buzz[];
	answers: Answer[];
}

interface Participant {
	id: string;
	alias: string;
	points: number;
	tags: string[];
	isConnected: boolean;
}

interface ParticipantMinimal {
	id: string;
	alias: string;
}

interface Buzz {
	user: ParticipantMinimal;
	buzzedAt: string;
	offsetMilliseconds: number;
}

interface Answer {
	user: ParticipantMinimal;
	text: string;
}
Field	Type	Description	Required
`title`	`string`	Refers to the name of the game that will be shown in the game room.	No
`description`	`string`	Refers to the text that describes the game and will be displayed in the game room.	No
`targetWords`	`string[]`	A set of words that, when detected in a user's alias, will trigger the `Demotivation Algorithm™` to discourage or dishearten that user.	No
Field	Type	Description
`gameCode`	`string`	Refers to the code specific to the game that is utilized to identify and participate in the game.
`adminKey`	`string`	This key serves as a verification method to confirm that any actions taken are authorized by the game admin. It is important to keep this key confidential throughout the duration of the game.
´
Field	Type	Description	Required
`alias`	`string`	The username that will be displayed in the game room.	Yes
`gameCode`	`string`	The code of the game to join.	Yes
Field	Type	Description	Required
`userId`	`string`	Refers to the user identifier that is essential for identifying the user in any subsequent actions.	Yes
`userKey`	`string`	This key serves as a verification method to confirm that any actions taken are authorized by the impersonated user. It is important to keep this key confidential throughout the duration of the game.	Yes
Field	Type	Description	Required
`destination`	`string`	The destination of the message.	Yes
`payload`	`string`	The message payload should contain any of the supported commands.	Yes
Field	Type	Description	Required
`gameCode`	`string`	Code of the referred game.	Yes
`adminKey`	`string`	Admin Key of the game to verify that the action is authorized by the game admin.	Yes
Field	Type	Description
`id`	`string`	Id of the participant.
`alias`	`string`	Alias of the participant.
`points`	`int`	Points of the participant.
`tags`	`string[]`	Tags of the participant.
`isConnected`	`boolean`	Whether or not the participant is still active. Will be `true` if a heart beat was recieved during the max timeout interval - otherwise `false`.
Field	Type	Description
`user`	`Participant.Minimal`	The participant that buzzed.
`buzzedAt`	`string`	Time when the participant hit the buzz button.
`offsetMilliseconds`	`int`	The time difference, in milliseconds, between the current buzz and the first buzz.
Field	Type	Description
`user`	`Participant.Minimal`	The participant that answered.
`text`	`string`	The answer the participant submitted.
	type GameType = 'Buzz' \| 'Question';

	export interface GameState {
	gameCode: string;
	type: GameType;
	hideAnswers: boolean;
	inputEnabled: boolean;
	participants: Participant[];
	buzzes: Buzz[];
	answers: Answer[];
	}

	interface Participant {
	id: string;
	alias: string;
	points: number;
	tags: string[];
	isConnected: boolean;
	}

	interface ParticipantMinimal {
	id: string;
	alias: string;
	}

	interface Buzz {
	user: ParticipantMinimal;
	buzzedAt: string;
	offsetMilliseconds: number;
	}

	interface Answer {
	user: ParticipantMinimal;
	text: string;
	}