Skip to content

Development: ServerFu

Jump to bottom
xmeadow edited this page Mar 13, 2026 · 1 revision

ServerFu — Network Protocol

Notes by Aaron Bishop (Dunlar)

ServerFu describes the server-side network protocol for multiplayer. It covers shard discovery, joining a game, room handshakes, and heartbeating.

Server Discovery Packets

PACKET_TYPE_REQUEST_SHARD_LIST

Field Type
executable_version unsigned short
data_version unsigned short
continent unsigned char
direction unsigned char

PACKET_TYPE_REPLY_SHARD_LIST

Field Type
shard_valid_flags (32 bits, 26 used) unsigned int
ip_address_of_whoever_requested unsigned int
map_server_ip_address (per valid shard) unsigned int

PACKET_TYPE_REQUEST_PLAYER_COUNT

(no payload)

PACKET_TYPE_REPLY_PLAYER_COUNT

Field Type
number_of_players unsigned short

PACKET_TYPE_REPLY_VERSION_ERROR

Field Type
required_executable_version unsigned short
required_data_version unsigned short

Join Protocol

PACKET_TYPE_REQUEST_JOIN (sent to server)

Field Type
executable_version unsigned short
data_version unsigned short
continent unsigned char
direction unsigned char
letter unsigned char
number_of_players unsigned char
password (optional, check packet size) 20 bytes

PACKET_TYPE_COMMAND_JOIN

(only accepted from main_server or machines already in game)

Field Type
continent unsigned char
direction unsigned char
letter unsigned char
password_okay (213 = okay) unsigned char
ip_address_of_joiner unsigned int
game_seed (only if sent to joining machine) unsigned int

PACKET_TYPE_REPLY_JOIN_OKAY

Field Type
sun_time unsigned int

Join Flow

  1. Machine sends REQUEST_JOIN to server
  2. Server checks password, sends COMMAND_JOIN to a machine already in game
  3. That machine sends COMMAND_JOIN to the joiner (repeated)
  4. Joiner rogers with REPLY_ROGER, waits (abort if not received in 10s)
  5. Machine sends COMMAND_JOIN to all others in game
  6. Others roger; machine notifies main server
  7. Machine sends REPLY_JOIN_OKAY to joiner
  8. Joiner requests up to 16 IP lists (64 IPs per list)
  9. Joiner is now in the game

IP List Packets

PACKET_TYPE_REQUEST_IP_LIST

Field Type
list_portion (0=0–63, 1=64–127, etc.) unsigned char

PACKET_TYPE_REPLY_IP_LIST

Field Type
list_portion unsigned char
Per machine (up to 64): room x/y/z, password_okay, ip_address unsigned char ×3 + unsigned char + unsigned int

Room Handshake

PACKET_TYPE_REQUEST_ROOM_JOIN

Field Type
room x / y / z unsigned char each

PACKET_TYPE_REPLY_ROOM_JOIN

Field Type
room x / y / z unsigned char each

PACKET_TYPE_REQUEST_ALL_ROOM_DATA

(no payload)

PACKET_TYPE_REPORT_ROOM_CHARACTER

Field Type
character number unsigned short
lots of data...

PACKET_TYPE_REPORT_ROOM_PARTICLE

Field Type
particle number unsigned short
lots of data...

PACKET_TYPE_REPORT_ROOM_ORDERS

Field Type
time orders should run unsigned int
16-bit flags for which players have orders unsigned short
actual order per player (2–6 bytes each) variable

PACKET_TYPE_WELCOME_TO_ROOM

Field Type
main_game_frame (frame client begins operation) unsigned int

Room Transfer Flow

  1. Client sends REQUEST_ROOM_JOIN to all machines in nearby area
  2. Hosting machine backs up character data, sends REPLY_ROOM_JOIN
  3. Client sends REQUEST_ALL_ROOM_DATA (must be received within 3s or server stops handling)
  4. Room server sends one packet per frame per character/particle
  5. Client rogers each; server resends unacknowledged (up to 10 times)
  6. Timeout: 3s server-side, 6s client-side

Maintenance Packets

PACKET_TYPE_REPORT_MACHINE_DOWN

Field Type
continent unsigned char
direction unsigned char
letter unsigned char
ip_address unsigned int
minutes_in_game (only if ip=0.0.0.0, sent to main server) unsigned short

PACKET_TYPE_HEARTBEAT

(no payload) — machines heartbeat the IP directly above them (wraps at end) every ~1 minute. Failure for 3 minutes = reported as down by the machine above.

PACKET_TYPE_REPORT_POSITION (broadcast, no repeat)

Field Type
room x / y / z unsigned char each

Clone this wiki locally