Guide for Bot Developers

# TCP Logging In previous versions of SSGM game events were logged to three separate log files: renlog, gamelog and ssgmlog. This gradually ate up disk space on the server and could cause the server to lag slightly while waiting on disk writes due to the single threaded nature of the Renegade FDS. This logging system is no longer supported under SSGM 4.0 and the gamelog and ssgmlog files will no longer be created, however the renlog file will still be written to disk to allow some limited compatibility with older bots. Instead, SSGM 4.0 supports a new type of logging which server owners based on a TCP connection between the bot and the server. Once connected to the server bots will receive a steady stream of log messages through the connection. In order to ease the process of updating existing bots to the new SSGM logging system it was decided to implement the existing ssgmlog and gamelog messages into the new system in the same format as they used in the old file based logging system. This means that bots can simply point messages to existing parsing procedures without having to significantly rewrite their log handling code. ## Protocol The logging protocol is extremely simple. The first three characters if each message sent through the protocol are digits between 0 and 9 which indicate the message type. The remainder of the message is the log entry. Each message is terminated with the NULL character (0x0). There are 4 built in message types; - 000 - SSGM log messages - 001 - Gamelog messages - 002 - Renlog messages (a copy of everything written to the renlog files) - 003 - Console Output (a copy of everything written to the console, basically a copy of 002 without timestamps) Here are some examples of messages a bot might receive through the TCP connection; ``` 001[14:06:20] POS;VEHICLE;1500000126;GDI_Ceiling_Gun_AGT;-66;21;9;0;100;100 001[14:06:21] POS;SOLDIER;1500000206;CnC_GDI_MiniGunner_0;-12;27;0;179;100;100 003Total current bandwidth usage for players is 85 kilobits per second 002[14:06:22] Total current bandwidth usage for players is 85 kilobits per second 003Westwood Online mode active since 11/08/2010 - 19:06:54 002[19:18:46] Westwood Online mode active since 11/08/2010 - 19:06:54 ``` *Important Note:* For reasons which are too complicated to go into at this point the first line of the player_info response (the column headers) is output with a newline character (0xD) at the front of the line. If your bot needs to parse this line and would choke on that character you should use an appropriate function to strip that character out of any messages before forwarding them for parsing. ## Configuration There are two configuration settings which are relevant to the TCP logging system, both of which are located within the ssgm.ini configuration file in the root directory of the Renegade FDS installation. These settings are; ``` [General] Port=8080 EnableGamelog=true ``` The port parameter defines the port number on which the server should listen for incoming TCP connections to the logging system and should be different from the RenRem and game ports defined in server.ini. Bots should read the port number from this file (or have it provided to them via config settings) to allow them to connect to the server. The EnableGamelog option turns the logging system on or off and must be set to true to enable the logging system. ## Resource Manager SSGM 4.0 uses a new Resource Manager system which allows the map rotation to be changed on the fly without reading and writing configuration files. It also allows mixing and matching mix, pkg and TT package maps within the same rotation. This change means that bots developed prior to SSGM 4.0 will be unable to read the map rotation, generate a list of available maps or set the next map in the rotation on servers running SSGM 4.0. This topic will document how bots should perform all of the above tasks on a server running SSGM 4.0, which can be determined at run time using the sversion console command via RenRem. ### Listing installed maps To get a list of all maps currently installed on a server, which includes mix, pkg and TT package maps, a bot can use the `listgamedefs` console command. This command will print out the following response to renlog; ``` [00:00:00] Available game definitions: [00:00:00] mapname1 [00:00:00] mapname2 [00:00:00] mapname3 [00:00:00] ``` The blank line at the end is always printed and should be used to determine the end of the map list. ### Reading the server rotation SSGM 4.0 uses a JSON-like format configuration file named tt.cfg, located in the root folder of the FDS installation. When the FDS is first loaded the initial server rotation is read from the the rotation: node of this file. The format is; ``` rotation: [ "Map1", "Map2", "Map3" ]; ``` If your bot will change the map rotation *without* restoring the original rotation once the modified map has been loaded then reading this file after restarting your bot will give you the wrong rotation. In this instance you could use the `mlist <n>` console command with n = 0 being the first map in the rotation and n = <numMaps-1> being the last map. You can determine the number of maps in the rotation on the fly by incrementing n until the FDS reports that there is no map in that position. The response to this command are one of the following; ``` The map in position n of the map list is map1 ``` ``` There is no map in position n of the map list ``` ### Setting the next map Bots can set the next map in the rotation by using the `mlistc <n> <map>` command. This command gives no response if successful and prints out the following upon failure; ``` Map map1 not found ``` Your bot can use this command to extend the length of the map rotation beyond the initial size loaded from the tt.cfg file. Attempting to set a map at a position beyond the end of the current length of the rotation will add that map to the index immediately after the end of the rotation, regardless of the index specified.