Multiplayer Protocol

Cube World Wiki, cataloging the cubes.
Share/Save/Bookmark
Jump to: navigation, search

In CubeWorld, multiplayer is achieved using Transmission Control Protocol (TCP). Just like in most standard protocols, data between a client and a server is transmitted using packets.

Almost all of this information comes from the cuwo project and the team behind it.

Note: There is still a lot to be investigated regarding the protocol, particularly in the entity update and server update packets.


Contents

Data types

Data types describe what kind of information is being transmitted. All of the ranges described are inclusive.

  • Byte - 8 bit data structure.
  • Signed - Ranges from -128 to 127
  • Unsigned - Ranges from 0 to 255
  • Short - 16 bit data structure.
  • Signed - Ranges from -32,768 to 32,767
  • Unsigned - Ranges from 0 to 65,535
  • Integer - 32 bit data structure.
  • Signed - Ranges from –2,147,483,648 to 2,147,483,647
  • Unsigned - Ranges from 0 to 4,294,967,295
  • Long - 64 bit data structure.
  • Signed - Ranges from –9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
  • Unsigned - Ranges from 0 to 18,446,744,073,709,551,615
  • Float - 32 bit data structure. The only data type in use that allows a floating point (up to 7 digits).
  • String - Data structure to support transmission of text. Starts with an unsigned long to describe how long the following data is going to be. Length is described in characters, and they are encoded in UTF-16LE, which means that every character is 2 bytes long (1 short), so you are going to need to read twice as many bytes as described initially.
  • Vector - the amount of data in this structure varies. Consists of 3 numbers to describe 3 dimensional information (position, velocity).
  • Float - consists of 3 floats. 3 * 32 bits in total.
  • Integer - consists of 3 integers. 3 * 32 bits in total.
  • Long - consists of 3 longs. 3 * 64 bits in total.

Packets

Almost all of this information comes from the cuwo project and the team behind it.

Overview

Packet ID Purpose Server or Client Notes
0 Entity Update Both Compressed data
1 Multiple Entity Update unknown Compressed data, not used?
2 Entity Update Finished S->C No data
3 (UNUSED) (possibly Inventory Update?) unknown(S->C?) not currently used?
4 Server State Update S->C Compressed data
5 Current Time S->C
6 Interact C->S
7 Hit C->S
8 (UNKNOWN) (Stealth State?) C->S
9 Shoot C->S
10 Chat Message Both The C->S version has no Entity ID, the S->C version does
11 Chunk Discovered C->S
12 Sector Discovered C->S
13 Unknown unknown does this packet even exist?
14 Unknown unknown does this packet even exist?
15 Map Seed S->C
16 Join Packet S->C
17 Client Version/Server Version Both The server only sends this packet if the client version doesn't match it?
18 Server Full S->C No data


Common (both S->C and C->S) Packets

Entity Update (0x0) (0)

Name Type Notes
Packet ID Unsigned Integer
Size Unsigned Integer Size of the compressed area, in bytes
zlib (deflated) data Variable See above

The deflated entity data is as such:

Name Type Notes
Entity ID Unsigned Long
Entity mask bitfield Unsigned Long This describes what data will follow in the packet
Entity data Variable the length and arrangement of this data depends on what bits were set in the bitfield above.

The actual format of the Entity data and bitfield is complicated. This info comes from cuwo's "entity.py". The bits are parsed in order from lowest to highest, and the data appears in the data block in that same order.

Bit number Name Data Type Notes
0 Position Long vector The entity's position (X,Y,Z)
1 Orientation 3 * Float The entity's orientation (Roll, Pitch, Yaw)
2 Velocity Float vector The entity's velocity
3 Acceleration Float vector The entity's acceleration
4 (Extra) Velocity Float vector The entity's secondary/extra velocity
5 Viewport Pitch Float The viewport's pitch (for player entity only?)
6 Physics Flags Unsigned Integer Update the physics flags*
7 Hostile Mode/Entity Relation to Player Unsigned Byte 1 = hostile; 5 = pet mode
8 Entity Type Unsigned Integer
9 Current Mode Unsigned Byte
10 Mode Start Time Unsigned Integer
11 Hit Counter Unsigned Integer
12 Last Hit Time Unsigned Integer
13 Appearance AppearanceData struct (see cuwo entity.py)
14 Entity Flags 2 * Unsigned Byte
15 Roll(Evade?) Time Unsigned Integer
16 Stun Time Unsigned Integer
17 Slowed Time Unsigned Integer
18 Make Blue Time(?) Unsigned Integer
19 Speed Up Time Unsigned Integer
20 Show Patch Time(?) Float
21 Class Type Unsigned Byte
22 Specialization Unsigned Byte
23 Charged MP Float
24 Unused 3 * Unsigned Integer not used
25 Unused 3 * Unsigned Integer not used
26 Ray Hit Float Vector
27 HP Float
28 MP Float
29 Block Power Float
30 Multipliers 5 * Float (Max HP, Shoot Speed, Damage, Armor, Resist)
31 Unused Unsigned Byte not used
32 Unused Unsigned Byte not used
33 Level Unsigned Integer
34 Current XP Unsigned Integer
35 Parent Owner Unsigned Long  ?Entity ID of owner?
36 Unknown/Unused? 2 * Unsigned Integer not used?
37 Power Base Unsigned Byte
38 Unknown/Unused? Unsigned Integer not used?
39 Unknown/Unused? 3 * Unsigned Integer not used?
40 Spawn Position Long Vector The entity's spawn position (X,Y,Z)
41 Unused 3 * Unsigned Integer not used?
42 Unused Unsigned Byte not used
43 Consumable Consumable Struct (see cuwo entity.py)
44 Equipment Equipment Struct (see cuwo entity.py)
45 Name 12 * Unsigned Byte Entity Name (in ASCII)
46 Skills 12 * Unsigned Integer
47 Mana Cubes Unsigned Integer

Chat Message (0xA) (10)

Server->Client
Name Type Notes
Packet ID Unsigned Integer
Entity ID (of sender) Unsigned Long Note: only server->client has this!
Length Unsigned Integer Message size in UTF-16_LE characters, i.e. in 16-bit words, one per character
Message String Message content in UTF-16_LE
Client->Server
First packetː
Name Type Notes
Packet ID Unsigned Integer
Length Unsigned Integer Message size in UTF-16_LE characters, i.e. in 16-bit words, one per character
Second packetː
Name Type Notes
Message String Message content
  • Is this 'split' even possible or is it just one packet for client->server?


Client -> Server Packets

Interact (0x6) (6)

Name Type Notes
Packet ID Unsigned Integer
Equipment Equipment (?) Describes player equipment
Chunk X Signed Integer X position of the current chunk
Chunk Y Signed Integer Y position of the current chunk
Item index in Chunk Signed Integer The index in the list of items for the current chunk
Unknown Unsigned Integer
Interaction type Unsigned Byte Type of interaction
Unknown Unsigned Byte
Unknown Unsigned Short

Interaction types:

  • 2 - NPC (shops, talk)
  • 3 - Normal (?)
  • 5 - Pickup item
  • 6 - Drop item
  • 8 - Examine


Hit (0x7) (7)

Name Type Notes
Packet ID Unsigned Integer
Entity ID of Attacker Unsigned Long ID of the attacker
Entity ID of Target Unsigned Long ID of the target entity.
Damage Float Amount of damage made
Critical Unsigned Byte If the hit was critical
Skip 3 bytes (?)
Stun duration Unsigned Integer
Unknown Unsigned Integer
Hit position Long Vector (X,Y,Z)
Hit direction Float Vector
Skill used for hit(?) Unsigned Byte
Hit type(?) Unsigned Byte
Show light Unsigned Byte If there should be a flash of light shown for the hit

Unknown_8 (Stealth?) (0x8) (8)

Name Type Notes
Packet ID Unsigned Integer
Unknown 40 byte array? (bitfield?) Bit (?) Array

Shoot (0x9) (9)

Name Type Notes
Packet ID Unsigned Integer
Entity ID of Attacker Unsigned Long ID of the attacker
Chunk X Signed Integer X position of the current chunk
Chunk Y Signed Integer Y position of the current chunk
Unknown Unsigned Integer
Skip 4 bytes(?)
Position Long Vector (X,Y,Z)
Unknown Unsigned Integer
Unknown Unsigned Integer
Unknown Unsigned Integer
Velocity Float Vector
Unknown Float ('Random' damage multiplier?)
Unknown Float
Unknown Float
Unknown Float (Stamina? Stun? 'Charge' used for shot?)
Unknown Unsigned Integer
Unknown Unsigned Byte (Skill used for shot?)
Skip 3 bytes(?)
Unknown Unsigned Integer
Unknown Unsigned Byte
Skip 3 bytes(?)
Unknown Unsigned Integer
Unknown Unsigned Integer

Chunk Discovered (0xB) (11)

Name Type Notes
Packet ID Unsigned Integer
Chunk X Unsigned Integer X position of the current chunk
Chunk Y Unsigned Integer Y position of the current chunk

Sector Discovered (0xC) (12)

Name Type Notes
Packet ID Unsigned Integer
Position X Unsigned Integer
Position Y Unsigned Integer

Client Version (0x11) (17)

Name Type Notes
Packet ID Unsigned Integer
Version Number Unsigned Integer Describes the current version of the client
  • For pre-alpha 'livestreamer' clients on the last week of June, this is '2'
  • For alpha clients as of the July 2 release, this is '3'

Server -> Client Packets

(UNUSED?) Multiple Entity Update (0x1) (1)

  • Note: this packet is supported but probably not used?
Name Type Notes
Packet ID Unsigned Integer
Count Unsigned Integer Number of entities to update
Compressed Entity Data Variable See Entity Update (0x0) for remainder of packet (without the 0x0 id field); and multiply the number of entities by Count above.

Entity Update Finished (0x2) (2)

Name Type Notes
Packet ID Unsigned Integer
  • Sent from Server to Client as an acknowledge for a previous Entity Update. Doesn't contain any data?

(UNUSED) (possibly Inventory Update?) (0x3) (3)

Name Type Notes
Packet ID Unsigned Integer
Count Unsigned Integer Number of 120-byte entries
Unknown Data 120*Count Bytes Unknown, may be ItemData packets?
  • Note: this packet is probably currently unused, possibly inventory or character file related?

Server State Update (0x4) (4)

Name Type Notes
Packet ID Unsigned Integer
Size Unsigned Integer Size of the compressed area, in bytes
zlib (deflated) data Variable See above
  • The decompressed data contains a set of lists of structs, number of structs is Unsigned Integer 'n':

(some structs are of variable length Unsigned Integer 'm')

List Number Name Type Notes
1 Block Delta Update n * Fixed length struct Changes to blocks (added/removed) caused by bombs/saurians/(future)building/etc
2 Player Hits n * Fixed length struct
3 Particle Effects n * Fixed length struct
4 Sound Actions n * Fixed length struct
5 Shoot Actions n * Fixed length struct
6 Object Actions n * Fixed length struct (object state changes/animations for static object such as doors, etc)
7 Chunk Items n * m * Fixed length struct
8 Unknown n * m * Fixed length struct (Maybe Player Inventory Items/Subitems?)
9 Pickup Actions n * Fixed length struct
10 Kill Actions n * Fixed length struct
11 Damage Actions n * Fixed length struct
12 NPC Rightclick Action? n * Fixed length struct(40 bytes) (Used when NPC wizards/creatures use a right-click targeted action such as a spell cast; any other purpose unknown)
13 Mission Data n * Fixed length struct (Quest data, what boss monster to kill in what chunk, etc)

Current Time (0x5) (5)

Name Type Notes
Packet ID Unsigned Integer
Day Unsigned Integer  ?
Time Unsigned Integer  ?
  • Is this in-game time or actual time of day of the server?

Map Seed (0xF) (15)

Name Type Notes
Packet ID Unsigned Integer
Map Seed Unsigned Integer Note: seed data is masked to 32 bits if user entered something ridiculous in the server.cfg file

Join Packet (0x10) (16)

Name Type Notes
Packet ID Unsigned Integer
Unknown Unsigned Integer must be zero or crash?
Entity ID (assigned to player) Unsigned Long Unmodified server will assign numbers 2 thru 9? (check this)
Entity Data (assigned to player) Variable Same as (uncompressed) entity data in entity update packet; this sets the player position etc on the client in the game world upon connect; (if no data is present, write 0x1168 of zeroes? is that a cuwo debug thing?)

Server Version Mismatch (0x11) (17)

Name Type Notes
Packet ID Unsigned Integer
Version Number Unsigned Integer Describes the current version of the server

Server Full (0x12) (18)

Name Type Notes
Packet ID Unsigned Integer
  • Sent from Server to Client when server is full. Doesn't contain any data?

See Also

Modding