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