dungeoncraft/docs/BALANCE.md

Balance runs

Whole games played headless by the AI brain on every side (src/balance.rs), deterministic per seed:

cargo test --release balance_ -- --ignored --nocapture --test-threads=3
BALANCE_SEEDS=16 cargo test --release balance_difficulty -- --ignored --nocapture   # more seeds
BALANCE_PAIR=0,1 ...       # one difficulty pairing only (0 easy, 1 medium, 2 hard)
BALANCE_TRACE=1 ...        # wave runs: a status line every two minutes

• balance_difficulty – duels of two AI masters (112x112, no hero waves, 45 min); the sides swap every other seed. Undecided games count as draws.
• balance_talents – four AI masters (medium), each held to one talent branch, the branches moving round the four starts; placement by survival and strength.
• balance_waves – one AI master alone against the hero waves (96x96, 40 min).

Findings and changes (2026-11-06)

First runs showed:

• AI masters stopped growing after their build order (99 room tiles, 24 creatures from minute 10).
• They mined one vein at a time and only below 1500 gold.
• They fought hero waves piecemeal and never cast spells.
• "Hard" attacked even when weaker (boldness 0.9) and was no stronger than "easy".

Changes:

• AI masters keep building lairs and gardens up to 24 / 50 / 80 beds (easy / medium / hard), and a bigger treasury when the old one is nearly full.
• They mine several veins (one per three imps) whenever gold is below 1.5 paydays + 1000.
• Defence: with intruders in the dungeon the rally flag goes on them, the master casts lightning on them and heals his hurt creatures; an attack is called off to defend.
• Boldness (own army / enemy army needed to attack): easy 1.0, medium 1.2, hard 1.35.
• Builder talent: imps dig +15% and rooms cost -10% per level (was +10% / -6%).

Results after the changes:

	before	after
one master vs waves: fallen of 8 (easy/medium/hard)	2 / 3 / 4	2 / 2 / 2
duels, 16 seeds: easy vs medium	6 : 6	3 : 6
medium vs hard	5 : 6 (8 seeds 3 : 2)	5 : 6
easy vs hard	3 : 7	3 : 7
talents, average place (builder / warlord / warlock / merchant)	3.3 / 1.9 / 3.0 / 1.9	3.1 / 2.1 / 2.5 / 2.3

Notes:

• The noise is about ±2 wins at 16 seeds; medium vs medium ended 5 : 7.
• The AI uses only lightning and heal, so Warlock is still worth more to a human player than the tournament shows.
• Builder pays off where space, not gold, limits building; AI dungeons are bounded by their radius.
• One map seed (1333) never brings heroes to the master. It shows as "wave 11, heroes 0" in the wave table and is a map outlier.