spec.md

Notes

• client: the game server
• server: the admin panel
• All integers are little-endian, all strings are null-terminated
• Enums are shown in light blue, responses are in light pink, records are in light purple
• Fields with asterik* are always present, if not present, it may not be sent

Connection Flow

Once a socket connection is established, the client (the game server), will send a Auth Record, and the server will either respond with an OK Response, or an Error Response (with an optional message). Once the client gets the OK, it will perform a full sync and send these group of records:

• Game Record
  • Finale Record (if finale active)
• Player Record (per player)
  • Survivor Record (if survivor)
  • Survivor Item Record (if survivor)
  • Infected Record (if infected)

Data Types

All data types are little-endian and signed

Name	Value
Byte	8-bit signed little-endian integer
Short	16-bit signed little-endian integer
Int	32-bit signed little-endian integer
Float	32-bit signed little-endian float
String	Null-terminated ASCII String

Enums

SurvivorState

Bitfield, can be any combination of values (besides None)

Name	Value
None	0
Black & White	1
In Saferoom	2
Is Calm (intensity = 0)	4
Is Boomed	8
Is Pinned (by special infected)	16
Alive	32

SurvivorMovement

Name	Value
Idle	0
Incapped	-1
Hanging From Ledge	-2
Under Attack (SurvivorState.IsPinned should be set)	-3
Walking	1
Running	2
Crouched	3
On Ladder	4

SurvivorAction

Name	Value
None	0
Being Healed	-1
Healing	1
Deploying Ammo Pack (unused)	2
Defibbing Teammate	4
Being Defibbed	5
Deploying Fire Ammo	6
Deploying Explosive Ammo	7
Pouring Gas	8
Delivering Cola	9
Pressing Button	10
UsePointScript	11

Built in Commands

When a Run Command Response is sent, these are the available commands for the builtinnamespace. The format is namespace:command

• &lt;param**>** indicates a required parameter (<> should not be included)
• [param] indicates an optional parameter (<> should not be included)

Command	Description
builtin:stop	Informs the server to exit. This ignores if there are any players online. he sourcemod plugins runs exit
builtin:request_stop	Asks the server to stop. If there is players, the Command Response record's result will be 0, if successful, will be 1.
builtin:kick <steamid or #userid>	Kicks the player. If game server is sourcemod, then can be STEAM_#_#_##### or #userid

Packets

Server → Client Packets (Responses)

LiveRecordResponse Enum

Name	Value
OK	0
Reconnect	1
Error	2
Refresh	3
RunCommand	4

The types Reconnect, Error, and Refresh have no extra arguments, only the response type field is needed

Response: OK

Sent periodically (as a heartbeat) and when the view count changes

Field	Type	Value
Response Type*	Byte	LiveRecordResponse.OK (0)
View Count*	Byte	The number of current viewers of live view

Response: Reconnect

Informs the client to reconnect. The client should wait a few seconds before performing, as this response is used from panel when it is restarting.

Field	Type	Value
Response Type*	Byte	LiveRecordResponse.Reconnect (1)

Response: Error

An error occurred, with an optional message. If during first Auth Record, then indicates auth failure, otherwise any other type of error.

Field	Type	Value
Response Type*	Byte	LiveRecordResponse.Error (2)
Message	Byte	The number of current viewers of live view

Response: Refresh

Requests the client to give a full refresh, same as what is performed after successful authentication ((Game+Finale) + Player + (Survivor+SurvivorItems|Infected))

Field)	Type	Value
Response Type*	Byte	LiveRecordResponse.Refresh (3)

Response: Run Command

Runs a command on the client (game server). The client will return a Command Response Record if the command exists, or an Error Record if it does not.

Namespace is optionally, send a single null terminator to use default. Command Response Records should be sent in order, but an ID can be set to verify as well.

Field	Type	Value
Response Type*	Byte	LiveRecordResponse.RunCommand (4)
ID*	Byte	An id for the command, the Command Response Record will contain the same id.
Command*	String	The command to run
Namespace*	String	Optional. The namespace of commands, default is "default", can be "builtin"

---

Client → Server Packets (Records)

Multiple records can be included per packet, they are separated by ASCII Record Separator 0xE1. Client → Server Packets are always suffixed by a newline \n character.

The end of a record is then indicated by:

• Presence of a newline character \n(LF) 0x0A
• Presence of a record separator RS 0xE1

LiveRecordType Enum

Name	Value
Game	0
Player	1
Survivor	2
Infected	3
Finale	4
Survivor Items	5
Command Response	6
Auth	7

Record: Auth

Field	Type	Value
Type*	Byte	LiveRecordType.Auth (7)
Token*	String	JWT token, generated from panel

Record: Command Response

Field	Type	Value
Type*	Byte	LiveRecordType.CommandResponse (6)
ID*	Byte	The ID that was specified when command was sent
Result*	Byte	The result of the command, can be boolean or a number. -1 is for command does not exist
Message*	String	The raw text response, may be blank.

Record: Game

Sent every time a map is loaded, and when starting a transition.

Can be re-sent by sending a Refresh response

Field	Type	Value
Type*	Byte	LiveRecordType.Game (0)
Start Timestamp*	Int	Unix timestamp (seconds). When the plugin has started, which can be used as server uptime
Campaign Start Timestamp*	Int	Unix timestamp (seconds). When the current campaign has started
Difficulty*	Byte	The difficulty level, in order: Easy(0), Normal(1), Advanced(2), Expert(3)
In Transition*	Byte	Is the server transitioning to the next map
Gamemode*	String	The current gamemode
Map*	String	The current map

Record: Player

The first 3 fields are always given, if the last 3 fields are missing this is a disconnection and the player should be removed from your cache.
Typically, this record is followed with either [SurvivorRecord + SurvivorItemsRecord] or InfectedRecord

Field	Type	Value
Type*	Byte	LiveRecordType.Player (0)
User ID*	Int	User ID (auto incremented for each user, for a duration of a session)
SteamID*	String	User's SteamID 2 (STEAM_#:#:#######). Is "BOT" if a fake client
Is Idle	Byte	Is the player idle (thus, the following survivor records are for their bot)
Join Timestamp	Byte	Unix timestamp (seconds). When player first joined campaign, shouldn't reset during transitions but it can
Name	String	The player's name

Record: Survivor

Represents a survivor. If a player is idle, this will be the idle player's bot's data.

Field	Type	Value
Type*	Byte	LiveRecordType.Player (1)
User ID*	Int	User ID (auto incremented for each user, for a duration of a session) Is the same as the Player record
Survivor*	Byte	The survivor type 0=Nick, 1=Rochelle, 2=Coach, 3=Ellis 4=Bill, 5=Francis, 6=Zoey, 7=Louis
Temp Health*	Byte	Temp health, from pills/adrenaline
Permanent Health*	Byte	Permanent health, assumed to be max 100. To get total health add with temp health
Flow Progress Percent*	Byte	How far through a campaign as a percent (0-100) the player is. Can go up/down
Survivor State*	Byte	Survivor state enum, see below
Movement State*	Byte	Survivor movement enum, see below
Survivor Action*	Byte	Survivor action enum, see below

Record: Survivor Items

Slots may be empty (and only include a single null terminator).

Slot 1, if the weapon was weapon_melee, the melee weapon's name will be given instead. All other weapons retain their weapon_ prefix

Field	Type	Value
Type*	Byte	LiveRecordType.SurvivorItems (5)
User ID*	Int	User ID (auto incremented for each user, for a duration of a session)
Slot 0*	String	The weapon in slot 0 (primary)
Slot 1*	String	The weapon in slot 1 (secondary, pistols)
Slot 2*	String	The weapon in slot 2 (throwables)
Slot3*	String	The weapon in slot 3 (kit/ammo packs)
Slot 4*	String	The weapon in slot 4 (pills / adrenaline)
Slot 5*	String	The weapon in slot 5 (any carryables, ex. gascans, gnome)

Record: Infected

Represents a player-controllable special infected.

There is never a record for Infected with special type witch (7), as it's not a player-controllable enemy.

Field	Type	Value
Type*	Byte	LiveRecordType.Infected (3)
User ID*	Int	User ID (auto incremented for each user, for a duration of a session)
Current Health*	Short	The infected's current health
Max Health*	1Short	The infected's maximum health, such as for tanks
Special Type*	Byte	Enum, starting at 0, in order: Smoker(1), Boomer(2), Hunter(3), Spitter(4), Jockey(5), Charger(6), Witch(7), Tank(8)
Victim User ID*	Byte	If infected has a victim (hunted player, smoked player, etc), their user id.

Record: Finale

Sent every time the finale stage changes, indicates the finale is active

Field	Type	Value
Type*	Byte	LiveRecordType.Finale (4)
Finale Stage*	Byte	The current finale stage
Escape Vehicle Active*	Byte	Is the finale escape vehicle ready?