SS13 Cogs

Overview

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.

Cog	Description
GetNotes	Pulls player notes from an SS13 BeeStation schemed database setnotes - Configuration options for the notes cog notes - Lists all of the notes for a given CKEY findplayer - Searches the database for a player using their CID, IP, or CKEY and outputs an overview of the user. Note: It is recommended to restrict this command to admin specific channels. The results will automatically redact the CID and IP after 5-minutes. playerinfo | ckey - Player friendly version of the findplayer command providing basic user info without providing sensitive information like the CID or IP. alts - Searches for possible alt accounts by comparing entries in the connection_log table. Note: This command can take a long time to complete Requires: aiomysql>=0.0.20 -- pip install aiomysql
Status	Obtains the current status of a hosted SS13 round and pertinent admin pings (e.g. Ahelps, round ending events, custom pings) adminwho - Lists the current admins on the server * players - Lists the current players on the server* setstatus - Configuration options for the status cog status - Displays current round information * Requires additional setup, see Additional Functions for more information
CCLookup	Checks the shared CentCom database for information on a given ckey centcom - Lists bans for a provided ckey ccservers - Lists servers currently contributing to the shared ban database Requires: httpx>=0.14.1 -- pip install httpx
DMCompile	Compiles and runs DM code setcompile - DM Compiler settings listbyond - Lists the available BYOND versions you can compile with compile - Sends formatted code to a compilation environment and returns the results* Requires: httpx>=0.14.1 -- pip install httpx * Requires additional setup, see DMCompile for more information
VerifyCkey	Allows CKEY verification in Discord ckeyauthset - Verification settings deverify - Remove a user's verification status and relating roles getckey - Get the CKEY associated with a specific Discord user identify - (Only works in DMs) Used to link a Discord user to their CKEY verify - Sends verification steps to the user's DMs * Requires the following codebase changes: BeeStation/BeeStation-Hornet#2163

Setup

RedBot:

Setup for your RedBot V3 instance is a straightforward process.

1. Add this repo/branch with [p]repo add ss13-cogs https://github.com/crossedfall/crossed-cogs ss13/master
2. Install the cogs you want to use with [p]cog install ss13-cogs getnotes and [p]cog install ss13-cogs status
3. Load your new cogs with [p]load status getnotes

Any reference to [p] should be replaced with your prefix

---

GetNotes:

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.

FindPlayer / PlayerInfo Screenshots

Notes Screenshot

Alts Screenshot

--

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.

---

Status:

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.

Online	Offline

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. (code/controllers/subsystem/redbot.dm)

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

Usage:

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 @here pings.

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")

Important Notes:

• The bot will automatically provide an @here mention in the designated admin channel, which can be adjusted with the [p]setstatus adminchannel command (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_key for 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

Additional Functions:

The [p]players and [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(.)	

---

CCLookup

A simple lookup cog that utilizes the CentCom shared database to find bans for a given ckey. No setup required!

---

DMCompile:

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.

Compiler Screenshots

---

Contact:

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.

Credits:

• Tigercat2000 for his subsystem template
• The /TG/ community for their efforts on SS13
• The Cog-Creators staff for their work on redbot
• Bobbahbrown for their CentCom API