Skip to content
ss13/master
Switch branches/tags
Code

Latest commit

* verifyckey: Adds a toggle to use the updated topic system

* verifyckey: slightly better (albeit dirty) runtime handling

* verifyckey: final fixes

* ss13status: Adds support for updated topic handling

* ss13status: error_counter addition fix
546293d

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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: https://github.com/BeeStation/BeeStation-Hornet/pull/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

non-redacted redacted ckey

Notes Screenshot

notes

Alts Screenshot

alts

--

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
1543959022724 1544039500509

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.

topic

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

1544022902014

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

1544023245022

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!

cclookup


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

standard compile advanced compile Using custom versions Compiler Error Compiler Warning


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: