Deadbot

Deadbot is an open-source automation tool for extracting and processing game data for Valve's upcoming hero shooter, Deadlock. Its primary purpose is to accurately populate and maintain the Deadlock Wiki.

Key Features

• Data Extraction: Downloads the latest game files by cloning the SteamDB GameTracking-Deadlock repository and using DepotDownloader for non-English localizations.
• Decompilation: Processes raw game assets (.vdata_c, localization files) into structured JSON.
• Data Parsing: Parses decompiled files to extract detailed stats for heroes, abilities, items, and NPCs.
• Changelog Aggregation: Fetches official patch notes and in-game "Hero Lab" changes.
• Wiki Integration: Formats game data as JSON and changelogs into wikitext and uploads them directly to the Deadlock Wiki.

Want to contribute? Deadbot is a community-driven project and we're always looking for new contributors. Find out how you can help!

---

Project Architecture

Deadbot uses a two-repository system to separate logic from data:

1. deadbot (This Repository): Contains all the Python code for decompiling, parsing, and uploading data.
2. deadlock-data: Stores the JSON, CSV, localization, and changelog files produced by this tool. Keeping data in a separate repository allows for clean, version-controlled tracking of game data changes over time.

The data flow is as follows: SteamDB GameTracking Repo → Deadbot (Parse) → deadlock-data Repository → Deadlock Wiki

---

Usage

The recommended way to use Deadbot is by downloading the pre-built executable. This method does not require Python, Poetry, or any other development tools.

1. Download the executable for your operating system from the latest release.

2. (On macOS/Linux) Make the file executable: chmod +x ./deadbot

3. Run commands from your terminal. For example, to parse a local Deadlock installation:

   # On macOS/Linux
   ./deadbot --dldir "/path/to/Deadlock" --parse
   
   # On Windows
   .\deadbot.exe --dldir "C:\Path\To\Deadlock" --parse

Developer Setup

Prerequisites

• Git
• Python 3.11+
• Poetry (Python dependency manager)

Installation

1. Clone the repository:

   git clone https://github.com/deadlock-wiki/deadbot.git
   cd deadbot

2. Install dependencies using Poetry:

   poetry install

3. Set up pre-commit hooks (for development):

   poetry run pre-commit install

4. Configure your environment (Optional): You can create a .env file to configure the bot's behavior.

   cp .env.example .env

   Then, edit the .env file with your desired paths and credentials.

   Variable	Example Value	Required?	Description
   DEADLOCK_DIR	C:\Steam\common\Deadlock	❌ (Defaults to ./game-data)	Path to local game files, or destination for downloaded files.
   STEAM_USERNAME	mySteamLogin	❌ (For non-English parsing)	Your Steam account username.
   STEAM_PASSWORD	mySteamPassword	❌ (For non-English parsing)	Your Steam account password.
   OUTPUT_DIR	../deadlock-data/data/current	❌ (Defaults to ./output-data)	Where the parsed data files will be saved.
   DEPOT_DOWNLOADER_CMD	C:\Tools\DepotDownloader.exe	❌ (For non-English parsing)	Path to the DepotDownloader executable.

   For a full list of all parameters, see the Parameters section below.

Run Commands

The simplest way to run the bot is by using poetry run deadbot, which will use your .env file for configuration.

You can override any .env setting by providing command-line flags. Here are a few examples:

1. Parsing Existing Local Game Files

# For Linux/macOS
DEADLOCK_DIR="/path/to/Steam/steamapps/common/Deadlock" poetry run deadbot --parse

# For Windows PowerShell
$env:DEADLOCK_DIR="C:\Program Files (x86)\Steam\steamapps\common\Deadlock"; poetry run deadbot --parse

2. Downloading and Parsing Game Files

# This will clone game files into the DEADLOCK_DIR specified in your .env file
poetry run deadbot --import_files --parse

---

Parameters

Section	Argument	Description	Environment Var
General	-h, --help	Show help message and exit.
	-g, --dldir DLDIR	Directory of Deadlock game files.	DEADLOCK_DIR
	-w, --workdir WORKDIR	Directory for temporary working files.	WORK_DIR
	-n, --inputdir INPUTDIR	Input directory for changelogs and wiki pages.	INPUT_DIR
	-o, --output OUTPUT	Output directory for generated files.	OUTPUT_DIR
	--english-only	Only parse English localizations.	ENGLISH_ONLY
	--force	Forces decompilation even if game files and workdir versions match.
	-v, --verbose	Enable verbose logging for detailed output.
Steam Config	--steam_username STEAM_USERNAME	Steam username for downloading game files.	STEAM_USERNAME
	--steam_password STEAM_PASSWORD	Steam password for downloading game files.	STEAM_PASSWORD
	--depot_downloader_cmd DEPOT_DOWNLOADER_CMD	Path to the DepotDownloader executable directory.	DEPOT_DOWNLOADER_CMD
	--manifest_id MANIFEST_ID	Manifest ID to download. Defaults to latest. Browse manifests: SteamDB Depot 1422456	MANIFEST_ID
Bot Actions	-i, --import_files	Import game and localization files using DepotDownloader.	IMPORT_FILES
	-d, --decompile	Decompile Deadlock game files.	DECOMPILE
	-p, --parse	Parse decompiled files into JSON and CSV.	PARSE
	-c, --changelogs	Fetch and parse both forum and local changelogs.	CHANGELOGS
	-u, --wiki_upload	Upload parsed data to the Wiki.	WIKI_UPLOAD
	--dry_run	Run wiki upload in dry-run mode (no actual upload).	DRY_RUN

Docker

You can also run Deadbot using Docker, which is how it's deployed in production.

1. Build the image:

   docker compose build

2. Run the container: Make sure your .env file is configured, as docker-compose will use it to set environment variables inside the container.

   docker compose up

   This command will build the image if it doesn't exist, then start the container and run the bot.

---

Automation (CI/CD)

This project uses GitHub Actions to automate its workflow. The central script is deploy.yaml, which handles the full data processing pipeline.

• Deployment Workflow (deploy.yaml): This is the core pipeline responsible for parsing all game data and committing the results to the deadlock-data repository. It is triggered by pushes to master and develop, manual runs, and by the other automation workflows.
• Auto-Deploy (auto-deploy.yaml): A scheduled action that runs hourly to check for game updates on SteamDB. If an update is found, it triggers the main Deployment Workflow.
• Pull Request Integration: When a PR is opened in deadbot, the Deployment Workflow runs on the feature branch. A corresponding draft PR is then automatically created in deadlock-data to show the impact of the code changes on the parsed output.
• CI Checks (ci.yaml): All PRs are automatically linted and checked to ensure code quality before they can be merged.
• Release Management (release.yaml): Merging to master triggers a release workflow that builds and pushes a new Docker image and creates a versioned GitHub release.

---

Acknowledgements

This project relies on the excellent work of the SteamDB team for tracking and providing access to Deadlock's game files via their GameTracking-Deadlock repository.

---

Contributing

Deadbot is in active development and welcomes new contributors! Whether you're experienced or new to coding, your help is appreciated.

• The best place to get involved is the #wiki-tech channel on The Deadlock Wiki Discord server; ask for contributor access and ping @hariyosaag if you’re not sure where to start.

For those who prefer to jump right in, check out the good first issues to find easy ways to contribute.