RCON: Difference between revisions
m →DEMO |
→Commands: Filled out the rest of this table. Some of the information about response values isn't accurate pertaining to RCON in its current state, but will be accurate in the near future as we roll out updates. |
||
Line 108: | Line 108: | ||
| Help || [Command] || True || Lists available commands if parameters is empty, command-specific help message otherwise || Provides helpful information about commands | | Help || [Command] || True || Lists available commands if parameters is empty, command-specific help message otherwise || Provides helpful information about commands | ||
|- | |- | ||
| ClientList || | | ClientList || || True || List of players and relevant information || Provides a list of players and some relevant information | ||
|- | |- | ||
| LoadMutator || | | LoadMutator || Mutator || True || Nothing on success, error otherwise || Loads a mutator | ||
|- | |- | ||
| UnloadMutator || | | UnloadMutator || Mutator || True || Nothing on success, error otherwise || Unloads a mutator | ||
|- | |- | ||
| ListMutators || | | ListMutators || || True || List of mutators currently loaded || Lists mutators currently loaded | ||
|- | |- | ||
| HostSay || | | HostSay || Message || True || Nothing on success, error otherwise || Sends an in-game Host message | ||
|- | |- | ||
| HostPrivateSay || | | HostPrivateSay || Player Message || True || Nothing on success, error otherwise || Sends an in-game private message to a player as the host | ||
|- | |- | ||
| Kick || | | Kick || Player [Reason] || True || Nothing on success, error otherwise || Kicks a player from the server, and displays a kick message if specified | ||
|- | |- | ||
| KickBan || | | KickBan || Player [Reason] || True || Nothing on success, error otherwise || Kicks and bans a player from the server, and displays a kick message if specified | ||
|- | |- | ||
| ForceKick || | | ForceKick || Player [Reason] || True || Nothing on success, error otherwise || Forcefully kicks a player from the server, and displays a kick message if specified | ||
|- | |- | ||
| TextMute || | | TextMute || Player || True || Nothing on success, error otherwise || Mutes a player from using any chat mechanisms or starting votes | ||
|- | |- | ||
| TextUnMute || | | TextUnMute || Player || True || Nothing on success, error otherwise || Unmutes a player | ||
|- | |- | ||
| ChangeMap || | | ChangeMap || Location to travel to || True || Nothing on success, error otherwise || Travels the server immediately to the specified level or server | ||
|- | |- | ||
| RecordDemo || | | RecordDemo || || True || Nothing on success, error otherwise || Starts a demo recording | ||
|- | |- | ||
| SwapTeams || | | SwapTeams || || True || || Swaps the players on each team | ||
|- | |- | ||
| EndMap || | | EndMap || || True || Nothing on success, error otherwise || Ends the current match immediately | ||
|- | |- | ||
| ForceNonSeamless || | | ForceNonSeamless || || True || || Unforces non-seamless travel | ||
|- | |- | ||
| ForceSeamless || | | ForceSeamless || || True || || Forces non-seamless travel | ||
|- | |- | ||
| CancelVote || | | CancelVote || Team || True || Nothing on success, error otherwise || Cancels a vote in progress | ||
|- | |- | ||
| MutateAsNone || | | MutateAsNone || Message to pass to mutate() || True || Nothing on success, error otherwise || Calls the Mutate() function on mutators, passing None as the instigator | ||
|- | |- | ||
| MutateAsPlayer || | | MutateAsPlayer || Player Message to pass to mutate() || True || Nothing on success, error otherwise || Calls the Mutate() function on mutators, passing a player as the instigator | ||
|- | |- | ||
| HasCommand || | | HasCommand || Trigger || True || "true" or "false" on success, error otherwise || Checks if a command exists | ||
|- | |- | ||
| Map || | | Map || || True || Level name and GUID || Provides information about the current level | ||
|- | |- | ||
| Ping || | | Ping || Message || True || PONG Message || Makes you think you're playing PING/PONG | ||
|- | |- | ||
| Team || | | Team || Player || True || Nothing on success, error otherwise || Changes a player's team as if they used the "Change Teams" button | ||
|- | |- | ||
| Team2 || | | Team2 || Player || True || Nothing on success, error otherwise || Changes a player's team, but the player retains their credits | ||
|- | |- | ||
| ClientVarList || | | ClientVarList || List of tokens || True || List of players and requested information || Provides a list of players in the match and information based on the specified parameters | ||
|- | |- | ||
| BotList || | | BotList || || True || List of bots and relevant information || Provides a list of bots in the match and relevant information | ||
|- | |- | ||
| BotVarList || | | BotVarList || List of tokens || True || List of bots and requested information || Provides a list of bots in the match and information based on the specified parameters | ||
|- | |- | ||
| PlayerInfo || | | PlayerInfo || Player || True || Information requested about a player || Provides information about a specific player | ||
|- | |- | ||
| MineLimit || | | MineLimit || || True || <nowiki>Mine Limit [ ... | Team Name | Team Mine Limit ]</nowiki> || Provides information about the mine limits | ||
|- | |- | ||
| VehicleLimit || | | VehicleLimit || || True || <nowiki>Vehicle Limit [ ... | Team Name | Team Vehicle Limit ]</nowiki> || Provides information about the vehicle limits | ||
|- | |- | ||
| ChangeName || | | ChangeName || Player NewName || True || Nothing on success, error otherwise || Changes a player's name | ||
|- | |- | ||
| ServerInfo || | | ServerInfo || Optional list of tokens || True || Information about the server || Provides information about the server | ||
|- | |- | ||
| GameInfo || | | GameInfo || Optional list of tokens || True || Information about the game || Provides information about the match | ||
|- | |- | ||
| BuildingInfo || | | BuildingInfo || || True || List of buildings and relevant information || Provides information about the buildings in the match | ||
|- | |- | ||
| Rotation || | | Rotation || || True || List of the levels in rotation and their GUIDs || Provides information about the level rotation | ||
|- | |- | ||
| MineBan || | | MineBan || Player || True || Nothing on success, error otherwise || Bans a player from mining | ||
|- | |- | ||
| MineUnban || | | MineUnban || Player || True || Nothing on success, error otherwise || Unbans a player from mining | ||
|- | |- | ||
| TeamInfo || | | TeamInfo || List of tokens || True || Information about a team on success, message starting with "Error:" otherwise || Provides information about a team based on the parameters | ||
|- | |- | ||
| SpectateMode || | | SpectateMode || Player || True || Nothing on success, error otherwise || Puts a player in spectator mode | ||
|- | |- | ||
| NormalMode || | | NormalMode || Player || True || Nothing on success, error otherwise || Puts a player in normal mode | ||
|- | |- | ||
| AddMap || | | AddMap || Level name || True || Nothing on success, error otherwise || Adds a level to the rotation | ||
|- | |- | ||
| RemoveMap || | | RemoveMap || Level name || True || Nothing on success, error otherwise || Removes a level from the rotation | ||
|- | |- | ||
| Kill || | | Kill || Player || False || Nothing on success, error otherwise || Kills a player's pawn | ||
|- | |- | ||
| GiveCredits || | | GiveCredits || Player Amount || False || Nothing on success, error otherwise || Gives a player credits | ||
|- | |- | ||
| Disarm || | | Disarm || Player || False || Nothing on success, error otherwise || Disarms all of a player's deployed weapons | ||
|- | |- | ||
| DisarmBeacon || | | DisarmBeacon || Player || False || Nothing on success, error otherwise || Disarms all of a player's deployed beacons | ||
|- | |- | ||
| DisarmC4 || | | DisarmC4 || Player || False || Nothing on success, error otherwise || Disarms all of a player's deployed C4 | ||
|} | |} | ||
Revision as of 00:20, 10 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:
- Process incoming data into lines (split on newline; no CR is included)
- Process tokens in each line into an array
- Process each token for escaped Unicode sequences
- 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:
- Client connects to Server
- Server sends version information
- Client sends authentication request
- 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 and 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>. These commands can also be executed by administrators in-game by using the admin console command (example: admin help).
Command | Parameters | Fair | Response | Description |
---|---|---|---|---|
Help | [Command] | True | Lists available commands if parameters is empty, command-specific help message otherwise | Provides helpful information about commands |
ClientList | True | List of players and relevant information | Provides a list of players and some relevant information | |
LoadMutator | Mutator | True | Nothing on success, error otherwise | Loads a mutator |
UnloadMutator | Mutator | True | Nothing on success, error otherwise | Unloads a mutator |
ListMutators | True | List of mutators currently loaded | Lists mutators currently loaded | |
HostSay | Message | True | Nothing on success, error otherwise | Sends an in-game Host message |
HostPrivateSay | Player Message | True | Nothing on success, error otherwise | Sends an in-game private message to a player as the host |
Kick | Player [Reason] | True | Nothing on success, error otherwise | Kicks a player from the server, and displays a kick message if specified |
KickBan | Player [Reason] | True | Nothing on success, error otherwise | Kicks and bans a player from the server, and displays a kick message if specified |
ForceKick | Player [Reason] | True | Nothing on success, error otherwise | Forcefully kicks a player from the server, and displays a kick message if specified |
TextMute | Player | True | Nothing on success, error otherwise | Mutes a player from using any chat mechanisms or starting votes |
TextUnMute | Player | True | Nothing on success, error otherwise | Unmutes a player |
ChangeMap | Location to travel to | True | Nothing on success, error otherwise | Travels the server immediately to the specified level or server |
RecordDemo | True | Nothing on success, error otherwise | Starts a demo recording | |
SwapTeams | True | Swaps the players on each team | ||
EndMap | True | Nothing on success, error otherwise | Ends the current match immediately | |
ForceNonSeamless | True | Unforces non-seamless travel | ||
ForceSeamless | True | Forces non-seamless travel | ||
CancelVote | Team | True | Nothing on success, error otherwise | Cancels a vote in progress |
MutateAsNone | Message to pass to mutate() | True | Nothing on success, error otherwise | Calls the Mutate() function on mutators, passing None as the instigator |
MutateAsPlayer | Player Message to pass to mutate() | True | Nothing on success, error otherwise | Calls the Mutate() function on mutators, passing a player as the instigator |
HasCommand | Trigger | True | "true" or "false" on success, error otherwise | Checks if a command exists |
Map | True | Level name and GUID | Provides information about the current level | |
Ping | Message | True | PONG Message | Makes you think you're playing PING/PONG |
Team | Player | True | Nothing on success, error otherwise | Changes a player's team as if they used the "Change Teams" button |
Team2 | Player | True | Nothing on success, error otherwise | Changes a player's team, but the player retains their credits |
ClientVarList | List of tokens | True | List of players and requested information | Provides a list of players in the match and information based on the specified parameters |
BotList | True | List of bots and relevant information | Provides a list of bots in the match and relevant information | |
BotVarList | List of tokens | True | List of bots and requested information | Provides a list of bots in the match and information based on the specified parameters |
PlayerInfo | Player | True | Information requested about a player | Provides information about a specific player |
MineLimit | True | Mine Limit [ ... | Team Name | Team Mine Limit ] | Provides information about the mine limits | |
VehicleLimit | True | Vehicle Limit [ ... | Team Name | Team Vehicle Limit ] | Provides information about the vehicle limits | |
ChangeName | Player NewName | True | Nothing on success, error otherwise | Changes a player's name |
ServerInfo | Optional list of tokens | True | Information about the server | Provides information about the server |
GameInfo | Optional list of tokens | True | Information about the game | Provides information about the match |
BuildingInfo | True | List of buildings and relevant information | Provides information about the buildings in the match | |
Rotation | True | List of the levels in rotation and their GUIDs | Provides information about the level rotation | |
MineBan | Player | True | Nothing on success, error otherwise | Bans a player from mining |
MineUnban | Player | True | Nothing on success, error otherwise | Unbans a player from mining |
TeamInfo | List of tokens | True | Information about a team on success, message starting with "Error:" otherwise | Provides information about a team based on the parameters |
SpectateMode | Player | True | Nothing on success, error otherwise | Puts a player in spectator mode |
NormalMode | Player | True | Nothing on success, error otherwise | Puts a player in normal mode |
AddMap | Level name | True | Nothing on success, error otherwise | Adds a level to the rotation |
RemoveMap | Level name | True | Nothing on success, error otherwise | Removes a level from the rotation |
Kill | Player | False | Nothing on success, error otherwise | Kills a player's pawn |
GiveCredits | Player Amount | False | Nothing on success, error otherwise | Gives a player credits |
Disarm | Player | False | Nothing on success, error otherwise | Disarms all of a player's deployed weapons |
DisarmBeacon | Player | False | Nothing on success, error otherwise | Disarms all of a player's deployed beacons |
DisarmC4 | Player | False | Nothing on success, error otherwise | Disarms all of a player's deployed C4 |
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.
Logs follow the following format:
- Token 0 is the primary header
- Token 1 is the secondary header
- 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; | Player | "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; | <"client request by" / "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.