BOAM — Bot On A Mission

index

5 min read

BOAM — Bot On A Mission

v2.5.0 | Documentation | Changelog

AI behaviour modification mod for Menace. Injects per-tile score modifiers during the game’s AI tile evaluation to steer enemy movement. Includes a real-time in-game minimap overlay.

Opt-in features: offline heatmap rendering, battle session recording (player actions + AI decisions + combat outcomes).

Features

FeatureDescription
AI BehaviourConfigurable behaviour nodes that influence enemy AI movement
Tactical MinimapIn-game IMGUI overlay showing unit positions on the captured map background
Heatmap RendererOffline heatmap generation from deferred render jobs — tile scores, decisions, movement
Action LoggingRecords player actions, AI decisions, and combat outcomes to JSONL battle logs
ConfigurationVersioned JSON5 configs with user/mod-default two-tier system

Current Behaviour Nodes

Four configurable nodes run in sequence during each AI actor’s turn, modifying the game’s tile scores to influence movement:

NodeScore targetEffect
RoamingUtilityExplore outward when idle. Suppressed near engagement so other behaviours take over.
RepositionUtilityByAttacksMove toward the closest known opponent at ideal attack range. Uses full AP when firing range is unreachable, reserves AP for attacks when it is.
PackSafetyForm groups around allies. Engaged allies attract harder. Crowd penalty when too dense (suppressed near combat).
InvestigateUtilityChase the last known position of player units that broke line of sight. Triggered by losing LOS on a player unit

Nodes are self-contained: types, keys, config, and registration all live in one file per node. See Adding a Behaviour Node.

All tuning is in behaviour.json5 — no code changes needed to adjust behaviour strength or add presets.

Components

ComponentLocationRuntimeDescription
BOAM-modpacksrc/In-game (MelonLoader/Wine)Harmony patches, minimap overlay, map capture, action forwarding
BOAM-engineboam_tactical_engine/Native (.NET 10, port 7660)Behaviour nodes, heatmap renderer, action logger, icon setup

The BOAM-modpack works standalone — the minimap needs the engine to be run once for setup to generate assets. Start the BOAM-engine only when you want AI behaviours, heatmaps, or action logging.

First time? Follow the Installation Guide.

Downloads

Pre-built engine binaries (Linux and Windows) are available on the Releases page.

Each release includes:

  • BOAM-modpack — C# source (compiled at deploy time by the Menace Modkit)
  • BOAM-tactical-engine — pre-built binaries for Linux and Windows (bundled and slim variants)

The engine is a standalone binary — put it anywhere you like. It finds the game directory automatically via MENACE_GAME_DIR env var or standard Steam install paths. No need to place it inside the game folder.

Prefer to build yourself? See Building from Source.

Install Layout

The BOAM-modpack is deployed inside the game directory. The engine can live anywhere.

Menace/
├── Mods/BOAM/
│   ├── dlls/BOAM.dll              C# bridge (compiled by ModpackLoader)
│   ├── modpack.json               Mod manifest
│   ├── configs/                   Mod default configs (reset on deploy)
│   │   ├── engine.json5           Engine ports, rendering
│   │   ├── behaviour.json5       AI behaviour node chains and tuning presets
│   │   ├── game_events.json5     Active game events and feature gates
│   │   ├── tactical_map.json5     Minimap keybindings, visual defaults
│   │   ├── tactical_map_presets.json5  Display presets (sizes, styles, anchors)
│   │   └── icon-config.json5      Icon generation source mappings
│   ├── start-tactical-engine.sh   Launcher (opens terminal, logs to file)
│   ├── boam-launch.sh(.bat)       Steam launch helper
│   └── logs/                      Engine log
└── UserData/BOAM/
    ├── configs/                   User configs (persistent, checked first)
    ├── icons/                     Generated heatmap/minimap icons
    │   ├── factions/
    │   └── templates/
    └── battle_reports/            Recorded battles (auto-created per session)
        └── battle_YYYY_MM_DD_HH_MM/
            ├── mapbg.png          Captured map background
            ├── mapbg.info         Tile dimensions
            ├── mapdata.bin        Binary tile data
            ├── dramatis_personae.json  Actor registry (UUIDs, templates, factions)
            ├── round_log.jsonl    Action log (player actions + AI decisions)
            ├── render_jobs/       Self-contained render job JSON files
            └── heatmaps/          Rendered heatmap PNGs

Anywhere/
└── TacticalEngine(.exe)           Engine binary — runs from any location

Usage

Start the Engine

Linux 
# Passive — engine starts, you control everything
./start-tactical-engine.sh
 
# Auto-navigate to tactical when game connects
./start-tactical-engine.sh --on-title /navigate/tactical
Windows 
REM Passive
start-tactical-engine.bat
 
REM Auto-navigate to tactical
start-tactical-engine.bat --on-title /navigate/tactical

Then launch the game normally through Steam. On Linux the engine opens in its own terminal window; on Windows it runs in the command prompt. Logs written to Mods/BOAM/logs/tactical_engine.log.

In-Game Minimap

KeyAction
MToggle minimap on/off
LCycle display presets (size/anchor)

Additional keys (FoW, labels, etc.) can be enabled in tactical_map.json5. See Tactical Minimap.

Render Heatmaps

After playing a round, render job data is flushed to disk. Render heatmaps on demand:

Linux 
../UserData/BOAM/Engine/TacticalEngine --render battle_2026_03_15_15_14                              # all
../UserData/BOAM/Engine/TacticalEngine --render battle_2026_03_15_15_14 --pattern "r01_*"            # round 1 only
../UserData/BOAM/Engine/TacticalEngine --render battle_2026_03_15_15_14 --pattern "*_alien_stinger*" # one unit
Windows 
..\UserData\BOAM\Engine\TacticalEngine.exe --render battle_2026_03_15_15_14
..\UserData\BOAM\Engine\TacticalEngine.exe --render battle_2026_03_15_15_14 --pattern "r01_*"
..\UserData\BOAM\Engine\TacticalEngine.exe --render battle_2026_03_15_15_14 --pattern "*_alien_stinger*"

HTTP (any platform, while engine is running):

curl -s -X POST http://127.0.0.1:7660/render/battle/battle_2026_03_15_15_14 -d '{}'

See Heatmap Renderer.

Icons

Icons are generated automatically on first engine startup via an interactive setup prompt. To regenerate, start the engine with --icons-force. A built-in fallback icon pack is embedded in the engine binary for users without extracted game assets.

Documentation