Serververbindung

[[TOC]]

Setup

1. pip install -r requirements.txt
2. python3 manage.py runserver
3. open http://127.0.0.1:8000/ in your Browser

To connect to our heroku server as a client:

let socket = io.connect('https://ab-backend.herokuapp.com:443')

Lobby and Hosting a Game

Create Game

To create a game, emit the create_game event with an empty string message.

Payload

The payload has to be an empty string and cannot be omitted.

Return Value

Returns the game token of the created game.

Join Game

When a client wants to join a game in lobby state, he can emit a join_game event. This event is also useful to rejoin a game after disconnect. When a player wants to rejoin, he has to use the same name.

Payload

{
    'token': <game-token>, // the token of the game to join
    'name': <player-name> // the player name as string 
}

Return Value

{
    'success': true or false, // Whether this login succeeded
    'reason': <reason>, // The reason for failure (null for success)
}

The reason is one of the following:

• invalid_message: This reason means there is an implementation error regarding the payload
• empty_name: You have to pick a non empty name to join
• game_not_found: There is no game with the given token
• game_full: The game already has 8 players
• name_not_found: There was a running game with the given token (so assuming rejoin), but no disconnected player with the given name exists
• name_duplication: There is already a player using this name

Player Infos

This event is emitted by the server, when a new player connects to a game in lobby state or when a player of this game disconnects.

Payload

[
    {
        'name': <player-name> // the name of the player as string
        'player_id': <player-id> // the player id created by the server as integer
    }
]

Start Game

To start a game in lobby state, emit the start_game event.

Payload

A single string containing the game token or a dictionary:

<token>
or
{
    'token': <token>, // The token of the game (required)
    'startposition': <index>, // The index of the team start position (default: 4)
    'test_choices': [OCCASIONS], // a list of possible test occasions. Max. 2. Possible occasions: ['found_clue', 'move_forwards', 'simplify_dicing', 'skip_player', 'hinder_dicing'](default: all)
    'enable_minigames': true/false, // whether to enable minigames or not (default: false)
}

Init Client

Every player receives an init event, when the host starts the game. You also receive an init event, when rejoining.

Payload

{
    'player_id': <player-id>, // The player id of the receiving client as integer
    'is_mole': true / false, // whether you are the mole or not
    'clues': [ // a list of clues, that are initially given for this player
        { /* TODO */ }
    ],
    'rejoin': true / false // whether this init is send, because of a rejoin or normal join
}

Client Information

Move

Whenever the team position changes (because of dicing, occasions or minigames), all clients receive a move event.

Payload

<field-index> // an integer specifying the position of the team

Players Turn

When a player ends his turn, all clients receive a players_turn event, that specifies the next player to move.

Payload

{
    'player_id': <player-id>, // the id of the next player to move
    'movement_modifier': 'normal', 'hinder' or 'simplify' // whether the next dicing is hindered or simplified
}

Moriarty Move

Whenever Moriarty moves all clients receive a moriarty_move event, specifying the position of Moriarty.

Payload

<moriarty-position> // a single integer, specifying the position of moriarty

Subscribing Events (TODO)

/*
  data: {
      'player_id': <player_id>,
      'choices': [
          {'type': <occasion_type>},
          {'type': 'move_forwards', 'value': 3}
      ]
  }
  where player id is the player that has to move and 'choices' is a list
  of options the player has to choose from.
*/
socket.on('occasion', data => console.log('player that has to choose occasions:', data['player_id']));

/* data: {'successful_validation': <Bool>, 'validation_status': <status>, 'player_id': <ID>, 'clues': <List of clues>}
   'validation_status': 'new_validation' (+), 'different_clue_types' (-), 'not_in_inventory' (-), 'already_verified' (-)
*/
socket.on('validation_result', data => console.log(data));

/* data: {'from': <Integer>, 'evidence': <evidence>}
   'from' is the player id from which you get the evidence (id=-1 is 'Scotland Yard')
   'evidence' contains the complete object
   TODO: Rename evidence to clue, Accept success value
*/
socket.on('receive_evidence', data => console.log(data));

/* data: {'player_id': <ID>, 'move_name': <move_name>}
   'move_name': "search-clue", "share-clue"
*/
socket.on('secret_move', data => console.log(data));

/* data: {'winner': <"Mole"/"Team">, 'reason': <reason>}
   'reason': "moriarty_caught_team", "hindered_team", "destroyed_enough_proofs", "validated_enough_proofs"
*/
socket.on('gameover', data => console.log(data));

Emitting Events (TODO)

// You choosed the move_backwards 5 fields event
socket.emit('player_occasion_choice', {'type': 'move_backwards', 'value': 5});

/* Valid types are:
 * - 'found_evidence'
 * - 'move_forwards'
 * - 'simplify_dicing'
 * - 'skip_player'
 * - 'hinder_dicing'
 * 
 * In case of move_forwards/move_backwards there should also be a "value" field containing the number of fields.
 * "value" should always be positive.
 * In case of skip player there should also be a "name" field, containing the name of the player. TODO: change to id
 * In case of found evidence there should also be a "success" field, containing a Bool. TODO: Rename evidence to clue
 */

Pantomime

Host Pantomime

The player moving to/over a shortcut field receives a host_pantomime event, while all the other players receive a guess_pantomime event (with start == false). The host also receives a guess_pantomime event.

Payload

{
    'solution_word': 'small_path', // The word to be pantomimed as string
    'words': ['grotty_canal', 'bright_way', 'cold_street', 'small_path'], // All words from which is guessed (maybe ignored)
    'category': 'escape_route' // The category of the words (maybe ignored)
}

Guess Pantomime

When a player moves over/to a shortcut field, all the other players receive a guess_pantomime event (with start == false). If the hosting player starts the game, all other clients receive another guess_pantomime event (with start == true). One player might be ignored. This player will receive the field ignored == true. If start == false ignored will always be false.

Payload

{
    'words': ['grotty_canal', 'bright_way', 'cold_street', 'small_path'], // All words from which is guessed
    'category': 'escape_route', // The category of the words (maybe ignored)
    'start': false / true, // true, if the game starts, false before the hosting player starts the game
    'ignored': false / true, // whether your choice will be ignored or not
}

Pantomime Start

After some time the hosting player can start the pantomime game by emitting an pantomime_start event. This will lead to an guess_pantomime with start == true event for all other clients.

Payload The hosting player can choose one player, that is ignored during voting. You can set ignored_player to null, -1 or omit completely to include all players.

{
    'ignored_player': 0 // The player id that will be ignored (optional) 
}

Pantomime Choice

If one player thinks he knows the word he can emit a pantomime_choice event.

Payload

{
    'guess': 'grotty_canal' // The word the player guessed
}

Additional pantomime_choice events will overwrite older events. When every player has guessed, the round ends. The round also ends after one minute.

Pantomime Result

When the round ends every player will receive an pantomime_result event.

{
    'success': true / false, // whether all players guessed correctly
    'player_results': [ // a list of results for each player. The hosting player and disconnected players are omitted
        {
            'player_id': <player-id>, // The id of the player
            'success': true / false, // Whether this player guessed correctly
            'guess': 'grotty_canal', // The guess of the player. null if no guess is given.
            'ignored': true / false, // whether this player was ignored (ignored == true implies success == true and guess == null)
        }
    ],
    'solution_word': 'small_path', // The solution word
}