doc/protocol

   1 Structure
   2 =========
   3
   4 Offset  Size   Type  Description
   5  0      4      data  protocol tag, must be 0xFB1AB1AF
   6  4      2      uint  sequence number
   7  6      2      uint  sequence ack
   8  8      4      data  bitfield with previous acks
   9 12      1      uint  type code for the payload
  10 13      3      none  padding, reserved for future use
  11 16      0-484  data  payload, contents and length vary,
  12                      mostly depending on the type code
  13
  14 all multibyte values are in LE
  15 the current code does no conversion, so only works on machines
  16 with native LE (or BE if the server and all clients are on that,
  17 but that's by accident and will break if conversion code is ever
  18 added)
  19
  20 Common Types
  21 ------------
  22
  23 Name          Size  Type
  24 vec3          12    3x 32bit float
  25 vec3i         12    3x 32bit signed int
  26 vec3b          3    3x 8bit signed int
  27 packn          2    16bit signed int representing a float value normalized to [-1,1]
  28                         it can be unpacked by dividing by 32767
  29 packu          2    16bit unsigned  int representing a float value normalized to [0,1]
  30                         it can be unpacked by dividing by 65535
  31 vec3n          6    3x packn
  32 vec3u          6    3x packu
  33 quat           8    4x packn float
  34 entity state  42    [ 0] vec3i chunk pos (there's a variation where this is a vec3b)
  35                     [12] vec3u block pos by 16,
  36                     [18] vec3 velocity,
  37                     [30] quat orientation,
  38                     [38] packn pitch by PI/2
  39                                         [40] packn yaw by PI
  40
  41
  42 Packets
  43 =======
  44
  45 Ping
  46 ----
  47
  48 To tell the other side we're still alive.
  49 Both server and client will send this if they haven't sent something in
  50 a while.
  51
  52 Code: 0
  53 Payload: none
  54 Length: 0
  55
  56
  57 Login
  58 -----
  59
  60 Sent from client to server as a request to join. The server may
  61 respond negatively if the player name is already taken or some cap has
  62 been reached.
  63
  64 Code: 1
  65 Payload:
  66         0 player name, max 32 byte UTF-8 string,
  67           shorter names should be zero terminated
  68 Length: 0-32
  69
  70
  71 Join
  72 ----
  73
  74 Sent by the server either as a response to a successful login or when
  75 it's changing worlds.
  76
  77 Code: 2
  78 Payload:
  79          0 entity ID of the player, 32bit unsigned int
  80          4 entity state of the player
  81         46 name of the world the server's currently running
  82            max 32 byte UTF-8 string
  83 Length: 47-78
  84
  85
  86 Part
  87 ----
  88
  89 Sent by the server either as a respons to a failed login or when the
  90 client was kicked.
  91 Optionally sent by the client on disconnect.
  92
  93 Code: 3
  94 Payload: none
  95 Length: 0
  96
  97
  98 Player Update
  99 -------------
 100
 101 Sent by clients to notify the server of their changes to the player.
 102
 103 Code: 4
 104 Payload:
 105          0 player's entity state as predicted by the client
 106         42 movement input, vec3n
 107         48 active actions, 8bit bit field, first three bits are primary, secondary, and tertiary
 108         49 selected inventory slot, 8bit unsigned int
 109 Length: 50
 110
 111
 112 Spawn Entity
 113 ------------
 114
 115 Sent by the server to notify the client of an entity entering spawn range.
 116
 117 Code: 5
 118 Payload:
 119          0 entity ID, 32bit unsigned int
 120          4 entity's model ID, 32bit unsigned int
 121          8 entity state
 122         50 bounding box of the entity, 6x 32bit float
 123         74 flags, 32bit bitfield with boolean values
 124            1: world collision
 125         78 entity name, max 32 byte UTF-8 string
 126 Length: 79 - 110
 127
 128
 129 Despawn Entity
 130 --------------
 131
 132 Sent by the server to notify the client of an entity leaving spawn range.
 133
 134 Code: 6
 135 Payload:
 136         0 entity ID, 32bit unsigned int
 137 Length: 4
 138
 139
 140 Entity Update
 141 -------------
 142
 143 Sent by the server to notify the client of updated entity properties.
 144 Contained entities must be ordered by ascending entity ID.
 145
 146 Code: 7
 147 Payload:
 148          0 number of entities, 32bit int, 1-12
 149          4 base for chunk coordinates, vec3i
 150         16 entity ID, 32bit unsigned int
 151         20 entity state with vec3b as chunk position (rather than vec3i)
 152         53 next entity...
 153 Length: 16 + multiple of 37, max 460
 154
 155
 156 Player Correction
 157 -----------------
 158
 159 Sent by the server to tell a client that its prediction is way off.
 160
 161 Code: 8
 162 Payload:
 163          0 sequence number of the offending packet, 16bit unsigned int
 164          2 entity state of the player's entity on the server
 165 Length: 44
 166
 167
 168 Chunk Begin
 169 -----------
 170
 171 Sent by the server to inform the client of an upcoming chunk transmission.
 172
 173 Code: 9
 174 Payload:
 175          0 transmission ID, used for reference with Chunk Data packets, 32bit unsigned int
 176          4 flags, 32bit bitfield with boolean values
 177            1: compressed
 178          8 chunk coordinates, vec3i
 179         20 data size, 32bit unsigned int
 180 Length: 24
 181
 182
 183 Chunk Data
 184 ----------
 185
 186 Raw chunk data sent by the server, optionally compressed with zlib.
 187
 188 Code: 10
 189 Payload:
 190          0 transmission ID, references the Chunk Begin packet this data belongs to, 32bit unsigned int
 191          4 block offset, offset of this block inside the whole data, 32bit unsigned int
 192          8 block size, size of the data block, 32bit unsigned int
 193         12 data, raw data
 194 Length: 12-484
 195
 196
 197 Block Update
 198 ------------
 199
 200 Sent by the server whenever one or more block in a chunk have changed.
 201
 202 Code: 11
 203 Payload:
 204          0 chunk coordinates, vec3i
 205         12 number of blocks, 32bit unsigned int, 1-78
 206         16 first block index, 16bit unsigned int
 207         18 first block data, 32bit
 208         22 second block index...
 209 Length: 16 + multiple of 6, max 484
 210
 211
 212 Message
 213 -------
 214
 215 Sent by the client when the user submits a line on the chat input.
 216 Sent by the server on various events like player chat, server status, command output, etc.
 217
 218 Code: 12
 219 Payload:
 220          0 message type, 8bit unsigned int: 0 = notification, 1 = chat
 221          1 referral, 32bit unsigned int, entity ID if type = 1
 222          5 message, max 450 byte UTF-8 string, should be zero terminated if shorter
 223 Length: 6-455