RCON: Difference between revisions

From Totem Arts Wiki
Jump to navigation Jump to search
Agent (talk | contribs)
→‎GAME: Filled in table; added crate table
Agent (talk | contribs)
→‎Commands: Listed the commands; still need to fill in PARAMETERS, RESPONSE, and DESCRIPTION fields
Line 107: Line 107:
|-
|-
| Help || [Command] || True || List of commands if parameters is not empty, command-specific message otherwise || Provides help information about commands
| Help || [Command] || True || List of commands if parameters is not empty, command-specific message otherwise || Provides help information about commands
|-
| ClientList || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| LoadMutator || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| UnloadMutator || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ListMutators || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| HostSay || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| HostPrivateSay || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
|-
| Kick || <Player> [Reason] || True || Nothing on success, error otherwise || Forcefully kicks a player from the server, and displays a kick message if specified
| Kick || <Player> [Reason] || True || Nothing on success, error otherwise || Forcefully kicks a player from the server, and displays a kick message if specified
|-
| KickBan || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ForceKick || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| TextMute || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| TextUnMute || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ChangeMap || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| RecordDemo || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| SwapTeams || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| EndMap || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ForceNonSeamless || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ForceSeamless || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| CancelVote || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| MutateAsNone || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| MutateAsPlayer || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| HasCommand || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| Map || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| Ping || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| Team || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| Team2 || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ClientVarList || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| BotList || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| BotVarList || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| PlayerInfo || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| MineLimit || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| VehicleLimit || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ChangeName || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| ServerInfo || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| GameInfo || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| BuildingInfo || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| Rotation || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| MineBan || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| MineUnban || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| TeamInfo || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| SpectateMode || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| NormalMode || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| AddMap || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
| RemoveMap || PARAMETERS || True || RESPONSE || DESCRIPTION
|-
|-
| Kill || <Player> || False || Nothing on success, error otherwise ||  Kills a player's pawn
| Kill || <Player> || False || Nothing on success, error otherwise ||  Kills a player's pawn
|-
| GiveCredits || PARAMETERS || False || RESPONSE || DESCRIPTION
|-
| Disarm || PARAMETERS || False || RESPONSE || DESCRIPTION
|-
| DisarmBeacon || PARAMETERS || False || RESPONSE || DESCRIPTION
|-
| DisarmC4 || PARAMETERS || False || RESPONSE || DESCRIPTION
|}
|}



Revision as of 22:36, 9 August 2016

RCON is a text based protocol completely unrelated to the Source RCON protocol. It is designed with readability, ease of implementation, and human usability in mind.

Packet Format

RCON packets consist of a single-byte Type ID, a variable number of ASCII strings separated by the Delimiter (Start of Text/0x02), and a newline. The text after the Type ID and before the newline is referred to as the message.

Type ID Message End Message
1 byte Variable Characters 0x0A (Newline)

Limitations

RCON strictly contains standard ASCII strings and does not support null characters. RCON therefore only guarantees the reliability of character values [1, 127]. This is largely because RCON is interpreted entirely as strings by the Renegade X server, but both TCPLink and Rx_TCPLink are incapable of directly reading or transmitting non-ASCII characters when in text mode.

Player are consistently represented in the format id,team,name. This means that you can parse RCON output directly without retaining any information about players if you so choose.

Escaping

Unicode sequences are escaped and interpreted in the format "\uXXXX", where XXXX is the hexadecimal representation of a Unicode code point. There is no support for Unicode code points beyond 16 bits in size, largely because the Unreal Development Kit does not support these strings. Therefore, both RCON and the Unreal Development Kit can only possibly support characters within the Unicode Basic Multilingual Plane (BMP).

The only non-Unicode character that you must sequence is the backslash (\) character, which can be escaped as \\

Processing

The recommended and intended method of processing RCON output is to:

  1. Process incoming data into lines (split on newline; no CR is included)
  2. Process tokens in each line into an array
  3. Process each token for escaped Unicode sequences
  4. Begin processing the content normally, based on the Type ID.

Type ID values

Server refers to the Renegade X server and client refers to the RCON client. Type IDs

Client -> Server

If not yet authenticated, the server will only accept Authenticate messages.

Type ID Description
a Authenticate
s Subscribe
u Unsubscribe
c Command
d DevBot specific (reserved)

Server -> Client

Type ID Description
v RCON and game version information
a Authentication success
e Error
r Command response
c Command execution finished
l Log
d DevBot specific

Example Implementation

An actively maintained and fully functional RCON client implementation can be found on Agent's GitHub here. Jupiter Bot is entirely ISC licensed, and you are free to reference, modify, and redistribute any code from it.

Version

The version provides information about the server in the following format. Each element is separated by the Delimiter (STX/0x02).

RCON Version Number Game Version Number Game Version String
004 5230 Open Beta 5.23

The zeroes preceding the RCON version number are to maintain compatibility with previous version of RCON where there was not a delimiter between the version number and the game version string, and may be removed in the future. The RCON version number is base 10.

Authentication

The TypeID for authentication is 'a'. The message portion from the client is just the RCON/admin password for the server. The message portion from the server is the RCON client's connection ID, so that the RCON client can identify its own command executions from other clients. The sequence for authenticating is as follows:

  1. Client connects to Server
  2. Server sends version information
  3. Client sends authentication request
  4. Server replies with authentication success or an error

Once the client is authenticated, they may subscribe to the log stream and execute commands.

Subscribe & Unsubscribe

The message elements for both of these Type IDs are empty and ignored. Subscribe marks the stream to receive RCON logs, and Unsubscribe marks the stream to not receive RCON logs. The default state in unsubscribed; therefore, you will need to Subscribe after successful authentication in order to receive any log messages.

Commands

In addition to the following RCON commands, RCON clients can also execute console commands. Console commands do not return any useful output. Some RCON commands are not available when bIsCompetitive is true.

The message format for commands is the command; if there are any parameters to pass to the command's execution, you need to add a space character (0x20), followed by the string representing the parameters. Required parameters are marked as <Parameter>, and optional parameters are marked as [Parameter].

Player can be a portion of a player's name, a player's full name, pid<player's ID>, or Player<player's ID>.

Command Parameters Available in Competitive Response Description
Help [Command] True List of commands if parameters is not empty, command-specific message otherwise Provides help information about commands
ClientList PARAMETERS True RESPONSE DESCRIPTION
LoadMutator PARAMETERS True RESPONSE DESCRIPTION
UnloadMutator PARAMETERS True RESPONSE DESCRIPTION
ListMutators PARAMETERS True RESPONSE DESCRIPTION
HostSay PARAMETERS True RESPONSE DESCRIPTION
HostPrivateSay PARAMETERS True RESPONSE DESCRIPTION
Kick <Player> [Reason] True Nothing on success, error otherwise Forcefully kicks a player from the server, and displays a kick message if specified
KickBan PARAMETERS True RESPONSE DESCRIPTION
ForceKick PARAMETERS True RESPONSE DESCRIPTION
TextMute PARAMETERS True RESPONSE DESCRIPTION
TextUnMute PARAMETERS True RESPONSE DESCRIPTION
ChangeMap PARAMETERS True RESPONSE DESCRIPTION
RecordDemo PARAMETERS True RESPONSE DESCRIPTION
SwapTeams PARAMETERS True RESPONSE DESCRIPTION
EndMap PARAMETERS True RESPONSE DESCRIPTION
ForceNonSeamless PARAMETERS True RESPONSE DESCRIPTION
ForceSeamless PARAMETERS True RESPONSE DESCRIPTION
CancelVote PARAMETERS True RESPONSE DESCRIPTION
MutateAsNone PARAMETERS True RESPONSE DESCRIPTION
MutateAsPlayer PARAMETERS True RESPONSE DESCRIPTION
HasCommand PARAMETERS True RESPONSE DESCRIPTION
Map PARAMETERS True RESPONSE DESCRIPTION
Ping PARAMETERS True RESPONSE DESCRIPTION
Team PARAMETERS True RESPONSE DESCRIPTION
Team2 PARAMETERS True RESPONSE DESCRIPTION
ClientVarList PARAMETERS True RESPONSE DESCRIPTION
BotList PARAMETERS True RESPONSE DESCRIPTION
BotVarList PARAMETERS True RESPONSE DESCRIPTION
PlayerInfo PARAMETERS True RESPONSE DESCRIPTION
MineLimit PARAMETERS True RESPONSE DESCRIPTION
VehicleLimit PARAMETERS True RESPONSE DESCRIPTION
ChangeName PARAMETERS True RESPONSE DESCRIPTION
ServerInfo PARAMETERS True RESPONSE DESCRIPTION
GameInfo PARAMETERS True RESPONSE DESCRIPTION
BuildingInfo PARAMETERS True RESPONSE DESCRIPTION
Rotation PARAMETERS True RESPONSE DESCRIPTION
MineBan PARAMETERS True RESPONSE DESCRIPTION
MineUnban PARAMETERS True RESPONSE DESCRIPTION
TeamInfo PARAMETERS True RESPONSE DESCRIPTION
SpectateMode PARAMETERS True RESPONSE DESCRIPTION
NormalMode PARAMETERS True RESPONSE DESCRIPTION
AddMap PARAMETERS True RESPONSE DESCRIPTION
RemoveMap PARAMETERS True RESPONSE DESCRIPTION
Kill <Player> False Nothing on success, error otherwise Kills a player's pawn
GiveCredits PARAMETERS False RESPONSE DESCRIPTION
Disarm PARAMETERS False RESPONSE DESCRIPTION
DisarmBeacon PARAMETERS False RESPONSE DESCRIPTION
DisarmC4 PARAMETERS False RESPONSE DESCRIPTION

Logs

Most game events are logged, including everything from players joining/leaving to mines being placed/disarmed. Some logs are disabled when bIsCompetitive is true.

Format

Logs follow the following format:

  1. Token 0 is the primary header
  2. Token 1 is the secondary header
  3. Tokens beyond 1 depend entirely upon the primary and secondary headers

The '|' character in the following tables notates represents the Delimiter (STX/0x02). String constants in the parameters are surrounded by double quotes. Sections surrounded in [ Brackets ] indicate that these parameters may not always appear.

PLAYER

Player state changes and warnings are covered by this header.

Secondary Header Parameters Description
Enter; "from" | IP Address | "hwid" | "" | "nosteam" / <"steamid" | Steam ID> A player entered the server; hwid may later be removed
TeamJoin; "joined" | Team [ | "left" | Old Team ] A player joined a team
HWID; HWID Reports a player's HWID
Exit; Player A player left the server
Kick; "for" | Reason A player was kicked
NameChange; "to:" | New Name A player's name changed
ChangeID; New ID | "from" | Old ID A player's Player ID changed
Rank; Rank A player's leaderboard Rank has been assigned
Dev; "true" / "false" A player has been marked as a Developer
Command; Command A player executed an RCON command
SpeedHack; Player A player has thrown a SpeedHack warning

GAME

Game events are covered by this header.

Secondary Header Parameters Description
Deployed; Player [ | "on" | Surface ] A deployable weapon (beacon, c4, etc) was deployed
Disarmed; "by" | Player [ | "owned by" | Owner ] A deployed weapon (beacon, c4, etc) was disarmed
Exploded; "near" | Spot Location | "at" | Location [ | "by" | Owner ] A deployed weapon (beacon, c4, etc) exploded
ProjectileExploded; "at" | Location [ | "by" | Owner ] A projectile weapon exploded
Captured; "id" | Building ID | "by" | Player A building was captured
Neutralized; "id" | Building ID | "by" | Player A capturable building was neutralized
Purchase; <"character" / "item" / "weapon" / "vehicle" | Object | "by" | Player> / <"refill" | Player> A player purchased something
Spawn; <"player" | Player | "character" | Character> / <"bot" | Player> / <"vehicle" | Vehicle Team "," Vehicle> Something spawned
Crate; [Crate Type | Crate Type Parameters (see below table)] | "by" | Player A player picked up a crate
Death; "player" | Player | <"by" | Killer Player | "with" | Damage Type> / <"died by" | Damage Type> / <"suicide by" | Damage Type> A player died
Stolen; Vehicle | <"by" | Player> / <"bound to" | Owner Player | "by" | Player> A vehicle was stolen
Destroyed; Object | "by" | Killer Player | "with" | Damage Type An object (building, vehicle, etc) was destroyed
Donated; "to" | Recipient Player | "by" | Donor Player A player donated funds to another player
OverMine; "near" | Location A player is over-mining
MatchEnd; "Nod=" Nod Total Score The match has ended
Crate Type Parameters Description
vehicle Vehicle A vehicle spawns near the player
death Player dies
suicide Player kills their self
money Amount Player gets free credits
character Character Player gets a new character
spy Character Player gets a spy that is hidden from base defenses
refill Player gets a health and ammo refill
timebomb A suicide Timed C4 gets attached to the player
speed Player's speed gets increased
nuke A nuke spawns at the player's location
abduction Player gets abducted and killed by aliens

CHAT

Chat messages are covered by this header.

Secondary Header Parameters Description
Say; "said:" | Message A player said something in public chat
TeamSay; "said:" | Message A player said something in team chat
Radio; "said:" | Message A player used a radio command
AdminSay; "said:" | Message A player said something in the admin chat
ReportSay; "said:" | Message A player said something to the administrators
HostSay; Message Host said something in public chat

VOTE

Votes are covered by this header. Team Type is either "GDI", "Nod", or "Global". It is theoretically possible for Team Type to be empty.

Secondary Header Parameters Description
Called; Vote Type | "by" | Player [ | Parameters... ] A vote has been started; see the table below for a list of parameters
Results; Vote Type | "pass" / "fail" | "Yes=" Total yes votes | "No=" Total no votes A vote has ended with the following results
Cancelled; Vote Type A vote was forcefully cancelled
Vote Type Called; Parameters Description
Rx_VoteMenuChoice_AddBots "GDI" / "Nod" / "Both" | "amount" | Number of bots | "skill" | Skill Level Adds bots
Rx_VoteMenuChoice_ChangeMap Forcefully ends the game on success
Rx_VoteMenuChoice_Kick Player Kicks a player from the server
Rx_VoteMenuChoice_MineBan Player Restricts a player from mining
Rx_VoteMenuChoice_RemoveBots "GDI" / "Nod" / "Both" | "amount" | Number of bots Removes bots
Rx_VoteMenuChoice_RetsartMap Forcefully ends the game and restarts the level
Rx_VoteMenuChoice_Surrender Forcefully ends the game as a loss for the team
Rx_VoteMenuChoice_Survey Message A survey with a user-specifiable message

MAP

Changes to the level's state are covered by this header.

Secondary Header Parameters Description
Changing; "nonseamless" / "seamless" Server is changing levels
Loaded; Map Server finished loading a level
Start; Map Match started

DEMO

Demo recording state changes are covered by this header.

Secondary Header Parameters Description
Record; Player> / <"admin command by" | Player> / "rcon command" A demo recording has started
RecordStop; A demo recording has stopped

ADMIN

Events related to a player's administrator or moderator permissions are covered by this header.

Secondary Header Parameters Description
Rcon; "executed:" | Command A player executed an RCON command
Login; "as" | Type = "moderator" / "administrator" A player logged into administrative permissions
Logout; "as" | Type = "moderator" / "administrator" A player logged out from administrative permissions
Granted; "as" | Type = "moderator" / "administrator" A player was granted administrative permissions

RCON

RCON events are covered by this header.

Secondary Header Parameters Description
Command; "executed:" | Command An RCON client executed a command
Subscribed; User An RCON client subscribed to RCON logs
Unsubscribed; User An RCON client unsubscribed from RCON logs
Blocked; Reason An RCON client was blocked from connecting
Connected; User An RCON client connected
Authenticated; User An RCON client authenticated
Banned; "reason" | Reason An RCON client was banned
InvalidPassword; User An RCON client attempted to login with an incorrect password
Dropped; "reason" | Reason An RCON client was dropped
Disconnected; User An RCON client disconnected
StoppedListen; Reason No further RCON clients can connect
ResumedListen; Reason Additional RCON clients can now connect
Warning; Warning Message An RCON-related warning string

ERROR

This header is currently unused, but was used in previous versions of RCON and may be used again in the future.

Trivia

  • RCON v3 used a non-breaking space (nbsp/0xA0) was the token deliminator despite it not being in the standard ASCII range. This lead to inconsistent results between servers, and was therefore replaced with the Start of Text character (STX/0x02) in RCON v4. In order to retain in-game readability of RCON output, the deliminator is replaced with a space before being displayed.