]> git.localhorst.tv Git - blank.git/blob - doc/protocol
(shabby) client side handling of messages
[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 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