Clone wiki

Potato / Network

Potato Network Protocol

All communications are done via UDP. UDP packets will be 256 in size. When game data (maps, models, etc) needs transfering HTTP via TCP will be used.

Command Format

Command1 byte
Number of Args1 byte
Data256 - 3 bytes
Checksum1 byte

The command section shall have the command. Each command can have one or more arguments. Each argument in the Data section must be separated by the NULL (0x00) char.

Command Listing

0x01 PING [Stuff]

Sends a PING request to a server or client with some random data, to check if said host is alive.

0x02 PONG [Stuff]

Sends a PONG message in response to a PING request. The same data received from the PING request must be sent back to the requester, in a PONG command.

0x10 CONNECT <nick>

When the client sends this command to the server, it initiates a game session.

0x11 READY <nick>

The client signals that it has loaded all the needed assets and is ready to play.

0x12 QUIT

Shows intent for quitting either from the server or client.

0x20 LEVEL <map_name>

Change level command sent by the server

0x21 ACCEPT <nick> <id>

The server sends this to a connecting client in order to accept it.

0x22 JOIN <nick> <id>

The server sends this command when a new player joins the game.

0x23 PART <id>

The server sends this command when a player leaves the game.

0x30 CONTROLLER [value_array]

Game controller status update.

0x40 GAMESTATE [data]

Command sent by the server containing all gamestate information. The data should be understandable by the managing game world.


Once upon a time there was a server running a Potato game. Let's call it Alice. It's Alice's duty to keep track of the current game state. She manages all the clients' input and state. But for now, she's not tracking anyone. She's idle.

Then comes along Bob. Bob knows Alice's address and via UDP sends a CONNECT command with his nick. Alice sees this commands and checks the checksum he sent along with the command. The checksum checks out! She then proceeds to send BOB an ACCEPT command with his nick and id.

Now that Bob is in, he must know what level should he connect to. Alice tells him that it is the raceway map via the LEVEL command. He loads up everything he needs and he is now ready to play! (For more information on how the LEVEL command should be handled read below the section ~Changing Level~). He now sends a READY command, signaling that he is ready. And so he begins to play in Alice's server.

In game

Now that Bob is connected, he must send commands to Alice. He does by sending the current actions he wants to do. He does so by sending CONTROLLER commands at a fixed rate (usually 60 times per second). Alice reads these commands and updates the game state accordingly.

Then Alice, also at a fixed rate (can be 60 times per second) sends back GAMESTATE commands, telling the current game state. Player positions, scoring, etc.

Changing Level

Alice now decides that it is a good time to change to another level. She proceeds to send a LEVEL to all players. Bob is actually connected and playing. He reads out what level is needed to load and proceeds to load it. It happens that he doesn't have the requested level. So, he proceeds to connect to Alice's running web server to fetch a zip file containing all the level information and respective assets. After having a level fully loaded (either he had the level data or not) he sends a READY command to the server. Now that Alice knows that Bob is ready, she signals to the remainder connected players that he is indeed ready by sending them the JOIN command.


Bob is bored. He wants to leave. To do so, he just sends a QUIT command to Alice. Alice proceeds to free any resources needed for Bob, and disconnects him. Bob goes on with his life.

It also happens that Alice doesn't want to serve the current game anymore. She then proceeds to send a QUIT command to connected players. They proceed to free any resources and go on with their lifes, while Alice stops running any server.