---
# System prepended metadata

title: Whack-A-Stoodent API documentation
tags: [BA4, CGL, Programming]

---

###### tags: `CGL` `BA4` `Programming`

# Whack-A-Stoodent API documentation

## Connection

The default port of a Whack-A-Stoodent server is 57007 and uses ENet for communication.

## Messages

The data between server and client are sent in a binary form.

A message starts with the message ID as an 1 byte integer, following with the contents of the message. The least significant bytes are sent first. (Little endian byte order)

### Administrative Messages

#### 1 : Authenticate (client to server only)

This message authenticates a client at a server.

| Parameters | Size                                              |
| ---------- | ------------------------------------------------- |
| User ID    | 16 bytes                                          |
| Name       | [Dynamic (byte sized string)](#Byte-sized-string) |

#### 2 : Acknowledge authentification (server to client only)

This message describes that the client authentification was successful. 

| Parameters   | Size                                              |
| ------------ | ------------------------------------------------- |
| User ID      | 16 bytes                                          |
| Session code | 6 bytes                                           |
| Name         | [Dynamic (byte sized string)](#Byte-sized-string) |

#### 3 : Deny authentification (server to client only)

This message describes that client authentification has failed.

#### 4 : Ping

This message can be used to keep a connection alive or to measure ping.

| Parameters | Size    |
| ---------- | ------- |
| Ping data  | 4 bytes |

#### 5 : Pong

This message is a response to a ping message. It has to contain the same data as the ping.

| Parameters | Size    |
| ---------- | ------- |
| Pong data  | 4 bytes |

#### 6 : Request match history (client to server only)

This message requests a clients match history from the server.

#### 7 : Respond match history (server to client only)

This message provides a client with their match history.

| Parameters  | Size    |
| ----------- | ------- |
| Entry count | 4 bytes |

Each entry is a [match history entry](#Match-history-entry) object.

### Matchmaking Messages

#### 8 : Play with random (client to server only)

This message tells the server to play a game with a random user.

#### 9 : Play with session code (client to server only)

This message tells the server to play with the specified session ID.

| Parameters   | Size    |
| ------------ | ------- |
| Session code | 6 bytes |

#### 10 : Request play (server to client only)

This message tells a client that an user wants to play with them.

| Parameters              | Size                                              |
| ----------------------- | ------------------------------------------------- |
| Opponent's session code | 6 bytes                                           |
| Opponent's name         | [Dynamic (byte sized string)](#Byte-sized-string) |

#### 11 : Accept play request (client to server only)

This message tells the server that the pending play request has been accepted.

#### 12 : Deny play request

This message tells that the previous play request has been denied.

| Parameters            | Size    |
| --------------------- | ------- |
| Reason                | 1 byte  |

#### 13 : Started game (server to client only)

This message tells a client that their game has started.

Once they have loaded their games, they have to respond with [this message](#Loaded-game).

| Parameter       | Size                                              |
| --------------- | ------------------------------------------------- |
| Your role       | 1 byte                                            |
| Opponent's name | [Dynamic (byte sized string)](#Byte-sized-string) |

#### 14 : Loaded game

This message tells the server that the client has loaded.
This message tells the client that all clients have loaded.

#### 15 : End game (server to client only)

This message tells clients that the game has ended.

It sends a [match history entry](#Match-history-entry) object.

### In-Game Messages

#### 16 : Hit (client to server only)

This message tells that a hit has been performed.
The position is the click position that triggered the hit (in world space).

| Parameters | Size               |
| ---------- | ------------------ |
| Position   | 8 bytes (2D float) |

#### 17 : Look

This message tells that a mole is looking through the specified hole.
The hole index describes which hole the mole is looking through.

| Parameters                  | Size   |
| --------------------------- | ------ |
| [Hole index](#Hole-indices) | 1 byte |

#### 18 : Hide

This message tells that the mole is no longer looking.

#### 19 : Hit success (server to client only)

This message tells clients that the mole was successfully hit with the hammer, while being in the indicated hole.
he hole index describes which hole the mole is looking through.
The position is the click position that triggered the hit in world space.

| Parameters           | Size               |
| -------------------- | ------------------ |
| [Hole index](#Holes) | 1 byte             |
| Points               | 8 bytes            |
| Position             | 8 bytes (2D float) |

#### 20 : Hit fail (server to client only)

This message tells clients that a hit has failed

| Parameters | Size               |
| ---------- | ------------------ |
| Position   | 8 bytes (2D float) |

#### 21 : Score mole (server to client only)

This message tells clients that the mole has scored.

| Parameters | Size               |
| ---------- | ------------------ |
| Points     | 8 bytes            |

### Debugging

#### 0 : Error

This message contains information of error happened.

| Parameters                 | Size                                                    |
| -------------------------- | ------------------------------------------------------- |
| [Error type](#Error-types) | 1 byte                                                  |
| Error message              | [Dynamic (integer sized string)](#Integer-sized-string) |

#### 255 : Log

This message can be used for logging (stdout and stderr).
For defined errors please use the [error](#0--Error) message instead.

| Parameters               | Size                                                    |
| ------------------------ | ------------------------------------------------------- |
| [Log level](#Log-levels) | 1 byte                                                  |
| Log message              | [Dynamic (integer sized string)](#Integer-sized-string) |

## Objects

### Match history entry

| Entry parameters | Size                                              |
| ---------------- | ------------------------------------------------- |
| Session ID       | 16 bytes                                          |
| Your score       | 8 bytes                                           |
| Your role        | 1 byte                                            |
| Your name        | [Dynamic (byte sized string)](#Byte-sized-string) |
| Opponent's score | 8 bytes                                           |
| Opponent's role  | 1 byte                                            |
| Opponent's name  | [Dynamic (byte sized string)](#Byte-sized-string) |

### String

A string is prefixed with its length following with its contents in Unicode.

#### Byte sized string

| Parameters      | Size                              |
| --------------- | --------------------------------- |
| String length   | 1 byte                            |
| String contents | String length * 2 bytes (Unicode) |

#### Integer sized string

| Parameters      | Size                              |
| --------------- | --------------------------------- |
| String length   | 4 bytes                           |
| String contents | String length * 2 bytes (Unicode) |

## Constants

### Error types

| Name                     | Value |
| ------------------------ | ----- |
| Unknown                  | 0     |
| Internal                 | 1     |
| Unsupported message type | 2     |
| Malformed message        | 3     |
| Invalid message context  | 4     |

### Hole indices

| Name         | Value |
| ------------ | ----- |
| Top-Left     | 0     |
| Top-Right    | 1     |
| Bottom-Right | 2     |
| Bottom-Left  | 3     |

### Log levels

| Name    | Value |
| ------- | ----- |
| Info    | 0     |
| Warning | 1     |
| Error   | 2     |

### Player role indices

| Name   | Value |
| ------ | ----- |
| Hitter | 0     |
| Mole   | 1     |
