The Client/Server Protocol

The protocol is optimized for using as less bandwidth as possible. Only parameters that have changed are sent over the network. Sending a player's changed position and angle from the server to the client, for instance, needs only 14 bytes (including header). A dead reckoning mechanism is used for extrapolating positions and angles between cycles.

Messages are sent within packets of an UDP data stream. The structure of the messages is a single-byte command, followed by command-dependant data. Depending on the importance of the message, they are either sent by a reliable or an unreliable packet; this can be changed by adjusting the dplay_unreliable variable. When describing the content of messages, we use the following conventions:

Byte an unsigned integer, one byte.
Short a signed integer, 2 bytes, Big Endian order (Intel order).
Long a signed integer, 4 bytes, Big Endian order (Intel order).
Float a floating point number, 4 bytes, Big Endian order (Intel order).
Fixed a fixed point number in 22.10 format, 4 bytes, Big Endian order (Intel order).
String a sequence of characters, terminated by 0 ('\0')
Angle a short, to be multiplied by 360.0/65535.0 to convert it to degrees.
Position a coordinate packed in 3 bytes by dividing it by 8
CPosition either Position or Fixed, depending on the pos_resolution variable
Scale(x) a value packed into one byte to be multiplied by x/255.0.

Client Messages

The following commands are used for transferring information from a client to the server.

Command Bytecode Arguments Description
CLS_JOIN 0x02 String Player_Name
String Session_Name
Request for joining the session (reliable).
CLS_CREATE 0x03 String File_Name
Position Start[3]
Long Action_Index
Short Identifier
Request creating an entity with given model name, and link the client to it (reliable).
CLS_REMOVE 0x04 Short Entity_Index Request removing entity on the server (reliable).
CLS_PING 0x07
Periodically sent by the client, dependent on dplay_pingrate (unreliable). If a client does not send anything for more than 5 seconds, it is automatically disconnected by the server.
CLS_LEVEL 0x09 String Level_Name Inform the server that the client has loaded a level (reliable).
CLS_VAR 0x0a Short Var_Index
Short Var_Length
Fixed Var[Var_Length]
Send a variable or an array (reliable).
CLS_STRING 0x0b Short String_Index
String Text
Send a string (reliable).
CLS_CVAR 0x0c Long Var_Offset
Fixed Var
Send a variable (reliable).
CLS_SKILL 0x0e Short Entity_Index
Short Struct_Offset
Fixed Skill
Send an entity skill (reliable). Struct_Offset gives the byte offset of the skill in the ENTITY struct.
CLS_SKILL3 0x0f Short Entity_Index
Short Struct_Offset
Fixed Skill[3]
Send an entity vector skill (reliable).

Server Messages

The following commands are used for transferring information from the server to either a specific client, or to all clients connected.

Command Bytecode Arguments Description
SVC_CREATE 0x03 Short Entity_Index
Short Identifier
Response to CLS_CREATE: Created entity with given index (reliable).
SVC_REMOVE 0x04 Short Entity_Index Removed entity from server (reliable).
SVC_ENTSOUND 0x05 Short Entity_Index
Short Sound_Index
Scale(2000) Volume
Long Sound_Handle
Play an entity sound on the clients (unreliable).
SVC_EFFECT 0x06 Long Action_Index
Short Number
Position Start[3]
Fixed Vel[3]
Generate a particle or beam effect on the clients (unreliable).
SVC_INFO 0x07 Byte Protocol_Version
Long Client_ID
Accept the client to the session (reliable).
SVC_VAR 0x0a Short Var_Index
Short Var_Length
Fixed Var[Var_Length]
Send a variable to the client (reliable).
SVC_STRING 0x0b Short String_Index
String Text
Send a string to the client (reliable).
SVC_CVAR 0x0c Long Var_Offset
Fixed Var
Send a variable to the client (reliable).
SVC_SKILL 0x0e Short Entity_Index
Short Struct_Offset
Fixed Skill
Send an entity skill to the client (reliable). Struct_Offset gives the byte offset of the skill in the ENTITY struct.
SVC_SKILL3 0x0f Short Entity_Index
Short Struct_Offset
Fixed Skill[3]
Send an entity vector skill to the client (reliable).
SVC_TIME 0x11
Float Server_Time
Send the server time to the clients (unreliable). This is sent periodically according to the dplay_entrate setting, and also together with entity updates for dead reckoning.
SVC_LOCAL 0x12 Short Entity_Index
Long Function_Index
Start the given function with the given entity on the client (reliable).
SVC_ENTITY 0x13 Short Entity_Index
Long Client_ID
Created entity with given index (reliable).
SVC_UPDATE1 0x40..0x7f Short Entity_Index (Parameters see below) Update entity parameters 1 (reliable)
SVC_UPDATE2 0x80..0xbf Short Entity_Index (Parameters see below) Update entity parameters 2 (unreliable).
SVC_UPDATE3 0xc0..0xff Short Entity_Index (Parameters see below) Update entity parameters 3 (reliable).

For the 3 entity parameter update messages, bits 0..5 of the svc_update bytecode give the parameter combination to be sent or received, in the order given below. All parameters are sent only when they have changed, according to the dplay_entrate setting. If an update packet contains file name, skin, flags, or lightrange, it is sent in reliable mode. Otherwise it's sent in unreliable mode.

Parameter Update.Bit Arguments Remarks
type 1.0 String File_Name Name of the mdl, wmb, pcx, etc. file
scale 1.1 Short Scale[3] XYZ scale*0.25
ambient 1.3 Scale(100) Ambient
albedo 1.4 Scale(255) Albedo
skin 1.2 Byte Skin Skin number
position 2.0 CPosition Pos[3] XYZ position
pan 2.1 Angle Pan
tilt 2.2 Angle Tilt
roll 2.3 Angle Roll
frame 2.4 Short Frame_Int
Scale(1) Frame_Frc
Short Nextframe
Frame number, tweening factor, tweening target
lightrange 3.0 Scale(2000) Lightrange
color 3.1 Scale(255) Red,Green,Blue RBG color packed in 3 bytes
alpha 3.2 Scale(100) Alpha
uv 3.3 Fixed U,V UV offset or speed for entity textures
flags 3.5 Short Flags 8..23

For instance, the code sequence
0x83 0x07 0x00 0x80 0x00 0x00 0x00 0x01 0x00 0x80 0x01 0x00 0x80 0x00

updates position and pan angle (0x83 has bits 0 and 1 set) of entity No. 7 (0x07 0x00). The position uses the packed format and is set at coordinates x=1 (0x80 0x00 0x00), y=2 (0x00 0x01 0x00) and z=3 (0x80 0x01 0x00), and the pan angle is set at 180 degrees (0x80 0x00).

► latest version online