{"id":17347903,"url":"https://github.com/floriansw/cftools-discord","last_synced_at":"2025-08-05T12:15:04.929Z","repository":{"id":63140152,"uuid":"371995620","full_name":"FlorianSW/cftools-discord","owner":"FlorianSW","description":"A discord bot that integrates with the CFTools Cloud API.","archived":false,"fork":false,"pushed_at":"2023-08-15T19:59:53.000Z","size":831,"stargazers_count":5,"open_issues_count":2,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2023-08-15T21:14:58.857Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FlorianSW.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.paypal.com/donate?hosted_button_id=C2EYFV3G8Y8P6"]}},"created_at":"2021-05-29T14:36:22.000Z","updated_at":"2023-05-02T17:37:53.000Z","dependencies_parsed_at":"2023-01-23T13:55:16.016Z","dependency_job_id":null,"html_url":"https://github.com/FlorianSW/cftools-discord","commit_stats":null,"previous_names":[],"tags_count":3,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianSW%2Fcftools-discord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianSW%2Fcftools-discord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianSW%2Fcftools-discord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FlorianSW%2Fcftools-discord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FlorianSW","download_url":"https://codeload.github.com/FlorianSW/cftools-discord/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219843179,"owners_count":16556510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-15T16:50:32.685Z","updated_at":"2024-10-15T16:50:33.217Z","avatar_url":"https://github.com/FlorianSW.png","language":"TypeScript","funding_links":["https://www.paypal.com/donate?hosted_button_id=C2EYFV3G8Y8P6"],"categories":[],"sub_categories":[],"readme":"# CFTools Cloud Discord bot\n\n[![Docker Pulls](https://img.shields.io/docker/pulls/droidwiki/cftools-discord?style=flat-square)](https://hub.docker.com/r/droidwiki/cftools-discord)\n[![Discord](https://img.shields.io/discord/729467994832371813?color=7289da\u0026label=Discord\u0026logo=discord\u0026logoColor=ffffff\u0026style=flat-square)](https://go2tech.de/discord)\n\n\u003e ⚠️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.\n\u003e **DO NOT** update your installation if you did not read through the documentation and changed the necessary configuration and pre-requisites. \n\nProvides a Discord bot to interact with the CFTools Cloud data which is exposed through the API.\n\n## Installation and usage\n\nThere are basically two ways to run and configure this discord bot:\n\n* as a docker container\n* as a plain nodejs app\n\n### Start the bot\n\n#### Run as a docker conatiner\n\nThe easiest method to install and use this bot is by running it in a docker container. I suggest to use docker-compose\nfor that, however, starting the container with `docker run` should be fine as well.\n\n```yaml\nversion: \"3\"\n\nservices:\n  serviceName:\n    image: droidwiki/cftools-discord\n    restart: unless-stopped\n    volumes:\n      - ./config.json:/app/config.json\n    # You need more configuration here, look at the Configuration section\n```\n\nYou can run as many containers as you want, one container per game server you want to track.\n\n#### Run on Heroku\n\nThe bot natively supports to be deployed on Heroku.\nHowever, because of how Heroku works, you need to do some manual steps for your first-time setup as well.\nFollow this guide to deploy the bot on Heroku.\nThe guide assumes you've installed the heroku cli, as well as git already.\nFollow [the Heroku guide](https://devcenter.heroku.com/articles/getting-started-with-nodejs#set-up) to setup your local environment if you did not do that already.\n\n1. Clone this repository: `git clone https://github.com/FlorianSW/cftools-discord.git`\n2. Create a heroku app: `heroku create`\n3. Add a `config.json` configuration file (e.g. by copying the `config.example.json` file) and configure as needed (see below)\n4. Add the `config.json` to the git repository: `git add -f config.json` (you need to use the `-f` parameter as the config file is ignored)\n5. Commit the configuration changes: `git commit -m 'Add bot configuration'`\n6. Push the app to heroku: `git push heroku main`\n7. Go to the Heroku dashboard and open the newly created app\n8. Navigate to the `Resources` tab\n9. Disable the `web` dyno and enable the `worker` dyno\n\n#### Run as a plain nodejs app\n\nYou can also clone this repository, build the project on your own and start the resulting JavaScript code directly. You\nneed to have `nodejs` as well as `npm` installed.\n\n* Clone the repository: `git clone https://github.com/FlorianSW/cftools-discord.git`\n* Change to the cloned repository: `cd cftools-discord`\n* Build the project: `npm ci \u0026\u0026 npm run build`\n* Start the bot: `npm start`\n* Configure the bot with the necessary configuration\n\n### Configure the bot\n\nThe bot uses a configuration file in JSON, which path can be specified with the `CONFIG_FILE` environment variable.\nWhen 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.\n\nThe contents of the JSON file can be taken from the example (`config.example.json`) of this repository.\n\n#### Configuring servers\n\nIn the configuration file, there's a section `servers` where you can configure one or multiple servers the bot should serve.\nThe application you configured with the `cftools` configuration needs to have a grant to all servers you specify in this `servers` section.\n\nEach 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.\n\nYou can configure available commands for each server with the `commands` property.\nIt 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.\nCheck the list of available commands to know what commands you can use as the key in this configuration.\nTo disable a command, simply remove the command from the object.\n\n#### Available commands\n\nCurrently, the following commands are available:\n\n* `haspriority`: Checks if the provided Steam ID has an entry in the priority queue list of the server.\n\n  _Possible responses_:\n  * Message that the player with the steam ID does not have priority queue for the server\n  * Message indicating that the player has priority queue for the server and the date when it expires\n  * Message indicating that the player has priority queue for the server and that it never expires\n\n* `leaderboard`: Returns a leaderboard of most kills for the specified server.\n\n  _Possible responses_:\n  * A leaderboard with up to 7 leaderboard entries, sorted descending starting with the player with the most kills.\n    Shows kills and deaths for each player as well.\n  * A message indicating that there is no data available to generate the leaderboard (used when CFTools Cloud did not return a leaderboard)\n  \u003cbr\u003e\n    \n  _Configuration options_:\n  * `defaultStat`: The statistic that should be used to render the leaderboard when the user did not request a specific one\n  * `allowedStats`: An array of available/allowed statistics.\n    This list needs to contain only known statistic values (see the example config for available ones).\n    If the user requests a statistic, which is not listed in this allow-list, no leaderboard will be rendered.\n  * `numberOfPlayers`: The number of maximal entries rendered in the leaderboard (defaults to 7).\n\n* `details`: Prints some general server information, like the current time, players online, etc.\n\n  _Possible responses_:\n  * A panel with a summary of available, general information about the server\n  * An error message explaining that the server could not be found in CFTools Cloud\n  \u003cbr\u003e\n\n* `playerstats`: Prints statistics about the player associated with the provides Steam ID.\n\n  _Possible responses_:\n  * A panel with a summary of available statistics about the player\n  * An error message explaining that the Steam ID could not be found in CFTools Cloud\n  \u003cbr\u003e\n\n### Setting the presence/activity in discord\n\nIf 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.\nThe 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).\n\nTo enable this feature, configure it like in this example:\n\n```json\n{\n  // ...\n  \"discord\": {\n    // ...\n    \"presence\": {\n      \"type\": \"WATCHING\",\n      \"text\": \"go2tech.de\"\n    }\n  }\n}\n```\n\nThe `type` can be any valid type for a discord presence, at the time of this writing one of:\n- PLAYING\n- STREAMING\n- LISTENING\n- WATCHING\n- CUSTOM_STATUS\n- COMPETING\n\nWhile the `text` parameter is a freetext field (which may get truncated by discord if to long).\n\n## Usage\n\nThe bot registers all available commands (of all servers) as discord slash commands (also known as application commands or simply commands).\nA 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.\n\nSlash 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.\n\n## Show the player count of the server in the status of the bot\n\nThis bot itself _does not_ have a feature to show the count of currently active players on the server in the Bot status (activity).\nIt would also not work in a multi-server setup (where this bot serves multiple different servers).\nIf you want to show the player count of your server in the discord bot, take a look into my [Discord Player Count bot](https://github.com/FlorianSW/discord-player-count-bot).\nIt supports several sources for the player count, including CFTools Cloud.\n\n# Contributions\n\nIf a feature, command or something is missing, feel free to open an issue or even a pull request :)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloriansw%2Fcftools-discord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloriansw%2Fcftools-discord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloriansw%2Fcftools-discord/lists"}