@NAME Protocol Spec, r1

Glossary

• CiSo: Client-in, Server-out. The packet is sent by the server and received by the client.
• CoSi: Client-out, Server-in. The packet is sent by the client and received by the server.
• A number prefixed with a dollar sign '$' is written in hexadecimal.
• A number suffixed with 'ms' is a count of milliseconds.
• A number suffixed with 't' is a count of game ticks, once every 1/25th of a second.
• A number prefixed with 'U-' is a hexadecimal Unicode codepoint.

Words written between [brackets] are abbreviations for the following data types:

• U8: Unsigned 8 bit integer
• U16: Big-endian, unsigned 16 bit integer
• U32: Big-endian, unsigned 16 bit integer
• Ua8: Variable-length array of unsigned 8 bit integers
• Str: Variable-length UTF-8 text string without BOM. NULL (U+0000) is disallowed.
• FixPos: Big-endian, two's-compliment signed 32 bit integer, representing 1/64th of a meter.
• Angle: Big-endian, unsigned 16 bit integer, representing 1/65536th of a full turn.
• ChunkPos: Big-endian, two's-compliment signed 16 bit integer, representing 16/1 meters.

Preface

@NAME is a voxel-based video game with a simple, flexible network protocol.

$00 — Disconnect (CiSo, CoSi)

Sent by the client to announce they are about to disconnect, and sent by the server to tell a client they have been forcibly disconnected.

Packet Length   [U16] = 1 + Length of Reason Message
Packet Opcode   [U8]  = $00
Reason Message  [Str] = ...

$01 — Ping (CiSo, CoSi)

Sent occasionally by both the client and server to eachother as a keep-alive mechanism. The recommended frequency for sending this packet is ~500ms.

The contents of the [U32] 'data' field are implementation-defined. The recipient sends back a ping packet containing a 'data' field of the same value that was received.

Packet Length  [U16] = 5
Packet Opcode  [U8]  = $01
         Data  [U32] = ...

$02 — Message (CiSo, CoSi)

Message Channels

• $00: Player Chat. Text messages sent by players MUST be in this channel.
• $01: System Message. Announcements, warnings, and OPTIONAL diagnostic messages from the server SHALL be in this channel. Clients MUST NOT send messages in this channel.
• $02: IPC Communication. This channel is used for communicating textual information between the server and client. See the 'IPC Messages' section below.

IPC Messages

IPC Message fields are tab-separated (U+0009). Their descriptions are written here with spaces for readability.

Packet Length  [U16] = 2 + Length of Message Data
Packet Opcode  [U8]  = $02
      Channel  [U8]  = (See 'Message Channels' section above)
 Message Data  [Str] = ...