revised todo list

[blank.git] / doc / protocol

diff --git a/doc/protocol b/doc/protocol
index a02ff2afa4bffa99b29dc32b7fe448e3d115af13..8e2694970ce596b049b2facb4aa313634214b085 100644 (file)
--- a/doc/protocol
+++ b/doc/protocol
@@ -17,6 +17,28 @@ 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
 =======
@@ -36,7 +58,7 @@ Length: 0
 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.
 
@@ -56,11 +78,10 @@ it's changing worlds.
 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
-Length: 68-100
+Length: 47-78
 
 
 Part
@@ -82,9 +103,11 @@ Sent by clients to notify the server of their changes to the player.
 
 Code: 4
 Payload:
-        0 chunk coords of the player, 3x 32bit signed int
-       12 pos/vel/rot/ang of the player, 13x 32bit float
-Length: 64
+        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
@@ -95,13 +118,13 @@ Sent by the server to notify the client of an entity entering spawn range.
 Code: 5
 Payload:
         0 entity ID, 32bit unsigned int
-        4 chunk coords of the entity, 3x 32bit signed int
-       16 pos/vel/rot/ang of the entity, 13x 32bit float
-       68 bounding box of the entity, 6x 32bit float
-       92 flags, 32bit bitfield with boolean values
+        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
-       96 entity name, max 32 byte UTF-8 string
-Length: 128
+       78 entity name, max 32 byte UTF-8 string
+Length: 79 - 110
 
 
 Despawn Entity
@@ -123,8 +146,79 @@ Contained entities must be ordered by ascending entity ID.
 
 Code: 7
 Payload:
-        0 number of entities, 32bit int, 1-7
-        4 chunk coords of the entity, 3x 32bit signed int
-       16 pos/vel/rot/ang of the entity, 13x 32bit float
-       68 next entity...
-Length: 4 + multiple of 64, max 452
+        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