]> git.localhorst.tv Git - blank.git/blob - doc/protocol
higher precision for quats over the net
[blank.git] / 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
174 Code: 9
175 Payload:
176          0 transmission ID, used for reference with Chunk Data packets, 32bit unsigned int
177          4 flags, 32bit bitfield with boolean values
178            1: compressed
179          8 chunk coordinates, vec3i
180         20 data size, 32bit unsigned int
181 Length: 24
182
183
184 Chunk Data
185 ----------
186
187 Raw chunk data sent by the server, optionally compressed with zlib.
188
189 Code: 10
190 Payload:
191          0 transmission ID, references the Chunk Begin packet this data belongs to, 32bit unsigned int
192          4 block offset, offset of this block inside the whole data, 32bit unsigned int
193          8 block size, size of the data block, 32bit unsigned int
194         12 data, raw data
195 Length: 12-484
196
197
198 Block Update
199 ------------
200
201 Sent by the server whenever one or more block in a chunk have changed.
202
203 Code: 11
204 Payload:
205          0 chunk coordinates, vec3i
206         12 number of blocks, 32bit unsigned int, 1-78
207         16 first block index, 16bit unsigned int
208         18 first block data, 32bit
209         22 second block index...
210 Length: 16 + multiple of 6, max 484
211
212
213 Message
214 -------
215
216 Sent by the client when the user submits a line on the chat input.
217 Sent by the server on various events like player chat, server status, command output, etc.
218
219 Code: 12
220 Payload:
221          0 message type, 8bit unsigned int: 0 = notification, 1 = chat
222          1 referral, 32bit unsigned int, entity ID if type = 1
223          5 message, max 450 byte UTF-8 string, should be zero terminated if shorter
224 Length: 6-455