Network Specification - McSherry/AppsAgainstHumanity GitHub Wiki

This document details the communications format used by Apps Against Humanity-compatible clients and servers. This list is the authoritative and official list of commands for communication, and will be updated upon the modification of commands. This document also details the flow of communication between client and server, listing expected actions to be taken.

Specification version 0.1, compatible with Apps Against Humanity 0.1.0+.

This is the sequence of events and actions which will take place during a standard game of Apps Against Humanity. It will likely be updated when new features are introduced.

1. TCP handshake
2. Client sends desired username (up to 20 characters, alphanumeric with _ and |)
3. Server acknowledges, but may refuse based on an invalid username
4. If the server accepts the player's request to join, it will send information about any other connected players
5. Upon the starting of the game:
6. Server generates a seed to be used for the duration of the round
7. Using this seed, the server generates a numeric identifier for every white card
8. The server sends 10 white cards to each player
9. On white cards sent (round start):
10. Server selects a random black card from its pool and sends its contents to the clients
11. Using the black card, sends an appropriate amount of white cards (e.g. Draw 2 will cause the server to send two white cards with the black card)
12. Server selects a Card Czar and notifies all clients
13. On all picks from clients received:
14. Server shuffles order of received white cards
15. Server sends white cards (identifier and text) to clients
16. Server waits for Card Czar's choice
17. On Card Czar's choice:
18. Server informs all players of this round's winner
19. Server awards an appropriate quantity of Awesome Points to winner
20. If no player has met the Awesome Points limit, server begins a new round
21. If a player has reached the limit, they are declared the winner. The server informs all clients of this, then terminates the game, giving clients a 2.5 second grace period to disconnect before the server shuts down.

An AAH client and server communicate by exchanging commands, sometimes with arguments following them. These commands are extremely simple in their structure: a 4-byte identifier followed by any parameters, where each parameter is separated by a NUL. This simplifies parsing, as the first four bytes of any message will always be the command. Below is a list of all commands, including their current support status.

Statuses:

• None -- This command is currently implemented by neither the client nor server.
• Partial -- This command is currently implemented by either the client or the server.
• Full -- This command is currently implemented by both the client and server.

Parameters in angled brackets (<param>) are required. Parameters in square brackets ([param]) are optional. Parameters within curly braces are grouped ({ <group 1 param> [group 1 param] } { <group 2 param> }). Ellipses (...) indicate there may be multiple instances of a given parameter in a command.

Command	Status	Meaning / Purpose
JOIN <name>	Full	Sent by the client when it is requesting to join a game.
ACKN	Full	Sent by the server to acknowledge a client's request to join. NACC is implied.
REFU [reason]	Full	Sent by the server when a client's request to join is refused.
NICK <name>	Full	Sent by the client to request a change of nickname.
NACC	Full	Sent by the server when a client's request to change its nickname is accepted.
NDNY [reason]	Full	Sent by the server when a client's request to change its nickname is denied.
CLNF <name> ...	Full	List of clients currently connected to the server, sent by the server.
CLJN <name>	Full	Sent by the server to indicate that a client has joined.
CLEX <name>	Full	Sent by the server to indicate that a client has exited.
SMSG <message>	Full	Sent by the client to request the relaying of a message to other clients.
RMSG <sender> <message>	Full	A message relayed by the server to all clients.
BDCS <message>	Full	A message broadcast to all clients by the server.
DISC	Partial	If sent by the client, a request to disconnect. If sent by the server, informs the client that it has been disconnected.
GSTR	Full	Sent to clients to indicate that the game has started.
RSTR	Full	Sent to clients to indicate that a round has started.
BLCK <contents> <pick no.>	Full	Sent by server to inform clients of the black card for the current round. Includes the number of cards a client should respond with.
WHTE <id> <contents>	Full	Sent by the server to the client to indicate that the client has drawn a white card with the specified ID and text.
CZAR <name>	Full	Server informs clients of this round's Card Czar
PICK <id> ...	Full	Sent by the client to indicate its choices of card. Card IDs should be sent in the order they are to be judged.
BLNK	Full	Command sent by the server to inform clients that another client has submitted a choice of white card.
CZPK <id>	Full	Card Czar sends their pick for the winning card to the server. If players have played more than a single card each, only one must be sent from the multiple cards picked per player.
REVL { <id> <contents> } ...	Full	The server reveals the card choices to each client. Cards which should be grouped together are sent together (e.g. Pick 2 = 1 REVL with 2 Cards' content per player).
PNTS <player> <points>	Full	Server informs clients of the number of points a given player has.
RWIN [{<player> <id>}]	Full	Server broadcasts the winner of the round with their winning card. If the player's name and the card ID are missing, the round is null and void.
GWIN <player>	Full	Server broadcasts the winner of the game.
CRTO	Partial	Server informs a client that they have reached the time limit for selecting cards, and have been skipped.
CZTO	Partial	Server informs a Card Czar that they have exceeded the time limit for picking a winner (limit is twice that given to normal clients), and that they have been skipped and the round ended.
UNRG [reason]	Partial	Server informs the client that there was an error regarding the command they sent.
META [Base64/xml]	Full	Permits the exchange of metadata between client and server to allow tasks such as version identification to be performed. A reference is available on this wiki.