Macros & Event Patterns

Macro catalogue through Scenario 03

Macro / construct	Origin	Purpose in these scenarios
`TROW_GI_TRACK` + journey macro	Campaign utility	Updates the Green Isle journey presentation for each stage.
`TROW_DEATHS`	Campaign utility	Injects shared last-breath and defeat/vanish behavior for recurring heroes.
`TURNS`, `GOLD`, `INCOME`, `ON_DIFFICULTY`	Core	Difficulty-dependent balance values.
`NO_SCOUTS`	Core	Modifies AI recruitment behavior.
`STARTING_VILLAGES`	Core	Assigns initial village control.
`LOYAL_UNIT`, `GUARD_UNIT`, `GUARDIAN`	Core	Creates fixed, loyal, or stationary supporting units.
`LOOT`, `FULL_HEAL`, `NEW_GOLD_CARRYOVER`	Core	Rewards, escape handling, and campaign economy.
`NORTH_GUARD`	Scenario 02 local	Creates three named, difficulty-scaled loyal defenders.
`ESCAPE_VICTORY`	Scenario 03 local	Packages route-choice dialogue, state, and next-scenario overrides.

Event-pattern catalogue

Pattern	Example	Reusable purpose
`prestart` setup	Objectives, recalls, fixed units, images	Prepare state before the player sees the map.
`start` exposition	All three scenarios	Explain the immediate tactical situation after setup.
Turn reminder	01 turn 5/20; 02 turn 14	Teach or reinforce urgency without changing objectives.
`last breath` decision	Wesfolk leader in 02	Run dialogue and choice before death resolution.
Filtered killer	Orc leader loot; Wesfolk killed by orcs	Make result depend on who caused the death.
Map-area movement trigger	Orcs enter Stormvale; Haldric finds Burin	Bind narrative to geography.
First boss death escalation	03 reinforcement wave	Keep a multi-leader scenario challenging.
Victory-time route menu	03 `ESCAPE_VICTORY`	Select a branch after tactical success.
`allow_undo` flavor trigger	03 signposts	Permit reading flavor text without consuming a move.

Shared death utility behavior

TROW_DEATHS is not just a list of defeat conditions. Different heroes receive different semantics: Haldric, Eldaric, Jessene, and Lord Typhon can cause defeat; Lady Outlaw vanishes and updates stored state; Burin and several later companions receive character-specific final lines.

Architecture lesson. Centralizing recurring hero-death logic keeps scenario files focused and ensures consistent consequences across the campaign.

TROW_DEATHS source · Utility directory

Scenario 04 macro and event patterns

Construct	Route	Purpose
`TEMPLE_HELP`, `TEMPLE_TRAP`, `TEMPLE_LOOT`	Swamp	Turn map coordinates into reusable, randomly assigned points of interest.
`RANDOM 1..3` plus conditional macro placement	Swamp	Produces three controlled exploration layouts.
Nested `new turn` event inside `moveto`	Swamp	Delays an adaptive ambush until the next turn.
`filter_vision` and adjacent visibility filters	Swamp	Finds the boundary between visible and hidden map areas.
`while` search-radius expansion	Swamp	Finds a valid ambush hex without assuming a fixed player route.
Nested `new turn` event inside `attack`	Midlands	Schedules a leader-specific reserve wave after combat begins.
Leader `die` event funding the surviving side	Midlands	Maintains multi-front pressure after one chief falls.

Oldwood arc macros and event patterns

Construct	Origin	Purpose
`GUARD_UNIT`	Campaign utility	Creates named loyal guardian units with `ai_special=guardian`.
`RISE_UP_RISE_UP`	Campaign utility	Raises a fallen ally as a hostile difficulty-scaled corpse while preserving undead variation.
`OBJ_POTION_HOLY_ALT`	Core item macro	Places an interactive holy-water pickup that appends arcane to melee attacks for the scenario.
`CLEAR_FOG` / `UNCLEAR_FOG`	Core	Temporarily reveals the Wose speaker for opening dialogue.
`modify_side share_vision=all`	WML action	Synchronizes allied vision after the battle.
`victory_when_enemies_defeated=no`	Scenario key	Supports compound objectives and cutscene-only scenarios.
`store_unit` / `unstore_unit`	WML actions	Preserve a companion through an off-screen scouting interlude.
Reconstruction from stored fields	Scenario 07 local pattern	Transforms Lady Outlaw into Lady Jessene while retaining intended progression data.

Campaign macro source · Core item source

Scenarios 08–10 macro and event patterns

Construct	Scenario	Purpose
`BOARDING_EVENT`	08 local	Generates three consistent Haldric-only boarding interactions.
`LIMIT_RECRUITS` and `set_extra_recruit`	08	Restricts fragile recruits and unlocks advanced units based on gold.
AI reset, goal locations, avoid regions, attack disabling	08	Implements posture-based allied defense.
`time_area` with custom schedule	08	Simulates lighthouse illumination in a local radius.
`PETRIFIED` and `PETRIFIED_UNIT`	09 local	Creates a visible but dormant enemy army.
`unpetrify` plus upkeep conversion	09	Activates the lich faction without replacing its units.
Haldric-only exit with temporary item flag	09	Requires both narrative artifact and protagonist staging.
Twin death counterpart check	10	Funds the survivor or rewards the player after the second death.
Exit event queries living enemy leaders	10	Selects standard or bonus victory without extra state variables.
`remove_shroud` as a combat reward	10	Turns boss defeat into navigation information.

Scenarios 11–13 macro and event patterns

Construct	Scenario	Purpose
`Cutscene_Minimal` + 100% carryover settings	11	Runs a council scene without gameplay reports or economic loss.
Forever-duration `[object]` with `new_attack`	12	Adds the Ruby attack to Haldric without changing unit type.
`SILENTLY_LIMIT_LEADER_MOVES`	12	Keeps Addroran near defensive positions.
`MODIFY_AI_DELETE_CANDIDATE_ACTION` and repeated `RESET_SIDE_AI`	12	Rebuilds the allied defense each turn.
`HERO` plus appended modifications	12	Creates Typhon with guaranteed signature equipment.
`LIVING_INTEL` and `UNDEAD_INTEL`	12–13	Stages temporary information-gathering characters and antagonist visits.
`OBJ_TRIDENT_STORM`	13, core	Provides a reusable eligible-unit pickup with a permanent magical attack.
Nested `new turn` inside item-region `moveto`	13	Delays a randomized Sea Serpent spawn until after the pickup turn.

Scenarios 14–16 macro and event patterns

Construct	Scenario	Purpose
`POSSIBLE_SERPENT_SPAWN_LOCS_SLF`	14 local	Reuses a deep-ocean distance-ring filter for both availability and storage.
Nested delayed `new turn` events	14	Schedule one serpent per enemy side after its first casualty.
`MODIFY_AI_ADD_CANDIDATE_ACTION`	15	Installs the campaign Lua no-suicide attack selector.
`MODIFY_AI_DELETE_CANDIDATE_ACTION`	15	Removes competing standard combat actions.
`modify_turns` value then add	15	Transforms survived turns into early-finish bonus turns.
`DRAGON`, `BEACH`, `HOLE`, `ISLE`	16 local	Define state-filtered hub destinations.
`QUESTS` / `QUEST_CHOICES`	16 local	Render unfinished descriptions and selectable routes.
`GREET`	16 local	Renders return dialogue from `last_done`.
`#undef` cleanup	16	Removes all seven local hub macros after preprocessing the file.

Scenario 17 branch macros and patterns

Construct	Branch	Purpose
`GOLD_TO_BADDIES`	Dragon local	Funds all Saurian sides consistently when the Dragon awakens.
Approach event plus fallback turn event	Dragon	Creates one boss from either spatial or temporal trigger.
Repeated Giant Mudcrawler death event	Dragon / Beach	Creates two smaller enemies from every large one.
`LIMIT_CONTEMPORANEOUS_RECRUITS`	Beach / Hole	Caps high-impact unit density across one or several sides.
`SPIDER_TRAIT` with additive tags	Hole local	Appends difficulty-specific traits to `GUARD_UNIT` results.
`TEMP_LOOT`, `TEMP_QUEEN`, `TEMP_EMPTY`	Isle local	Assign random interaction identities to fixed temple coordinates.
Objective `show_if` by living units	Isle	Switches displayed victory requirement when the Queen is created.
Boss-death faction cleanup	Isle	Kills remaining undead without firing individual death events.
`#undef` cleanup	Dragon / Hole / Isle	Removes local helper macros after the scenario.

Scenarios 18–20 event patterns

Construct	Scenario	Purpose
`store_unit kill=no` then renamed `unstore_unit`	18	Creates a temporary duplicate without moving the persistent hero.
`remove_object object_id=ruby_of_fire`	19	Physically removes a permanent artifact attack.
Dynamic variable names such as `side_$unit.side\|_...`	19	Runs one generic proportional-loss handler for three enemy sides.
Nested `new turn delayed_variable_substitution=no`	19	Preserves trigger context while evaluating future search variables later.
Expanding-radius location search	19	Finds a legal front-related reinforcement point exactly 12 hexes from the player.
Objective `show_if` with `have_unit`	20	Displays Jessene’s defeat condition only after her return.
`modify_side fog=yes`	20	Changes battlefield visibility during play.
Geographic encounter plus `allow_recruit`	20	Creates Saurians and permanently expands current enemy recruit lists.

Endgame event patterns

Construct	Purpose
`unit_overlay`	Turns Aethyr into a visible treaty carrier.
Paired `last breath` and `die` with `filter_second`	Distinguishes valid and invalid Aethyr deaths.
Repeated leader-death queries	Enforces the exact-one-orc-survivor condition.
`switch` on stored side	Selects one of four boat escape routes.
New-turn bridge condition checks	Destroy routes only when player proximity makes the event relevant.
Random future-turn variables	Schedule recurring corpse and skeleton pressure inside bounded windows.
`random_placement allow_less=yes`	Places as many legal undead reinforcements as the map state permits.
Conditional companion epilogue block	Shows futures only when at least one optional companion survives.

Utility-file catalogue

The new Utility & Macro Catalogue inventories all six utility files, including the complete five-macro unit-construction surface, seven AI helper macros, shared death contract, journey-map system, and narrative reminder events.

Release 1.0.0. Source snapshot: Wesnoth 6ab3fc1, accessed July 12, 2026. This site has no external runtime dependencies and can be opened directly from disk.