Source-first reverse engineering of a mainline Battle for Wesnoth campaign

AI Index

A campaign-wide index of declarative AI tuning, scripted reinforcements, autonomous allies, dormant factions, and Clearwater Port’s posture-based defense system.

Home / AI index

AI usage through Scenario 10

ScenarioAI levelNotable behavior
01LightCore AI, no scouts, role-based recruitment.
02ModerateDefensive Wesfolk, passive target leader, night-aggressive orcs.
03ModerateSymmetric passive orc leaders, night aggression, scripted post-kill reinforcements.
04aLight AI / high event logicCult sides use ordinary AI; adaptive ambushes are event-driven.
04bModerateNight-aggressive orcs plus attack-triggered reserves and survivor funding.
05Moderate allianceAutonomous Wose side; difficulty scales allied gold and guardians downward.
06Simple aggressiveLenvan uses aggression 1.0; dungeon events provide most complexity.
07None intendedOne-turn cutscene with no tactical AI requirement.
08Very highStateful allied defense, withdrawal, wall holding, offensive support, and dynamic recruits.
09Moderate multi-factionNight-aggressive orcs, dormant petrified undead, hidden no-economy Yeti side.
10Moderate symmetricTwo matching wizard AIs; event logic funds the surviving twin.

Clearwater Port state machine

previous_ai_position │ ├── "forward" │ ├── player commits west ──► "attacking" │ └── orcs overwhelm castle ─► "retreat firstturn" │ ├── "retreat firstturn" ─────────► "retreat secondturn" │ ├── "retreat secondturn" ────────► "defending" │ ├── "defending" ─────────────────► holds city walls │ └── "attacking" ─────────────────► offensive support until conditions change
SignalThresholdResponse
Orcs near outer castle10 or more side-4/5/6 units within radius 6 of 22,20Withdraw unless the player has at least four units in front of the walls.
Player far forwardAt least four side-1 units with x in 0–20Switch allied garrison to offensive support.
Allied reserve goldMore than 60Enable level-2 extra recruits.
Retreat modeAttacking disabledTemporary side-3 transfer permits attacks against adjacent enemies without renewed advance.

Declarative AI versus scripted behavior

TechniqueExamplesUse when
Static AI attributesAggression, caution, grouping, village valueA faction should have one broad personality.
Time-of-day AI facetsOrc aggression at dusk and nightBehavior should change predictably with the schedule.
Goal and avoid locationsClearwater forward castle and city wallSpecific map positions define the faction’s job.
AI reset by eventClearwater posture changesThe faction must change military doctrine during play.
Fixed scripted unitsMidlands reserves, sewer guardiansComposition and timing must be guaranteed.
Event-driven ecologySwamp scorpion ambushesThe effect should respond to player location or vision rather than AI planning.

AI design lessons

LessonEvidence in the campaign
Do not customize AI unless the scenario needs readable behavior.Most early enemies use core AI plus a few role or time-of-day settings.
Use events for guaranteed dramatic beats.Assassins, Naga, reserves, and guardian creatures do not depend on recruitment luck.
Allied AI requires more care than enemy AI.Clearwater must look competent, avoid suicide, preserve wall positions, and support the player.
Difficulty may scale allies as well as enemies.Oldwood reduces Wose resources and defenders at higher difficulty.
Current unit state can replace extra variables.Sewer bonus checks whether wizard leaders remain rather than maintaining kill flags.

Clearwater AI source · Fallen Lich Point source · Sewer source

AI additions in Scenarios 11–13

ScenarioAI architectureKey lesson
11 — Southbay in WinterNo tactical AI requiredA scenario can use normal sides and units purely for cutscene staging.
12 — A Final SpringAllied side recalculates northern-castle, riverbank, and wall goals each turn; three night-aggressive enemy leaders; scripted hidden Jevyan sideUse direct battlefield queries when posture can be derived without a state variable.
13 — Peoples in DeclineThree broadly symmetric drake sides with different advanced roster options; hidden serpent sideFaction and roster differences may provide enough identity without custom AI.

Clearwater versus Southbay allied defense

FeatureClearwater PortA Final Spring
State methodExplicit previous_ai_positionRecomputed from current unit counts and locations
PosturesForward, retreat 1, retreat 2, wall defense, attackNorthern castles or southern riverbank, plus permanent wall goals
Special workaroundTemporary helper side during withdrawalNo helper-side retreat sequence
Use caseReadable multi-turn tactical transitionResponsive static-defense allocation

Scenario 15 Lua candidate action

ca_aggressive_attack_no_suicide.lua is added to all three continental sides at a maximum score of 100000. The standard combat, high-XP attack, and poison-spreading candidate actions are removed.

Evaluation stepBehavior
Enumerate attacksUses the campaign’s AI-helper dependency to find all possible attacks.
Simulate combatClones the attacker at the destination and calls wesnoth.simulate_combat.
Safety gateConsiders only attacks where att_stats.hp_chance[0] == 0.
RatingDefender kill chance × 100 + expected defender damage − attacker damage/10 + attacker HP/10.
ExecutionUses robust_move_and_attack on the highest-rated safe attack.
Technical lesson. The campaign does not build a whole AI. It replaces one decision point—the attack selector—because that is the only default behavior incompatible with a deathless scenario.

Lua source · Scenario integration

AI across the Ka’lian quests

BranchAI design
DragonThree Saurian sides defend the cave region, one targets Haldric, and a hidden Dragon side is event-created. Boss awakening funds every Saurian army.
Lizard BeachTwo passive leaders anchor the trade site; progress creates fixed Naga reinforcements; first leader death funds the survivor.
Troll HoleFour symmetric Troll sides are declared, but random setup removes two leaders. Aggression scales modestly by difficulty; recruit limits control regenerating unit density.
Cursed IsleTwo Spectre sides protect the island center, remain cautious by day, and become aggressive at night. The Queen is event-created and her death deletes the remaining faction.

The branch set shows a recurring campaign principle: ordinary AI handles movement and combat, while WML events guarantee the scenario-defining phase changes.

AI and scripted escalation in Scenarios 18–20

ScenarioAI architectureScenario-defining scripting
18No tactical AI needed.Temporary unit double moves through the council cutscene.
19Night-aggressive orcs, conventional Troll AI, hidden no-economy undead side.Each front’s proportional losses trigger one spatially searched undead wave.
20Passive undead leader, night-aggressive orcs.Turn-5 fog curse and Chocobones; exploration-triggered Cuttle Fish and Saurians.

Scenario 19 is a useful boundary case: the enemy sides themselves use ordinary AI, while the reinforcement director monitors army strength and map geometry outside the AI system.

Final-battle AI boundary

LayerResponsibility
Jevyan AIPassive leader, castle protection, night aggression, undead recruitment.
Orc AIMaritime, defensive, and night-aggressive ordinary battlefield pressure.
Event directorRequired killer, survivor count, boat escape, bridges, Naga arrival, random undead schedules, and faction reinforcement economy.

The final scenario demonstrates why objective logic should remain outside AI: the computer-controlled factions fight normally, while the event layer evaluates the player’s strategic deception contract.