A discord bot that integrates with the CFTools Cloud API.
MIT License
⚠️With version 2 of this discord bot a lot of changes will be introduces onto how this tool works, how it is configured and what requirements need to be fulfilled to use it. DO NOT update your installation if you did not read through the documentation and changed the necessary configuration and pre-requisites.
Provides a Discord bot to interact with the CFTools Cloud data which is exposed through the API.
There are basically two ways to run and configure this discord bot:
The easiest method to install and use this bot is by running it in a docker container. I suggest to use docker-compose
for that, however, starting the container with docker run
should be fine as well.
version: "3"
services:
serviceName:
image: droidwiki/cftools-discord
restart: unless-stopped
volumes:
- ./config.json:/app/config.json
# You need more configuration here, look at the Configuration section
You can run as many containers as you want, one container per game server you want to track.
The bot natively supports to be deployed on Heroku. However, because of how Heroku works, you need to do some manual steps for your first-time setup as well. Follow this guide to deploy the bot on Heroku. The guide assumes you've installed the heroku cli, as well as git already. Follow the Heroku guide to setup your local environment if you did not do that already.
git clone https://github.com/FlorianSW/cftools-discord.git
heroku create
config.json
configuration file (e.g. by copying the config.example.json
file) and configure as needed (see below)config.json
to the git repository: git add -f config.json
(you need to use the -f
parameter as the config file is ignored)git commit -m 'Add bot configuration'
git push heroku main
Resources
tabweb
dyno and enable the worker
dynoYou can also clone this repository, build the project on your own and start the resulting JavaScript code directly. You
need to have nodejs
as well as npm
installed.
git clone https://github.com/FlorianSW/cftools-discord.git
cd cftools-discord
npm ci && npm run build
npm start
The bot uses a configuration file in JSON, which path can be specified with the CONFIG_FILE
environment variable.
When running the bot with the official docker image, this environment variable is pre-set to /app/config.json
, the easiest would be to mount/bind a local configuration file to this path.
The contents of the JSON file can be taken from the example (config.example.json
) of this repository.
In the configuration file, there's a section servers
where you can configure one or multiple servers the bot should serve.
The application you configured with the cftools
configuration needs to have a grant to all servers you specify in this servers
section.
Each server required a name
, which is used by your users when talking with the bot, so keep it short to ensure a good experience for your community.
You can configure available commands for each server with the commands
property.
It is an object where the key is the lowercase command the user will use as a discord application command, and the value is the configuration of the command (if any), or an empty object.
Check the list of available commands to know what commands you can use as the key in this configuration.
To disable a command, simply remove the command from the object.
Currently, the following commands are available:
haspriority
: Checks if the provided Steam ID has an entry in the priority queue list of the server.
Possible responses:
leaderboard
: Returns a leaderboard of most kills for the specified server.
Possible responses:
Configuration options:
defaultStat
: The statistic that should be used to render the leaderboard when the user did not request a specific oneallowedStats
: An array of available/allowed statistics.numberOfPlayers
: The number of maximal entries rendered in the leaderboard (defaults to 7).details
: Prints some general server information, like the current time, players online, etc.
Possible responses:
playerstats
: Prints statistics about the player associated with the provides Steam ID.
Possible responses:
If you want the bot to manage the presence/activity of the bot user within your discord, you may enable it with the discord.presence
setting.
The default is false
, which disables this feature and therefore allows potential other bots to use this activity (e.g. to display the current player count on a server).
To enable this feature, configure it like in this example:
{
// ...
"discord": {
// ...
"presence": {
"type": "WATCHING",
"text": "go2tech.de"
}
}
}
The type
can be any valid type for a discord presence, at the time of this writing one of:
While the text
parameter is a freetext field (which may get truncated by discord if to long).
The bot registers all available commands (of all servers) as discord slash commands (also known as application commands or simply commands).
A user can interact with them by typing a /
and selecting the desired command. The required and optional parameters for that specific command will be shown and requested by discord before the user can send the command to get a response.
Slash commands can not be used by everyone. Make sure that you give the roles and users who should be able to use slash commands the necessary rights (either on a specific channel or for your whole guild.
This bot itself does not have a feature to show the count of currently active players on the server in the Bot status (activity). It would also not work in a multi-server setup (where this bot serves multiple different servers). If you want to show the player count of your server in the discord bot, take a look into my Discord Player Count bot. It supports several sources for the player count, including CFTools Cloud.
If a feature, command or something is missing, feel free to open an issue or even a pull request :)