mazedrivers-api-documentation

Mazedrivers API documentation

VideumCodeup Mazedrivers

Server

Go to mazedrivers.videumcodeup.se and enter 46.101.96.185 as host.

Connect your WebSocket client to 46.101.96.185:8001.

API

This is the API for the server-side version of Bomberman. Written by Andreas Lundahl and Kevin Sjöberg and Albert Arvidsson

Action commands

Commands are sent as JSON over WebSockets.

You can for example connect to the websocket via

var ws = new WebSocket(`ws://${host}:${port}`)

Then you can send a message to it like this:

ws.onopen = function () {
  ws.send(JSON.stringify({
    type: "JOIN_REQUEST",
    payload: { nickname: "??" }
  }))
}

And listen for all responses like this:

ws.onmessage = function (event) {
  console.log(event.data)
}

All responses are of the form { type: 'SOME_ACTION', payload: 'some data' } or { type: 'SOME_ERROR', error: true, payload: 'ERROR_DESCRIPTION' } and could be handled something like this:

const action = JSON.parse(event.data)
switch (action.type) {
  case 'JOIN_SUCCESS':
    localStorage.setItem('mazedrivers-token', action.payload.token)
    break
  default:
    break
}

You start out in spectator-mode when you connect to the socket.

JOIN_REQUEST

Request to join the game with your car. You must specify your nickname.

{"type": "JOIN_REQUEST", "payload": {"nickname": "Your name"}}

Error responses:

{"type": "JOIN_FAILURE", "payload": "JOIN_NICKNAME_MISSING"}
{"type": "JOIN_FAILURE", "payload": "JOIN_NICKNAME_INVALID"}
{"type": "JOIN_FAILURE", "payload": "JOIN_NICKNAME_TOO_SHORT"}
{"type": "JOIN_FAILURE", "payload": "JOIN_NICKNAME_TOO_LONG"}
{"type": "JOIN_FAILURE", "payload": "JOIN_NICKNAME_ALREADY_TAKEN"}

Success response includes a token that should be used if you need to reconnect to the websocket server after having reloaded the browser or lost connection.

{"type": "JOIN_SUCCESS", "payload": {"token": "6487d24e-02e4-41ce-8371-db56742d3b6a"}}

REJOIN_REQUEST

Request to rejoin the game with the token you got when joining.

{"type": "REJOIN_REQUEST", "payload": {
   "token": "6487d24e-02e4-41ce-8371-db56742d3b6a"}}

Error responses:

{"type": "REJOIN_FAILURE", "payload": "REJOIN_TOKEN_MISSING"}
{"type": "REJOIN_FAILURE", "payload": "REJOIN_TOKEN_INVALID"}
{"type": "REJOIN_FAILURE", "payload": "REJOIN_TOKEN_WRONG"}

Success response:

{"type": "REJOIN_REQUEST", "payload": {
   "token": "6487d24e-02e4-41ce-8371-db56742d3b6a",
   "nickname": "Your name",
   "gameId": "cee6b387-80ac-468b-9093-8d691c4385ab"}}

DRIVE

Start driving in a direction EAST, WEST, NORTH or SOUTH.

{"type": "DRIVE_REQUEST", "payload": "NORTH"}

Error responses:

{"type": "DRIVE_FAILURE", "payload": "DRIVE_DIRECTION_MISSING"}
{"type": "DRIVE_FAILURE", "payload": "DRIVE_DIRECTION_INVALID"}
{"type": "DRIVE_FAILURE", "payload": "DRIVE_JOIN_GAME_FIRST"}

Success response:

{"type": "DRIVE_SUCCESS"}

BREAK

Push the breakes to stop the car! (This action does not need a payload)

{"type": "BREAK_REQUEST"}

State updates

After joining the game, a message like this will be sent to you containing all of the current state. This is mainly used for rendering the game.

{
  "type": "STATE",
  "payload": {
    "players": {
      "andreas": { "x": 10, "y": 5, "direction": "WEST", "speed": 0 },
      "kevin": { "x": 7, "y": 3, "direction": "SOUTH", "speed": 1 }
    },
    "maze": [
      ["corner", "wall", "corner", "wall", "..."],
      ["wall", "room", "opening", "room", "..."],
      ["..."]
    ]
  }
}

Incremental updates as double-dimension array

After that you'll only get incremental updates looking like this whenever something changes. This is mainly used for rendering the game.

// collection, scope, key, value
[
  ["players", "albert", "direction", "NORTH"],
  ["maze", 4, 7, "NORTH"],
  ["players", "kevin", "x", 10],
  ["players", "kevin", "y", 7]
]

(There is no payload wrapping in this particular case)

LIST_REQUEST

The spectator client uses this to show a list of clients and games.

{"type": "LIST_REQUEST"}

FOLLOW_REQUEST

The spectator client uses this to follow a specific player in each game they participate in regardless if the player has joined a game yet or not).

{"type": "FOLLOW_REQUEST", "payload": {"nickname": "kevin"}}

Error responses:

{"type": "FOLLOW_FAILURE", "payload": "FOLLOW_NICKNAME_MISSING"}
{"type": "FOLLOW_FAILURE", "payload": "FOLLOW_NICKNAME_INVALID"}
{"type": "FOLLOW_FAILURE", "payload": "FOLLOW_NICKNAME_WRONG"}

Success response:

{"type": "FOLLOW_SUCCESS"}

UNFOLLOW_REQUEST

The spectator client uses this to show the game list again instead of following a player.

{"type": "UNFOLLOW_REQUEST", "payload": {"nickname": "kevin"}}

Error responses:

{"type": "UNFOLLOW_FAILURE", "payload": "UNFOLLOW_NICKNAME_MISSING"}
{"type": "UNFOLLOW_FAILURE", "payload": "UNFOLLOW_NICKNAME_INVALID"}
{"type": "UNFOLLOW_FAILURE", "payload": "UNFOLLOW_NICKNAME_WRONG"}

Success response:

{"type": "UNFOLLOW_SUCCESS"}