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