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 XYZ coordinate from the server to the client, for instance, needs only 12 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. |
The following commands are used for transferring information from a client to the server.
| Command | Bytecode | Arguments | Description |
|---|---|---|---|
| CLS_JOIN | 0x02 | String Player_Name | Request for joining the session (reliable). |
| CLS_CREATE | 0x03 | String File_Name Position Start[3] Short Action_Index Short Identifier |
Request creating an entity with given model name, and link the client to it (reliable). |
| CLS_REMOVE | 0x04 | Long 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_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 A4_ENTITY struct. |
| CLS_SKILL3 | 0x0f | Short Entity_Index Short Struct_Offset Fixed Skill[3] |
Send an entity vector skill (reliable). |
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 |
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 | Short 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 Float Server_Time |
Send the server time to the clients (reliable). This is sent periodically according to the dplay_entrate setting. |
| 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_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 A4_ENTITY struct. |
| SVC_SKILL3 | 0x0f | Short Entity_Index Short Struct_Offset Fixed Skill[3] |
Send an entity vector skill to the client (reliable). |
| SVC_local | 0x12 | Short Entity_Index Short Function_Index |
Start the given function with the given entity on the client (reliable). |
| SVC_UPDATE1 | 0x40..0x7f | Short Entity_Index (Parameters see below) | Update entity parameters 1. |
| SVC_UPDATE2 | 0x80..0xbf | Short Entity_Index (Parameters see below) | Update entity parameters 2. |
| SVC_UPDATE3 | 0xc0..0xff | Short Entity_Index (Parameters see below) | Update entity parameters 3. |
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 |
|---|---|---|---|
| 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 |
| flags1 | 2.5 | Short Flags 8..23 | |
| 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 |
| 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 |
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).