This repository contains three main components:
- CataBot: A Telegram bot that provides information about the game Cataclysm: Dark Days Ahead (CDDA). It uses pre-processed game data to allow users to search for items, crafting recipes, monster information, and more.
- Changelog Announcer: A tool that monitors the Cataclysm: DDA GitHub repository for new releases and automatically announces them to a specified Telegram chat.
- Download Data: A module responsible for downloading and processing all Cataclysm DDA game definitions (items, recipes, monsters, etc.) into a structured JSON format. This data is then utilized by
CataBotfor its search functionalities.
CataBot is a Telegram bot designed to provide helpful information for players of Cataclysm: Dark Days Ahead.
- Game Information Search: Look up details about in-game items, crafting recipes, monster stats, and more.
- Release Information & Downloads: Get links to download the latest game versions for various platforms (Linux, Windows, macOS, Android). By default, it provides the last experimental version. It can also fetch specific stable releases, platform-specific experimental versions, and releases for the Cataclysm: Bright Nights fork.
- Download game data:
CataBotrelies on game data (items, recipes, monsters, etc.) that is processed by thedownload_datamodule. Ensure you have run this module at least once to generate the necessary data files.- See the
## Download Datasection for instructions on how to run it (python -m download_data).
- Clone the repository:
git clone git@github.com:Tairesh/catabot.git cd catabot - Create and activate a virtual environment:
Note: On Windows, the activation command is
python3 -m venv venv source venv/bin/activatevenv\Scripts\activate. - Install dependencies (within the activated venv):
pip install -r requirements.txt
- Configure the bot token:
- Navigate to the
config/directory. - Copy
config/samples/token.txttoconfig/token.txtand editconfig/token.txtto include your Telegram bot token. - Paste your Telegram bot token into this file. You can obtain a token by talking to the BotFather on Telegram.
- Navigate to the
- Run the bot (from the repository root, with venv active):
python -m catabot
Once the bot is running and you've added it to your Telegram chat, you can use the following commands:
/search <query>or/s <query>: Search for an item, monster, or craft.- Example:
/search spear
- Example:
/item <query>or/i <query>: Specifically search for an item.- Example:
/item survivor_suit
- Example:
/craft <query>or/c <query>or/recipe <query>or/r <query>: Search for a crafting recipe.- Example:
/craft makeshift_knife
- Example:
/disassemble <query>or/disasm <query>or/d <query>or/uncraft <query>or/u <query>: Search for items that can be disassembled from the given item.- Example:
/disassemble radio
- Example:
/monster <query>or/mob <query>or/m <query>: Search for a monster.- Example:
/monster zombie_cop
- Example:
/releaseor/get_release: Get download links for game releases.- Default (and
/release last): Shows links for the latest experimental version across all major platforms (Linux, Windows, macOS, Android). /release stable: Shows links for the latest stable version./release <platform>: Shows links for the latest experimental version for a specific platform. Replace<platform>withlinux,windows,macos, orandroid.- Example:
/release android
- Example:
/release bn: Shows links for the latest version of the Cataclysm: Bright Nights fork.
- Default (and
The Changelog Announcer is a script that monitors the official Cataclysm: DDA GitHub repository for new releases. When a new release is detected, it automatically sends a notification message to a pre-configured Telegram chat.
- Prerequisites: Ensure
catabotis set up and you have its Telegram token and the target chat ID for announcements. - Configuration:
- Telegram Bot Token: This script requires a Telegram bot token. If using the same bot instance as
CataBot, it usesconfig/token.txt. For a different bot, modifychangelog/tgbot.pyto load the token according to your setup (e.g., from a specific file path or an environment variable). - Telegram Chat ID: Edit the
changelog/tgbot.pyscript and set the value of theCHAT_IDvariable to your desired Telegram Chat ID. - GitHub Repository: The script monitors the
CleverRaven/Cataclysm-DDArepository by default. The repository URL is defined inchangelog/github.py(e.g., in a variable likeGITHUB_REPO_URLorAPI_URL) and can be modified there to track a different repository.
- Telegram Bot Token: This script requires a Telegram bot token. If using the same bot instance as
- Dependencies: Make sure all dependencies are installed (refer to
requirements.txt). - Running the announcer:
This will check for new releases once and then exit. For continuous monitoring, you'll need to schedule it using a tool like
python -m changelog
cron(see Deployment section).
The download_data module is a crucial component responsible for fetching and processing game data from the Cataclysm: DDA repositories. It gathers all items, recipes, monster information, and other game definitions, then compiles them into a structured JSON file.
This JSON data is then used by CataBot to provide its search results. Therefore, you must run this module at least once before CataBot can function fully.
To download/update the game data:
- Ensure dependencies are installed:
pip install -r requirements.txt
- Run the script:
This will download the latest game data and create/update the necessary JSON file(s) (e.g., in a
python -m download_data
data/directory, or as specified in the script's output/documentation) whichCataBotwill then access.
It's recommended to re-run this script periodically to keep the game data used by CataBot up-to-date with the latest version of Cataclysm: DDA.
All Python dependencies required for both catabot and the changelog announcer are listed in the requirements.txt file. Install them using pip:
pip install -r requirements.txtTo automatically update game data and check for new releases, you can set up cron jobs to run the download_data and changelog scripts periodically within the project's virtual environment.
-
Ensure your virtual environment is set up as described in the
CataBotsetup section (e.g., in a directory namedvenvwithin your project root). -
Open your crontab for editing:
crontab -e
-
Add new lines to schedule the scripts. For example, to run both scripts every hour:
0 * * * * cd /path/to/your/repo && venv/bin/python -m download_data 0 * * * * cd /path/to/your/repo && venv/bin/python -m changelog
- Important:
- Replace
/path/to/your/repo/in both lines with the absolute path to the directory where you cloned this repository (e.g.,/home/user/catabot/). - The command
venv/bin/pythonassumes your virtual environment is namedvenvand is located directly within your project's root directory. Adjust this path if your virtual environment setup differs (e.g.,myenv/bin/python). - Using
cdensures the commands run from the project's root directory. The-mflag is used to run the installed modulesdownload_dataandchangelog. - Refer to the
crontab.examplefile in this repository for a complete example, which you can adapt.
- Replace
- Important:
-
Save and exit the crontab editor.
This setup will ensure that download_data fetches the latest game definitions and changelog checks for new game releases once every hour.
To ensure catabot runs continuously in the background and restarts automatically on failure or system reboot, you can set it up as a systemd service.
-
Locate the example service file: An example systemd service configuration is provided as
catabot.servicein the root of the repository. -
Review and customize the service file:
- Open
catabot.service. - This file is an example
.servicefile. You will need to adjust paths (likeExecStartandWorkingDirectory) and user information to match your system and repository location. - Ensure the following fields in
/etc/systemd/system/catabot.serviceare correctly set for your environment:Description: A description of the service.ExecStart: This is the most important line. It must specify the command to start the bot using the Python interpreter from your virtual environment and targeting thecatabotmodule. Ensure the path to your repository and the name of your virtual environment directory (venvby default) are correct. For example:(ReplaceExecStart=/path/to/your/repo/venv/bin/python -m catabot/path/to/your/repo/with the absolute path to the project's root directory. If your virtual environment directory is not namedvenvor is not located directly in the project root, update the pathvenv/bin/pythonto point to the correct Python interpreter within your virtual environment.)WorkingDirectory: Set this to the root directory of the cloned repository.User: Set this to the username the bot should run as (e.g.,catabotor your own username).Grou 690C p: Set this to the group the bot process should run under (e.g.,catabotor your own user's group).Restart: Set toalwaysoron-failureto ensure the bot restarts if it crashes.
- Open
-
Copy and edit the service file:
- Copy
catabot.serviceto the systemd directory:sudo cp catabot.service /etc/systemd/system/catabot.service
- Open the copied file for editing to adjust paths and user settings:
sudo nano /etc/systemd/system/catabot.service
- Copy
-
Reload systemd daemon:
sudo systemctl daemon-reload
-
Enable the service to start on boot:
sudo systemctl enable catabot.service -
Start the service immediately:
sudo systemctl start catabot.service
-
Check the service status:
sudo systemctl status catabot.service
View its logs using
journalctl -u catabot.service.
This project is licensed under the terms of the license specified in the LICENSE file in the root of this repository.