These are utility cogs explicitly intended for SS13 servers leveraging off of the /TG/ codebases. The idea is to provide a clean and convenient way to push data from the game to discord all while enjoying the many other benefits of having a Red Bot V3 instance. These cogs may work for other codebases, however, this has not been tested and it may require some added effort during setup.
|GetNotes||Pulls player notes from an SS13 /TG/ schemed database
Requires: mysql-connector-python>=8.0 --
|Status||Obtains the current status of a hosted SS13 round and pertinent admin pings (e.g. Ahelps, round ending events, custom pings)
* Requires additional setup, see Additional Functions for more information
Setup for your redbot V3 instance is a straightforward process.
- Add this repo/branch with
[p]repo add ss13-cogs https://github.com/crossedfall/crossed-cogs ss13/master
- Install the cogs you want to use with
[p]cog install ss13-cogs getnotesand
[p]cog install ss13-cogs status
- Load your new cogs with
[p]load status getnotes
Any reference to [p] should be replaced with your prefix
In order to fully utilize the GetNotes cog you will need to have a fully configured player database for your SS13 server configured using the /TG/ schema.
Once you have a database configured, you will need to provide a user that the bot can use to query said database. It is highly recommended that you ensure this user only has
SELECT privileges and is separate from the one your server is configured to use.
Note: While the required
mysql-connector-python package should be installed automatically.. If you get an error when using the notes cog where the
mysql-connector-python module wasn't found, please ensure it is installed either by using your favorite terminal or (with the debug flag enabled on your bot)
[p]pipinstall mysql-connector-python where
[p] is your prefix.
The status cog operates by probing the server with a
?status request and then parses that information out in a readable format, see the below example on how that might look.
In addition to the above, the status cog also has a listening function to serve incoming game data provided by your SS13 server. Currently, this cog serves new round and administrative notices using the following subsystem. In order for the status cog to receive said notifications, this controller subsystem will need to be added into your codebase and loaded into your dme file. (
SUBSYSTEM_DEF(redbot) name = "Bot Comms" flags = SS_NO_FIRE /datum/controller/subsystem/redbot/Initialize(timeofday) var/comms_key = CONFIG_GET(string/comms_key) var/bot_ip = CONFIG_GET(string/bot_ip) if(config && bot_ip) var/query = "http://[bot_ip]/?serverStart=1&key=[comms_key]" world.Export(query) return ..() /datum/controller/subsystem/redbot/proc/send_discord_message(var/channel, var/message, var/priority_type) var/bot_ip = CONFIG_GET(string/bot_ip) var/list/adm = get_admin_counts() var/list/allmins = adm["present"] . = allmins.len if(!config || !bot_ip) return if(priority_type && !.) send_discord_message(channel, "@here - A new [priority_type] requires/might need attention, but there are no admins online.") //Backup message should redbot be unavailable var/list/data = list() data["key"] = CONFIG_GET(string/comms_key) data["announce_channel"] = channel data["announce"] = message world.Export("http://[bot_ip]/?[list2params(data)]")
A new option (
BOT_IP) within the comms.txt config file (or within your legacy config file) will also have to be added. The
BOT_IP should be the ip and listening port of your bot. For example,
## Communication key for receiving data through world/Topic(), you don't want to give this out COMMS_KEY SomeKeyHere [...] ## Bot IP:Port for discord notifications BOT_IP 127.0.0.1:8081
In order to process the new config option, the following entry must be added to the bottom of the comms.dm controller file:
[...] /datum/config_entry/string/medal_hub_password protection = CONFIG_ENTRY_HIDDEN /datum/config_entry/string/bot_ip
Once the above is added into your codebase, you can send administrative notices directly into discord by calling the
send_discord_message(var/channel, var/message, var/priority_type) function. Currently, the status cog will only check for new round notifications and messages directed at the admin channel. Any messages sent should ensure that the first parameter is set to
admin. Future development may grant added flexibility here.
If, for example, you want to send new ticket admin notifications to discord you can do so using the following method within your if(is_bwoik) statement.
SSredbot.send_discord_message("admin", "Ticket #[id] created by [usr.ckey] ([usr.real_name]): [name]", "ticket")
As another example, if you wanted to show a round ending event (like the supermater shard delaminating), you can do so by adding a very similar method within the function handling the event, in this case the shard delaminating event.
SSredbot.send_discord_message("admin","The supermatter has just delaminated.","round ending event")
The bot will automatically provide an
@heremention in the designated admin channel, which can be adjusted with the
[p]setstatus adminchannelcommand (where [p] is your prefix). It is recommend to create an admin monitoring channel where the bot has permissions to mention and post updates.
In order to serve messages received by your game server, you will need to ensure that the
comms_keyfor the bot and the server are the same. The bot will automatically drop any messages sent that do not contain your
comms_key. This setting can be found within your config file
[p]adminwho commands will output a list of player/admin ckeys respectively. In order to use these functions you will need to add the below entries at the bottom of your world_topic.dm file. Using the commands without the below topics will cause the bot to report "0 players" whenever either command is used. This will not effect the player/admin counts in the status report, however.
/datum/world_topic/whois keyword = "whoIs" /datum/world_topic/whois/Run(list/input) /var/list/s = list() s["players"] = GLOB.clients return list2params(s) /datum/world_topic/getadmins keyword = "getAdmins" /datum/world_topic/getadmins/Run(list/input) var/list/s = list() var/list/adm = get_admin_counts() var/list/presentmins = adm["present"] var/list/afkmins = adm["afk"] s["admins"] = presentmins s["admins"] += afkmins return list2params(s)
For questions or concerns, feel free to submit a new issue. I will make my best effort to address any concerns/feedback provided within a reasonable amount of time.