revised todo list

[blank.git] / doc / protocol

diff --git a/doc/protocol b/doc/protocol
index 63055a267fce123b022ef54ba6fdfad26ef649c4..8e2694970ce596b049b2facb4aa313634214b085 100644 (file)
--- a/doc/protocol
+++ b/doc/protocol
@@ -1,3 +1,45 @@
+Structure
+=========
+
+Offset  Size   Type  Description
+ 0      4      data  protocol tag, must be 0xFB1AB1AF
+ 4      2      uint  sequence number
+ 6      2      uint  sequence ack
+ 8      4      data  bitfield with previous acks
+12      1      uint  type code for the payload
+13      3      none  padding, reserved for future use
+16      0-484  data  payload, contents and length vary,
+                     mostly depending on the type code
+
+all multibyte values are in LE
+the current code does no conversion, so only works on machines
+with native LE (or BE if the server and all clients are on that,
+but that's by accident and will break if conversion code is ever
+added)
+
+Common Types
+------------
+
+Name          Size  Type
+vec3          12    3x 32bit float
+vec3i         12    3x 32bit signed int
+vec3b          3    3x 8bit signed int
+packn          2    16bit signed int representing a float value normalized to [-1,1]
+                       it can be unpacked by dividing by 32767
+packu          2    16bit unsigned  int representing a float value normalized to [0,1]
+                       it can be unpacked by dividing by 65535
+vec3n          6    3x packn
+vec3u          6    3x packu
+quat           8    2bit index of largest component, a 2bit padding, then 3x 20bit small components in xyzw
+                       order mapped from [-0.7072,0.7072] to [0,1048574] (with largest omitted)
+entity state  42    [ 0] vec3i chunk pos (there's a variation where this is a vec3b)
+                    [12] vec3u block pos by 16,
+                    [18] vec3 velocity,
+                    [30] quat orientation,
+                    [38] packn pitch by PI/2
+                                       [40] packn yaw by PI
+
+

 Packets
 =======
 
 Packets
 =======
 


@@ -10,12 +52,13 @@ a while.
 
 Code: 0
 Payload: none
 
 Code: 0
 Payload: none

+Length: 0

 
 
 Login
 -----
 
 
 
 Login
 -----
 

-Sent from client to serveri as a request to join. The server may
+Sent from client to server as a request to join. The server may

 respond negatively if the player name is already taken or some cap has
 been reached.
 
 respond negatively if the player name is already taken or some cap has
 been reached.
 


@@ -23,6 +66,7 @@ Code: 1
 Payload:
        0 player name, max 32 byte UTF-8 string,
          shorter names should be zero terminated
 Payload:
        0 player name, max 32 byte UTF-8 string,
          shorter names should be zero terminated

+Length: 0-32

 
 
 Join
 
 
 Join


@@ -34,10 +78,10 @@ it's changing worlds.
 Code: 2
 Payload:
         0 entity ID of the player, 32bit unsigned int
 Code: 2
 Payload:
         0 entity ID of the player, 32bit unsigned int

-        4 chunk coords of the player, 3x 32bit signed int
-       16 pos/vel/rot/ang of the player, 13x 32bit float
-       68 name of the world the server's currently running
+        4 entity state of the player
+       46 name of the world the server's currently running

           max 32 byte UTF-8 string
           max 32 byte UTF-8 string

+Length: 47-78

 
 
 Part
 
 
 Part


@@ -49,3 +93,132 @@ Optionally sent by the client on disconnect.
 
 Code: 3
 Payload: none
 
 Code: 3
 Payload: none

+Length: 0
+
+
+Player Update
+-------------
+
+Sent by clients to notify the server of their changes to the player.
+
+Code: 4
+Payload:
+        0 player's entity state as predicted by the client
+       42 movement input, vec3n
+       48 active actions, 8bit bit field, first three bits are primary, secondary, and tertiary
+       49 selected inventory slot, 8bit unsigned int
+Length: 50
+
+
+Spawn Entity
+------------
+
+Sent by the server to notify the client of an entity entering spawn range.
+
+Code: 5
+Payload:
+        0 entity ID, 32bit unsigned int
+        4 entity's model ID, 32bit unsigned int
+        8 entity state
+       50 bounding box of the entity, 6x 32bit float
+       74 flags, 32bit bitfield with boolean values
+          1: world collision
+       78 entity name, max 32 byte UTF-8 string
+Length: 79 - 110
+
+
+Despawn Entity
+--------------
+
+Sent by the server to notify the client of an entity leaving spawn range.
+
+Code: 6
+Payload:
+       0 entity ID, 32bit unsigned int
+Length: 4
+
+
+Entity Update
+-------------
+
+Sent by the server to notify the client of updated entity properties.
+Contained entities must be ordered by ascending entity ID.
+
+Code: 7
+Payload:
+        0 number of entities, 32bit int, 1-12
+        4 base for chunk coordinates, vec3i
+       16 entity ID, 32bit unsigned int
+       20 entity state with vec3b as chunk position (rather than vec3i)
+       53 next entity...
+Length: 16 + multiple of 37, max 460
+
+
+Player Correction
+-----------------
+
+Sent by the server to tell a client that its prediction is way off.
+
+Code: 8
+Payload:
+        0 sequence number of the offending packet, 16bit unsigned int
+        2 entity state of the player's entity on the server
+Length: 44
+
+
+Chunk Begin
+-----------
+
+Sent by the server to inform the client of an upcoming chunk transmission.
+
+Code: 9
+Payload:
+        0 transmission ID, used for reference with Chunk Data packets, 32bit unsigned int
+        4 flags, 32bit bitfield with boolean values
+          1: compressed
+        8 chunk coordinates, vec3i
+       20 data size, 32bit unsigned int
+Length: 24
+
+
+Chunk Data
+----------
+
+Raw chunk data sent by the server, optionally compressed with zlib.
+
+Code: 10
+Payload:
+        0 transmission ID, references the Chunk Begin packet this data belongs to, 32bit unsigned int
+        4 block offset, offset of this block inside the whole data, 32bit unsigned int
+        8 block size, size of the data block, 32bit unsigned int
+       12 data, raw data
+Length: 12-484
+
+
+Block Update
+------------
+
+Sent by the server whenever one or more block in a chunk have changed.
+
+Code: 11
+Payload:
+        0 chunk coordinates, vec3i
+       12 number of blocks, 32bit unsigned int, 1-78
+       16 first block index, 16bit unsigned int
+       18 first block data, 32bit
+       22 second block index...
+Length: 16 + multiple of 6, max 484
+
+
+Message
+-------
+
+Sent by the client when the user submits a line on the chat input.
+Sent by the server on various events like player chat, server status, command output, etc.
+
+Code: 12
+Payload:
+        0 message type, 8bit unsigned int: 0 = notification, 1 = chat
+        1 referral, 32bit unsigned int, entity ID if type = 1
+        5 message, max 450 byte UTF-8 string, should be zero terminated if shorter
+Length: 6-455