These are utility cogs explicitly intended for SS13 servers leveraging off of the /tg/ and BeeStation 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 BeeStation schemed database
Requires: aiomysql>=0.0.20 --
|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
|CCLookup||Checks the shared CentCom database for information on a given ckey
Requires: httpx>=0.14.1 --
|DMCompile||Compiles and runs DM code
Requires: httpx>=0.14.1 --
* Requires additional setup, see DMCompile for more information
|VerifyCkey||Allows CKEY verification in Discord
* Requires the following codebase changes: https://github.com/BeeStation/BeeStation-Hornet/pull/2163
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 BeeStation 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 aiomysql where
[p] is your prefix.
The status cog operates by probing the server with a
[p]status request and then parses that information out in a readable format, see the below example on how that might look.
The status cog is also capable of displaying current round information within a set channel's topic description. This live status report will automatically update itself every 5-minutes.
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) var/round_id = GLOB.round_id if(config && bot_ip) var/query = "http://[bot_ip]/?serverStart=1&roundID=[round_id]&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. The status cog can currently check for new round notifications, messages directed at the admin channel, and mentor tickets.
For any admin notices (e.g. round ending events or ahelps) ensure that the
admin channel is set. If you have a mentorHelp system in place, you can send mentor tickets to discord using the
mentor channel instead. Note:
admin notices will provide an
@here ping if there aren't any admins currently online when the announcement is sent. Notices using the
mentor channel will not provide
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) . = list() .["players"] = GLOB.clients return list2params(.) /datum/world_topic/getadmins keyword = "getAdmins" /datum/world_topic/getadmins/Run(list/input) . = list() var/list/adm = get_admin_counts() var/list/presentmins = adm["present"] var/list/afkmins = adm["afk"] .["admins"] = presentmins .["admins"] += afkmins return list2params(.)
A simple lookup cog that utilizes the CentCom shared database to find bans for a given ckey. No setup required!
The DMCompile cog parses a codeblock containing DM code, and sends it to an external environment which will compile, run, and generate an output for the provided code.
In order to use this cog, you will need to either use a preestablished environment or host your own using this listener: https://github.com/BeeStation/dmcompile-listener.
Basic code can be compiled without defining a primary proc, however, advanced functions or code requiring indents must have an explicitly defined
proc/main(). The code must be contained within a codeblock regardless of the code's complexity.
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.