Total Battle Automation

Automation tools for reducing repetitive tasks in Total Battle.

The recommended interface is TotalBattleHelper, which provides a GUI for running Citadel and Crypt automation and opening the Citadel configuration tools.

The command-line interfaces remain available for testing, diagnostics, and advanced use.

The automation interacts with the game visually, so the game must be visible and the expected UI elements must be available on screen.

TotalBattleHelper

TotalBattleHelper is the recommended way to run the automation.

You can still start it directly with Python:

python total_battle_helper.py

For normal day-to-day use, Linux and Windows can both be configured so TotalBattleHelper launches like a regular desktop application without opening a terminal.

Linux Application Launcher

From the project directory, run the one-time installer:

python install_total_battle_helper_linux.py

This creates a user application entry for TotalBattleHelper. After installation:

1. Open the Applications menu.
2. Search for TotalBattleHelper.
3. Launch it once.
4. Pin that running application to the dock if desired.

The launcher uses the project's .venv Python environment and starts TotalBattleHelper with no terminal window.

Windows Standalone EXE

Windows can build a standalone TotalBattleHelper.exe launcher with:

.\build_total_battle_helper_windows.ps1

The build script uses PyInstaller from the project's .venv and creates:

TotalBattleHelper.exe

in the project root.

The EXE can be launched directly or pinned to the Windows taskbar. It opens without a PowerShell or Command Prompt window while Citadel, Crypt, and tool subprocesses still use the project's .venv\Scripts\python.exe.

PyInstaller must be installed in the Windows virtual environment before the first build:

python -m pip install pyinstaller

TotalBattleHelper provides four main sections:

• Citadels - run Citadel automation and select run options.
• Crypts - run Crypt automation and select Watchtower Crypt filter behavior.
• Citadel Stacks - open the Citadel stack configuration GUI.
• Troop Catalog - open the troop catalog and troop-ordering GUI.

An Under Development section contains useful tools that are not yet considered part of the fully polished production workflow. Watch Exchange is currently available there.

Automation output is displayed in the Activity area.

Only one Citadel or Crypt automation process can run from TotalBattleHelper at a time. While automation is running, the run settings are locked to prevent accidental changes.

The Stop button requests a graceful shutdown so the active automation can perform its normal cleanup before exiting.

Citadel Controls

The Citadel panel provides:

• Successful launches - stop after this many successful Citadel launches. Leave blank to run without a launch-count limit.
• Loss handling - use each Citadel configuration or override it with Stop, Revive, Delete All, or Delete Silver.
• Apply MAX march speedup - enabled by default.
• Verbose diagnostic output - display detailed automation diagnostics.

Loss handling options:

• Use Citadel Setting - use the configured loss_policy.
• Stop - leave losses untouched and stop before another Citadel is launched.
• Revive - revive all outstanding losses.
• Delete All - permanently remove all outstanding losses.
• Delete Silver - permanently remove Silver Troops and revive remaining protected losses.

Crypt Controls

The Crypt panel provides:

• Successful launches - stop after this many successful Crypt launches. Leave blank to run continuously.
• Crypt Type - Leave As Is, Common, Rare, or Epic.
• Apply MAX march speedup - enabled by default. Disable it to let Carter complete the march normally.
• Verbose diagnostic output - display detailed automation diagnostics.

Leave As Is keeps the current Watchtower Crypt filters unchanged.

Selecting Common, Rare, or Epic sets the Watchtower filters for that Crypt type.

When MAX march speedup is disabled, Carter is still tracked until his natural return. Another Crypt is not launched while Carter is still away.

Crypts

crypt.py runs the production Crypt loop through the Watchtower.

# Run continuously
python crypt.py

# Stop after 10 successful Crypt launches
python crypt.py --count 10

# Select a specific Watchtower Crypt type
python crypt.py --type common
python crypt.py --type rare
python crypt.py --type epic

# Short form
python crypt.py -t rare

# Do not apply MAX march speedup
python crypt.py --no-speedup

# Show detailed diagnostic output
python crypt.py --verbose
python crypt.py -v

# Flags can be combined
python crypt.py --type rare --count 10 --no-speedup --verbose

If --type is omitted, the current Watchtower Crypt filters are left unchanged.

If --type common, --type rare, or --type epic is supplied, the automation selects that Crypt type in the Watchtower.

The Crypt loop finds a Crypt through the Watchtower, launches Carter, applies MAX march speedup by default, waits for Carter to return, and repeats. While waiting, it also clicks Clan Help when available.

With --no-speedup, MAX is not applied. Carter is still tracked until his return before another Crypt can be launched.

Citadels

citadel.py runs the production Citadel loop.

# Run continuously
python citadel.py

# Stop after 10 successful launches
python citadel.py --count 10

# Use a different Citadel configuration
python citadel.py --config my_citadel_stacks.json

# Do not apply MAX march speedup
python citadel.py --no-speedup

# Override Citadel loss handling for this run
python citadel.py --loss stop
python citadel.py --loss revive
python citadel.py --loss delete
python citadel.py --loss silver

# Show detailed diagnostic output
python citadel.py --verbose
python citadel.py -v

# Flags can be combined
python citadel.py --count 10 --loss silver --verbose
python citadel.py --count 10 --no-speedup --loss revive --verbose

The Citadel loop finds a supported Citadel through the Watchtower, confirms its type, loads its configured troop stack, launches the attack, applies MAX march speedup by default, tracks the active march, handles configured losses, and repeats.

While a Citadel march is active, the automation continues checking for Clan Help.

For revive, dismiss, and dismiss_silver policies, it also periodically checks for outstanding Citadel losses while the march is still active. If losses are found, they are handled according to the selected policy, the automation returns to the World map, and tracking of the same active march continues.

For the stop policy, losses are deliberately left untouched while the march remains active. After the march finishes, outstanding losses are detected and the automation stops before launching another Citadel.

Citadel behavior is configured in citadel_stacks.json. Individual troop stacks are stored in citadel_troops/.

Currently supported Citadels:

• Cursed 20
• Cursed 25
• Elven 20
• Elven 25
• Elven 30

Citadel Loss Policies

Each Citadel configuration has a loss_policy.

• stop - stop Citadel automation if outstanding losses are detected.
• revive - revive all outstanding losses before continuing.
• dismiss - permanently remove all outstanding losses before continuing.
• dismiss_silver - permanently remove Silver Troops, then revive any remaining protected losses such as mercenaries, monsters, Heroes, and Captains.

The configured policy is used normally. It can be overridden for an entire citadel.py run with --loss:

python citadel.py --loss stop
python citadel.py --loss revive
python citadel.py --loss delete
python citadel.py --loss silver

The command-line values map to the existing Citadel policies as follows:

• --loss stop -> stop
• --loss revive -> revive
• --loss delete -> dismiss
• --loss silver -> dismiss_silver

When --loss is supplied, it takes precedence over the loss_policy configured for individual Citadels for the duration of that run. Omitting --loss preserves normal per-Citadel configuration.

Examples:

# Run 18 Citadels and revive every loss
python citadel.py --count 18 --loss revive

# Permanently remove Silver Troops and revive protected losses
python citadel.py --count 18 --loss silver

# Permanently remove every outstanding loss
python citadel.py --count 18 --loss delete

Citadel Stack Configuration

The easiest way to manage Citadel troop stacks is through Citadel Stacks in TotalBattleHelper.

The standalone Citadel stack GUI remains available:

python citadel_stack_gui.py

The troop catalog and troop ordering used by Citadel stacks can be managed through Troop Catalog in TotalBattleHelper.

The standalone troop catalog GUI remains available:

python troop_catalog_gui.py

citadel_stack_tool.py provides the command-line configuration interface.

# List configured Citadels
python citadel_stack_tool.py list

# Show a Citadel configuration and troop stack
python citadel_stack_tool.py show elven_30

# Set a troop amount
python citadel_stack_tool.py set elven_30 vulture7 5000

# Remove a troop from a stack
python citadel_stack_tool.py remove elven_30 vulture7

# Set the loss policy
python citadel_stack_tool.py policy elven_30 dismiss

# Enable or disable a Citadel
python citadel_stack_tool.py enable elven_30 on
python citadel_stack_tool.py enable elven_30 off

# Validate all Citadel configuration
python citadel_stack_tool.py validate

Troop Selection

troops.py loads a troop selection from a JSON file while the Battle troop-selection screen is open.

python troops.py my_troops.json

The JSON object maps troop names to quantities.

Login

login.py can log into the game using a JSON credentials file containing username and password.

python login.py credentials.json

# Login and continue to the World map
python login.py --worldmap credentials.json

# Short form
python login.py -w credentials.json

Other Tools

Files prefixed with dev_ are retained development or manual-assist tools. They may be useful for testing, diagnostics, or partially automated workflows, but are not part of the primary production automation interface.

The project also contains sample-capture and development utilities, and experimental tools such as the chest counter. These are not part of the primary production automation interface.

Citadel Hero Frame Requirement

Citadel automation requires the standard/default Hero portrait frame while the automation is running.

Custom, decorative, or event Hero frames can extend visually into the Hero selection-checkbox area on the Battle screen. This can interfere with the image-based safety check that verifies whether the Hero is selected and available before a Citadel march is prepared.

The Citadel automation verifies the Hero and all three Captain selection slots before loading troops. A Citadel is allowed to proceed only when all four slots are positively detected as selected.

If any Hero/Captain slot is still on a march, is not selected, or cannot be classified confidently, the Citadel is not launched and the automation recycles through the World map and Watchtower.

Required setup: Set the Hero portrait frame back to the standard/default frame before running Citadel automation.