Skip to content
Cogs for redbot v3
Branch: ss13/master
Clone or download
Latest commit 016a4c1 May 1, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
getnotes Removes the alias May 1, 2019
status Adds text wrapping for long map names reported by the status command Apr 14, 2019
.gitignore remove VsCode stuff Jul 9, 2018
LICENSE
README.md
info.json Corrects the mysql-connector requirements for the repo Jan 3, 2019

README.md

SS13 Cogs

Overview

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.

Cog Description
GetNotes Pulls player notes from an SS13 /TG/ 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.

Requires: mysql-connector-python>=8.0 -- pip install mysql-connector-python
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

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 /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.


Status:

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.

Online Offline
1543959022724 1544039500509

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

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

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

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:

You can’t perform that action at this time.