Codewords Server

This is the server side of the Codewords game. It manages game state and handles turn logic, however it does not have a built-in front-end. You will also need the Codewords UI available within this organization.

Requirements

Ruby 2.6.3
Rails 5.2.3
This server

Setup

Need to set up a Ruby environment? MacOS instructions within.

Note: Depending on your existing setup, you may be able to skip one or more of the steps below. If you're not sure whether you have something installed or not, go ahead and run the respective command, and the command-line tools we're using will let you know that you're good to go. First, we'll install a Ruby environment manager. rbenv gives you very straightforward tools to manage which version of Ruby you use for a particular project.

brew install rbenv
rbenv init
- This will instruct you to add content to your ~/.bash_profile. Do so.
source ~/.bash_profile
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
- The above command should report green across the board. If you get anything else, you'll need to search for assistance on the internet.

Now that rbenv is installed, we need to install Ruby. This project uses Ruby 2.6.3, so we'll start there.

rbenv install 2.6.3
- If you have used rbenv to install Ruby before, you will need to set the correct Ruby version for this project.
- Once you have cloned down this repository, cd into the project root.
- Run rbenv local 2.6.3. (This step can be skipped if rbenv global reports you're already using 2.6.3)
- With Ruby, the package manager we use is called Bundler. Let's be certain you have the right version.
- Run gem install bundler -v 2.0.2

Next, we'll install the PostgreSQL database.

brew install postgresql

Finally, we'll install Redis, which is used to manage our Websockets broadcasts

brew install redis
redis runs as a service in the background. It uses very little resources, so we'll go ahead and start it now.
brew services start redis
It will need to be active anytime we're running the server, however you can stop it whenever you don't need it with brew services stop redis

At this point, we have everything we need for our Rails environment. If you wish, you can also globally install Rails with gem install rails -v 5.2.3 however Bundler will ensure you have what you need for this project.

Clone this repository and run bundle install.
Prepare database with rails db:create
Migrate with rails db:migrate
Start the server with rails s

Schema

API Endpoints

Create/Initiate Game
Join Existing Game
Get Intel Data

Websockets Message Events

From Server	From Client
Player Joined
Game Started
Hint Provided	Hint Sent
Board Update	Guess Sent
Game Over
Illegal Action

Create Game

Request that the server create a new Game instance and attach the requesting user as a Player. Because we are not managing persistent users at this time, this endpoint also creates a User record for the requesting user.

Request

POST /api/v1/games

{
  "name": "Archer"
}

key	description
`name`	String: The username that the requesting user would like to use during the game

Successful Response

HTTP/1.1 201 Created

{
  "invite_code": "L6J5suAqTsKUAjEXm5swoEUN",
  "id": 0,
  "name": "Archer",
  "token": "uuxHQc7djqQuzWgJxAp5r1vy"
}

key	description
`invite_code`	String: A code which can be shared with other players. They will use this code to join the game.
`id`	Integer: The unique id for the player.
`name`	String: A confirmation that the requested name was indeed assigned to the player.
`token`	String: A token unique to the current player, which can be used to identify them in future requests to the server.

Failed Responses

Name Omitted

This error occurs if the body of the request does not contain a name, or if the name is empty.

HTTP/1.1 401 Unauthorized

{
  "error": "You must provide a username"
}

Join Game

Request that the server create a new Player instance for the requesting user and attach it to the Game denoted by the invite code.

Request

POST /api/v1/games/:invite_code/players

{
  "name": "Lana"
}

key	description
`:invite_code`	String: (Within URI) The invite code provided by the person inviting the requesting user to their existing game.
`name`	String: The username that the requesting user would like to use during the game

Successful Response

HTTP/1.1 200 OK

{
  "id": 0,
  "name": "Lana",
  "token": "uuxHQc7djqQuzWgJxAp5r1vy"
}

key	description
`id`	Integer: The unique id for the player.
`name`	String: A confirmation that the requested name was indeed assigned to the player.
`token`	String: A token unique to the current player, which can be used to identify them in future requests to the server.

Failed Responses

Name Omitted

This error occurs if the body of the request does not contain a name, or if the name is empty.

HTTP/1.1 401 Unauthorized

{
  "error": "You must provide a username"
}

Name Already In Use

This error occurs if the name requested by the user is already in use by another Player in this game.

HTTP/1.1 401 Unauthorized

{
  "error": "That username is already taken"
}

Invalid Invite Code

This error occurs if the invite code provided by the user does not match a current game.

HTTP/1.1 401 Unauthorized

{
  "error": "That invite code is invalid"
}

Game Is Full

This error occurs if the invite code provided for the user matches a game that does not have room for additional players.

HTTP/1.1 401 Unauthorized

{
  "error": "That game is already full"
}

Get Intel

Request the Intel data for a game, allowing the player to see which cards belong to which team, which are bystanders, and which is the assassin. This endpoint requires a valid token belonging to a player with the intel role.

Request

GET /api/v1/intel?token=<player_token>

key	description
`token`	String: A valid token belonging to a Player with the Intel role.

Successful Response

HTTP/1.1 200 OK

{
  "cards": [
    {
      "id": 0,
      "word": "<card word>",
      "type": "red"
    }, ...
  ]
}

key	description
`cards`	Array: An ordered collection of `card` objects which are part of the game. These cards go onto the board left-to-right, top-to-bottom.
`-->card.id`	Integer: The unique identifier for the card.
`-->card.word`	String: The word for the card.
`-->card.type`	String: The type of card to render in the UI: "red", "blue", "bystander", or "assassin".

Failed Responses

Token Omitted

This error occurs if the querystring of the request does not contain a token, or if the token is empty.

HTTP/1.1 401 Unauthorized

{
  "error": "You must provide your access token"
}

Invalid Token Code

This error occurs if the provided token does not match a player.

HTTP/1.1 401 Unauthorized

{
  "error": "Unable to find a user with that token"
}

Player Does Not Have Intel Role

This error occurs if the token matches a player who does not have the Intel role for the game.

HTTP/1.1 401 Unauthorized

{
  "error": "You are not authorized for this game's secret intel"
}

Player Joined

This message is broadcast to the game channel whenever a player joins the game. It contains the name and ID of the player who joined, as well as a roster of all players currently in the game.

Payload

{
  type: "player-joined",
  data: {
    id: 0,
    name: "name",
    playerRoster: [
      {
        id: 0,
        name: "name"
      },
      ...
    ]
  }
}

key	Description
`type`	String: The type of message being broadcast.
`data`	Object: The data payload of the message.
`data.id`	Integer: The unique id of the player who joined.
`data.name`	String: The name of the player who joined.
`data.playerRoster`	Array: A collection of `player` objects for all players currently in the game, ordered by the time they joined the lobby.
`-->player.id`	Integer: The unique id of the given player.
`-->player.name`	String: The name of the given player.

Game Started

This message is broadcast to the game channel once the final player has joined the lobby. It is broadcast after the player joined message generated by that player.

Payload

{
  type: "game-setup",
  data: {
    cards: [
      {
        id: 0,
        word: "someword"
      },
      ...
    ],
    players: [
      {
        id: 0,
        name: "name",
        isBlueTeam: true,
        isIntel: true
      },
      ...
    ],
    firstTeam: "red"
  }
}

key	description
`type`	String: The type of message being broadcast.
`data`	Object: The data payload of the message.
`data.cards`	Array: An ordered collection of `card` objects that will be used in the game. These cards go onto the board left-to-right, top-to-bottom.
`-->card.id`	Integer: The unique id for the given card.
`-->card.word`	String: The word to display on a given card.
`data.players`	Array: A collection of `player` objects for all players in the game, ordered by the time they joined the lobby.
`-->player.id`	Integer: The unique id for the given player.
`-->player.name`	String: The name for the given player.
`-->player.isBlueTeam`	Boolean: `true` if the player is on the blue team, `false` if they're on the red team.
`-->player.isIntel`	Boolean: `true` if the player has the Intel role, `false` if they don't.
`data.firstTeam`	String: The team that will play first: "red" or "blue".

Hint Sent

This message is sent from the game client to the server by the current player. So long as the sender is the current player and has the Intel role, and the hint is a single-word string, this will generate a Hint Provided broadcast to all players. If any of these requirements are not met, the appropriate Illegal Action message will be broadcast instead.

Call

cable.sendHint({
  hintWord: "tree",
  numCards: "3"
})

key	Description
`hintWord`	String: A single word hint.
`numCards`	Integer: The number of cards to which the hint is related.

Hint Provided

This message is broadcast to all players after a valid Hint Sent action is performed by a player. After receiving this message, play will proceed to the Spy player on the same team. The Spy will be allowed one more guess than the number of related cards.

Payload

{
  type: 'hint-provided',
  data: {
    isBlueTeam: true,
    hintWord: "tree",
    relatedCards: 3,
    currentPlayerId: 1
  }
}

key	Description
`type`	String: The type of message being broadcast.
`data`	Object: The data payload of the message.
`data.isBlueTeam`	Boolean: Whether the hint belongs to the Blue team or not.
`data.hintWord`	String: The hint word provided by the player.
`data.relatedCards`	Integer: The number of cards this hint is related to.
`data.currentPlayerId`	Integer: The ID of the new current player.

Guess Sent

This message is sent from the game client to the server by the current player. So long as the sender is the current player and has the Spy role, and the provided ID matches a card in the current game, this will generate a Board Update broadcast to all players, unless the guess causes the game to end, in which case the Game Over message will be broadcast instead. If any of these requirements are not met, the appropriate Illegal Action message will be broadcast instead.

If the Spy elects not to use all their guesses, they may pass. To convey a pass to the server, this message should be sent with id: null.

Call

cable.sendGuess({
  id: "1"
})

key	Description
`id`	Integer: The ID of the guessed card, or `null` if player ends their guesses early.

Board Update

This message is broadcast to all players after a valid Guess Sent action is performed by a player, unless the guess causes the game to end (in which case, the Game Over message will be broadcast instead). After receiving this message, play will proceed to the currentPlayer provided in the response.

In the event that a Spy player decides to end their turn without taking all allowed guesses, the returned card will be null instead of an Object.

Payload

{
  type: 'board-update',
  data: {
    card: { // {} or null
      id: 1,
      flipped: true,
      type: "red"
    },
    remainingAttempts: 2,
    currentPlayerId: 1
  }
}

key	Description
`type`	String: The type of message being broadcast.
`data`	Object: The data payload of the message.
`data.card`	Object: Data about the card that was guessed, or `null` if the player has ended their turn without making all allowed guesses.
`-->card.id`	Integer: The ID of the guessed card.
`-->card.flipped`	Boolean: The flipped state of the card (always `true`).
`-->card.type`	String: The type of card to render in the UI: "red", "blue", "bystander", or "assassin".
`data.remainingAttempts`	Integer: The number of guesses remaining.
`data.currentPlayerId`	Integer: The ID of the current player.

Game Over

This message is broadcast to all players after a valid Guess Sent action causes the game to end. After receiving this message, the game UI will render the end state.

Payload

{
  type: 'game-over',
  data: {
    card: {
      id: 1,
      flipped: true,
      type: "red"
    },
    winningTeam: "red",
    nextGame: "<invite code>"
  }
}

key	Description
`type`	String: The type of message being broadcast.
`data`	Object: The data payload of the message.
`data.card`	Object: Data about the card that was guessed.
`-->card.id`	Integer: The ID of the guessed card.
`-->card.flipped`	Boolean: The flipped state of the card (always `true`).
`-->card.type`	String: The type of card to render in the UI: "red", "blue", "bystander", or "assassin".
`data.winningTeam`	String: The team that won the game.
`data.nextGame`	String: An invite code for a new game. Provided automatically so all players can easily join the next game.

Illegal Action

This message is broadcast to all players after any illegal action is performed by a player in a Hint Sent or Game Sent action.

Payload

{
  type: 'illegal-action',
  data: {
    error: "<descriptive message>",
    byPlayerId: 1
  }
}

key	Description
`type`	String: The type of message being broadcast.
`data`	Object: The data payload of the message.
`data.error`	String: The descriptive error message.
`data.byPlayerId`	Integer: The ID of the player who performed the illegal action.

The potential illegal actions that are anticipated and caught are:

The player performing the action is not the current player
- "<player name> attempted to submit a (hint/guess) out of turn"
The player performed an action during their turn, but does not have the correct role for that action
- "<player name> attempted to submit a (hint/guess), but does't have the (Intel/Spy) role"
An Intel player submits a multi-word hint during their turn
- "<player name> attempted to submit an invalid hint"
A Spy player submits a guess with a card ID not present in this game
- "<player name> attempted to submit a guess for a card not in this game"

Files

README.md

Latest commit

History

README.md

File metadata and controls

Codewords Server

Requirements

Setup

Schema

API Endpoints

Websockets Message Events

Create Game

Request

Successful Response

Name Omitted

Join Game

Request

Successful Response

Name Omitted

Name Already In Use

Invalid Invite Code

Game Is Full

Get Intel

Request

Successful Response

Token Omitted

Invalid Token Code

Player Does Not Have Intel Role

Player Joined

Payload

Game Started

Payload

Hint Sent

Call

Hint Provided

Payload

Guess Sent

Call

Board Update

Payload

Game Over

Payload

Illegal Action

Payload