WML Macros Reference

This page is an automatically-generated reference for all the utility macros with documentation strings in the Wesnoth source distribution. It will reflect the state of the latest development release. It can be generated with make macro-reference.html in the data/tools-directory.

The organization of these macros may change in future releases, and some may be moved out of the default load path. If in doubt, use wmlscope to check your campaign against the macros in the Wesnoth distribution.

warning: ../../data/core/macros/ has no export property

Documented files:

From file: abilities.cfg

Ability macros to be included in the SingleWML description of a unit.

ABILITY_HEALS

Canned definition of the heal+4 ability to be included in an [abilities] clause.

ABILITY_UNPOISON

Canned definition of the cure-poison ability to be included in an [abilities] clause.

ABILITY_CURES

Canned definition of the cure ability (which entails heal+8) to be included in an [abilities] clause..

ABILITY_REGENERATES

Canned definition of the Regenerate ability to be included in an [abilities] clause.

ABILITY_STEADFAST

Canned definition of the Steadfast ability to be included in an [abilities] clause.

ABILITY_LEADERSHIP

Canned definition of the Leadership ability to be included in an [abilities] clause.

ABILITY_SKIRMISHER

Canned definition of the Skirmisher ability to be included in an [abilities] clause.

ABILITY_ILLUMINATES

Canned definition of the Illuminates ability to be included in an [abilities] clause.

ABILITY_TELEPORT

Canned definition of the TELEPORT ability to be included in an [abilities] clause.

ABILITY_AMBUSH

Canned definition of the Ambush ability to be included in an [abilities] clause.

ABILITY_NIGHTSTALK

Canned definition of the Nightstalk ability to be included in an [abilities] clause.

ABILITY_CONCEALMENT

Canned definition of the Concealment ability to be included in an [abilities] clause.

ABILITY_SUBMERGE

Canned definition of the Submerge ability to be included in an [abilities] clause.

ABILITY_FEEDING

Canned definition of the Feeding ability to be included in an [abilities] clause.

WEAPON_SPECIAL_BERSERK

Canned definition of the Berserk ability to be included in a [specials] clause.

WEAPON_SPECIAL_BACKSTAB

Canned definition of the Backstab ability to be included in a [specials] clause.

WEAPON_SPECIAL_PLAGUE_TYPE TYPE

Canned definition of the Plague ability to be included in a [specials] clause (with type specifier).

WEAPON_SPECIAL_PLAGUE

Canned definition of the Plague ability to be included in a [specials] clause.

WEAPON_SPECIAL_SLOW

Canned definition of the Slow ability to be included in a [specials] clause.

WEAPON_SPECIAL_PETRIFY

Canned definition of the Petrify ability to be included in a [specials] clause.

WEAPON_SPECIAL_MARKSMAN

Canned definition of the Marksman ability to be included in a [specials] clause.

WEAPON_SPECIAL_MAGICAL

Canned definition of the Magical (targeting) ability to be included in a [specials] clause.

WEAPON_SPECIAL_SWARM

Canned definition of the Swarm ability to be included in a [specials] clause.

WEAPON_SPECIAL_CHARGE

Canned definition of the Charge ability to be included in a [specials] clause.

WEAPON_SPECIAL_DRAIN

Canned definition of the Drain ability to be included in a [specials] clause.

WEAPON_SPECIAL_FIRSTSTRIKE

Canned definition of the First-strike ability to be included in a [specials] clause.

WEAPON_SPECIAL_POISON

Canned definition of the Poison ability to be included in a [specials] clause.

From file: ai.cfg

MODIFY_AI_ADD_ASPECT SIDE ASPECT_ID FACET_WML

modify ai, add facet to an aspect

example: {MODIFY_AI_ADD_ASPECT 1 aggression ([facet] id=always value=0.5 [/facet])} example: {MODIFY_AI_ADD_ASPECT 1 leader_goal ([facet] id=always [value]x=1 y=2[/value] [/facet])}

MODIFY_AI_ADD_STAGE SIDE STAGE_WML

modify ai, add stage

MODIFY_AI_ADD_GOAL SIDE GOAL_WML

modify ai, add goal

MODIFY_AI_ADD_CANDIDATE_ACTION SIDE STAGE_ID CANDIDATE_ACTION_WML

modify ai, add candidate action to a stage

MODIFY_AI_DELETE_ASPECT SIDE ASPECT_ID FACET_ID

modify ai, delete facet from aspect

example: {MODIFY_AI_DELETE_ASPECT 1 aggression night}

MODIFY_AI_DELETE_STAGE SIDE STAGE_ID

modify ai, delete a stage

example: {MODIFY_AI_DELETE_STAGE 1 fallback} example: {MODIFY_AI_DELETE_STAGE 1 3}

MODIFY_AI_DELETE_GOAL SIDE GOAL_ID

modify ai, delete a goal

example: {MODIFY_AI_DELETE_GOAL 1 kill_undead} example: {MODIFY_AI_DELETE_GOAL 1 0}

MODIFY_AI_DELETE_CANDIDATE_ACTION SIDE STAGE_ID CANDIDATE_ACTION_ID

modify ai, delete candidate action from a stage

example: {MODIFY_AI_DELETE_CANDIDATE_ACTION 1 special_poisoning_formula} example: {MODIFY_AI_DELETE_CANDIDATE_ACTION 1 0}

MODIFY_AI_TRY_DELETE_ASPECT SIDE ASPECT_ID FACET_ID

modify ai, delete facet from aspect

example: {MODIFY_AI_TRY_DELETE_ASPECT 1 aggression night}

MODIFY_AI_TRY_DELETE_STAGE SIDE STAGE_ID

modify ai, delete a stage

example: {MODIFY_AI_TRY_DELETE_STAGE 1 fallback} example: {MODIFY_AI_TRY_DELETE_STAGE 1 3}

MODIFY_AI_TRY_DELETE_GOAL SIDE GOAL_ID

modify ai, delete a goal

example: {MODIFY_AI_TRY_DELETE_GOAL 1 kill_undead} example: {MODIFY_AI_TRY_DELETE_GOAL 2 *} example: {MODIFY_AI_TRY_DELETE_GOAL 3 0}

MODIFY_AI_TRY_DELETE_CANDIDATE_ACTION SIDE STAGE_ID CANDIDATE_ACTION_ID

modify ai, delete candidate action from a stage

example: {MODIFY_AI_TRY_DELETE_CANDIDATE_ACTION 1 special_poisoning_formula} example: {MODIFY_AI_TRY_DELETE_CANDIDATE_ACTION 1 0}

AI_ASPECT ASPECT_ID FACET_WML

macro to define a named facet of ai aspect

AI_SIMPLE_ASPECT ASPECT_ID FACET_ID VALUE

simple aspect with value=VALUE

AI_SIMPLE_ALWAYS_ASPECT ASPECT_ID VALUE

simple aspect which is always active

AI_SIMPLE_ASPECT_FOR_TIME_OF_DAY ASPECT_ID FACET_ID TIMEOFDAY_VALUE VALUE

simple aspect which is active during a specified time of day

AI_SIMPLE_NIGHT_ASPECT ASPECT_ID VALUE

simple aspect which is active during the night

AI_SIMPLE_DAY_ASPECT ASPECT_ID VALUE

simple aspect which is active during the day

AI_SIMPLE_ASPECT_VALUE ASPECT_ID FACET_ID VALUE

simple aspect

AI_SIMPLE_ALWAYS_ASPECT_VALUE ASPECT_ID VALUE

simple aspect which is always active

AI_SIMPLE_ASPECT_FOR_TIME_OF_DAY_VALUE ASPECT_ID FACET_ID TIMEOFDAY_VALUE VALUE

simple aspect which is active during a specified time of day

AI_SIMPLE_NIGHT_ASPECT_VALUE ASPECT_ID VALUE

simple aspect which is active during the night

AI_SIMPLE_DAY_ASPECT_VALUE ASPECT_ID VALUE

simple aspect which is active during the day

MODIFY_AI_ADD_SIMPLE_ASPECT SIDE ASPECT_ID FACET_ID VALUE

modify ai, add simple facet to an aspect

MODIFY_AI_ADD_SIMPLE_ALWAYS_ASPECT SIDE ASPECT_ID VALUE

modify ai, add simple aspect which is always active

MODIFY_AI_ADD_SIMPLE_ASPECT_FOR_TIME_OF_DAY SIDE ASPECT_ID FACET_ID TIMEOFDAY_VALUE VALUE

modify ai, add simple aspect which is active during a specified time of day

MODIFY_AI_ADD_SIMPLE_NIGHT_ASPECT SIDE ASPECT_ID VALUE

modify ai, add simple aspect which is active during the night

MODIFY_AI_ADD_SIMPLE_DAY_ASPECT SIDE ASPECT_ID VALUE

modify ai, add simple aspect which is active during the day

MODIFY_AI_ADD_SIMPLE_ASPECT_VALUE SIDE ASPECT_ID FACET_ID VALUE

modify ai, add simple facet to an aspect

MODIFY_AI_ADD_SIMPLE_ALWAYS_ASPECT_VALUE SIDE ASPECT_ID VALUE

modify ai, add simple aspect which is always active

MODIFY_AI_ADD_SIMPLE_ASPECT_FOR_TIME_OF_DAY_VALUE SIDE ASPECT_ID FACET_ID TIMEOFDAY_VALUE VALUE

modify ai, add simple aspect which is active during a specified time of day

MODIFY_AI_ADD_SIMPLE_NIGHT_ASPECT_VALUE SIDE ASPECT_ID VALUE

modify ai, add simple aspect which is active during the night

MODIFY_AI_ADD_SIMPLE_DAY_ASPECT_VALUE SIDE ASPECT_ID VALUE

modify ai, add simple aspect which is active during the day

AI_NO_SCOUTS

make the AI team not recruit scouts.

AI_NEW_SYNTAX

use stable 1.8 ai syntax Deprecated; no longer does anything

AI_SCALE_ATTACK_DEPTH_BY_DIFFICULTY

change attack depth depending on difficulty ifdef EASY

AI_DEACTIVATE_SAVE_GOLD

disable aspect recruitment_save_gold

AI_NO_RECRUITMENT

disable recruitment

AI_SAVE_GOLD ACTIVE BEGIN END

Enable AI recruitment gold saving. ACTIVE: turn from which on gold saving will be active BEGIN: begin gold saving when unit cost ratio rises above this value END: end gold saving when unit cost ratio drops below this value This goes directly into the [ai] tag.

AI_SAVE_GOLD_DEFAULT

Enable AI recruitment gold saving with values set to what was the default in Wesnoth 1.11.7 and 1.11.8. This goes directly into the [ai] tag.

AI_ASPECT_LEADER_GOAL_MOVE_TO X Y

leader goal: move to X Y and be free

AI_ASPECT_LEADER_GOAL_MOVE_TO_AND_STAY_THERE X Y

leader goal: move to X Y and stay there

CLEAR_AI_ALWAYS_ASPECT_LEADER_GOAL SIDE

clear AI leader goal "always"

AI_ASPECT_LEADER_GOAL_RISKY_MOVE_TO X Y

leader goal: move to X Y and be free

AI_ASPECT_LEADER_GOAL_RISKY_MOVE_TO_AND_STAY_THERE X Y

leader goal: move to X Y and stay there

EXPERIMENTAL_AI

Experimental AI with alternative recruitment, castle switching, alternative retreating, village grabbing, poison spreading, healer placement, village hunting and move-to-enemy candidate actions. Put this into the [side][ai] tag. Does not work in [modify_side][ai] or [modify_ai] at the moment.

From file: ai_candidate_actions.cfg

AI_CA_GOTO

RCA AI candidate action: goto

AI_CA_RECRUITMENT

RCA AI candidate action: recruitment

AI_CA_MOVE_LEADER_TO_GOALS

RCA AI candidate action: move_leader_to_goals

AI_CA_MOVE_LEADER_TO_KEEP

RCA AI candidate action: move_leader_to_keep

AI_CA_COMBAT

RCA AI candidate action: combat

AI_CA_HEALING

RCA AI candidate action: healing

AI_CA_VILLAGES

RCA AI candidate action: villages

AI_CA_RETREAT

RCA AI candidate action: retreat

AI_CA_MOVE_TO_TARGETS

RCA AI candidate action: move_to_targets

AI_CA_LEADER_SHARES_KEEP

RCA AI candidate action: leader_shares_keep

AI_CA_POISONING

Extra candidate action: Formula AI CA for poisoners to spread poison around

From file: ai_controller.cfg

AI_CONTROLLER_ALLOW_UNIT_CONTROL CONTROLLER_SIDE UNIT_ID

Right-click content menu item for issuing instructions to an allied AI unit

AI_CONTROLLER_ALLOW_LEADER_CONTROL CONTROLLER_SIDE CONTROLLED_SIDE

Right-click content menu item for issuing instructions to an allied AI side's leader

AI_CONTROLLER_NOTE

Note for the objectives that instructions can be issued to an allied AI side

AI_CONTROLLER AFFIX PLAYER_SIDES ALLY_SIDES VARIABLES_WML

Right-click content menu item for issuing instructions to an allied AI side

AI_CONTROLLER_FUTURE_STRINGS

These will be used for the special orders menu and the order for telling the ally leader to move someplace

From file: amla.cfg

this file contains macros for After Max Level Advancement (AMLA)

AMLA_DEFAULT

Canned definition of the default AMLA.

From file: animation-utils.cfg

Macros for setting animations.

LEADING_ANIM FULL_IMAGE HALFWAYS_IMAGE OFFSET_POSITION

Define an animation of a unit waving/raising their weapon, with a gleam of light reflecting off it at the point specified by OFFSET_POSITION

DEFENSE_ANIM REACTION_IMAGE BASE_IMAGE HIT_SOUND

Define a defensive animation moving from a specified BASE_IMAGE to REACTION_IMAGE, with HIT_SOUND playing only if a hit occurs.

DEFENSE_ANIM_FILTERED REACTION_IMAGE BASE_IMAGE HIT_SOUND FILTER

Define a defensive animation moving from a specified BASE_IMAGE to REACTION_IMAGE, with HIT_SOUND playing only if a hit occurs. This fires only if FILTER is matched.

DEFENSE_ANIM_DIRECTIONAL_FILTERED REACTION_SE_IMAGE BASE_SE_IMAGE REACTION_NE_IMAGE BASE_NE_IMAGE HIT_SOUND FILTER

Define a defensive animation depending on direction moving from a specified NE or SE Base image to NE or SE Reaction image, with HIT_SOUND playing only if a hit occurs. This fires only if FILTER is matched.

DEFENSE_ANIM_RANGE REACTION_IMAGE BASE_IMAGE HIT_SOUND RANGE

Define a defensive animation moving from a specified BASE_IMAGE to REACTION_IMAGE, with HIT_SOUND playing only if a hit occurs. This fires only on the class of attacks specified by RANGE.

DEFENSE_ANIM_ELVEN_RANGE REACTION_IMAGE BASE_IMAGE HIT_SOUND RANGE

Define a defensive animation moving from a specified BASE_IMAGE to REACTION_IMAGE, with HIT_SOUND playing only if a hit occurs and an elven halo waxing and waning during the animation. This fires only on the class of attacks specified by RANGE.

STANDARD_IDLE_FILTER

Poisoned units should have no idle animation.

MISSILE_FRAME_WAIL

Animate a projectile for a wail attack.

MISSILE_FRAME_LIGHT_BEAM

Animate a beam of light coming down from the heavens.

MISSILE_FRAME_FIRE_BREATH N_OFFSET_POSITION S_OFFSET_POSITION N_DIAGONAL_OFFSET_POSITION S_DIAGONAL_OFFSET_POSITION

Animate a projectile for a fire-breath attack.

MISSILE_FRAME_FIRE_BREATH_N OFFSET_POSITION

Animate a projectile for a fire-breath attack.

MISSILE_FRAME_FIRE_BREATH_S OFFSET_POSITION

Animate a projectile for a fire-breath attack.

MISSILE_FRAME_FIRE_BREATH_N_DIAGONAL OFFSET_POSITION

Animate a projectile for a fire-breath attack.

MISSILE_FRAME_FIRE_BREATH_S_DIAGONAL OFFSET_POSITION

Animate a projectile for a fire-breath attack.

MISSILE_FRAME_FAERIE_FIRE

Animate a projectile for a faerie-fire attack.

MISSILE_FRAME_FIREBALL_XY OFFSET_X OFFSET_Y

Animate a projectile for a fireball attack with an X and Y start offset from centre of hex.

MISSILE_FRAME_HATCHET

Animate a projectile for a thrown-hatchet attack.

From file: animation-utils2.cfg

Macros for setting animations.

MAGIC_ARMRAISE_DIRECTIONAL_2_FRAME BASE_IMAGE_NAME

unlike the others, this one is used *inside* the attack/healing anim.

From file: conditional-utils.cfg

Conditionals for MP scenarios.

OWN_VILLAGE X Y SIDE

Test if a given side owns the village at the specified location

IF_VAR VAR OP_NAME VALUE CONTENTS_WML

Shortcut for IF statements testing the value of a variable. Need to write [then] and [else] tags manually. Use like this:

 {IF_VAR some_variable equals yes (
     [then]
         ...
     [/then]
 )}
IF_ALIVE SIDE ACTION_WML

Condition triggering of ACTION_WML on whether SIDE has at least one unit left. For example, if the player 2 is still alive, kill all his units.

 {IF_ALIVE 2 (
   [kill]
       side=2
   [/kill]
 )}
IF_DEAD SIDE ACTION_WML

Condition triggering of ACTION_WML on whether SIDE has no units left. For example, give player 2 gold if player 1 is dead

 {IF_DEAD 1 (
   [gold]
       side=2
       amount=25
   [/gold]
 )}
IF_ALLIED PLAYER1_SIDE PLAYER2_SIDE ACTION_WML

Condition that triggers if PLAYER1_SIDE and PLAYER2_SIDE belong to the same team. NOTE: only works if leaders are alive, are the same leader as the game started and haven't changed teams. For example, if player 3 and 4 is allied, steal 10 gold from each:

 {IF_ALLIED 3 4 (
   [gold]
       side=3
       amount=-10
   [/gold]
   [gold]
       side=4
       amount=-10
   [/gold]
 )}

From file: debug-utils.cfg

This file contains macros useful for debugging and testing purposes.

DEBUG_MSG MESSAGE_TEXT

Emit a debug message. Meant to be overridden with no-op definition of the same name for production use.

DEBUG TEXT

Logs a WML debug message to consol and the in-game chat. It does nothing unless the 'wml' log domain is set to debug level at application startup (usually with --log-debug=wml), or in-game with the :log command (e.g. :log debug wml).

Example:

 {DEBUG "inconsistency: $unit.id is not loyal!"}
LOG TEXT

Logs a WML message to console and the in-game chat. It does nothing unless the 'wml' log domain is set to log level at application startup (usually with --log-info=wml), or in-game with the :log command (e.g. :log info wml).

Example:

 {LOG "player moved to forbidden location"}
WARNING TEXT

Logs a WML warning to console and the in-game chat. It does nothing unless the 'wml' log domain is set to warning level at application startup (usually with --log-warning=wml), or in-game with the :log command (e.g. :log warning wml).

Example:

 {WARNING "malformed unit data"}
ERROR TEXT

Logs a WML error to console and the in-game chat.

Example:

 {ERROR "could not respawn hero at 2,4"}
TIMED_ACTIONS TITLE_TEXT CONTENT_WML

Measure (in milliseconds) the time arbitrary event WML takes to execute.

Example:

 [event]
     name=start

     {TIME_ACTIONS "orc renaming" (
         {MODIFY_UNIT race=orc name ( _ "Azir")}
     )}
 [/event]

From file: deprecated-utils.cfg

These are clutter, scheduled to be removed.

DEPRECATE MACRO_NAME VERSION_NAME

deprecated 3 1.15 Use DEPRECATE_ACTION_MACRO instead.

DEPRECATE_ACTION_MACRO MACRO_NAME LEVEL VERSION_NAME MESSAGE

Tag ActionWML macros for removal, where VERSION_NAME is the the next development series from the date of deprecation.

MAGENTA_IS_THE_TEAM_COLOR

deprecated 3 1.15 This used to be used to set the default team color for most unit types deprecated 3 1.15 It's no longer needed, since the default is now set in the game_config.

ABILITY_LEADERSHIP_LEVEL_1

deprecated 2 1.15 Leadership is now a single unified macro. deprecated 2 1.15 If you gave it to a unit other than its intended level, you'll need a custom macro.

ABILITY_LEADERSHIP_LEVEL_2

deprecated 2 1.15 Leadership is now a single unified macro. deprecated 2 1.15 If you gave it to a unit other than its intended level, you'll need a custom macro.

ABILITY_LEADERSHIP_LEVEL_3

deprecated 2 1.15 Leadership is now a single unified macro. deprecated 2 1.15 If you gave it to a unit other than its intended level, you'll need a custom macro.

ABILITY_LEADERSHIP_LEVEL_4

deprecated 2 1.15 Leadership is now a single unified macro. deprecated 2 1.15 If you gave it to a unit other than its intended level, you'll need a custom macro.

ABILITY_LEADERSHIP_LEVEL_5

deprecated 2 1.15 Leadership is now a single unified macro. deprecated 2 1.15 If you gave it to a unit other than its intended level, you'll need a custom macro.

EARLY_FINISH_BONUS_CAPTION

deprecated 3 1.15 Use EARLY_FINISH_BONUS_FOOTNOTE instead

MISSILE_FRAME_FIREBALL

Deprecated; use MISSILE_FRAME_FIREBALL_XY X_OFFSET Y_OFFSET instead

MESSAGE SPEAKER_ID IMAGE CAPTION_TEXT MESSAGE_TEXT

deprecated 1 It's preferred to simply write out the message tag in full. Displays a text message spoken by SPEAKER_ID. Speaker can be any of: narrator, unit and second_unit For example, let's have the narrator, which looks like a faery express some feelings on the undead:

 {MESSAGE narrator "units/elves-wood/shyde.png" _ "Faery" _ "Aarr! Them be undeadies! Loooks at them.."}
LOYAL_UNDEAD_UNIT SIDE TYPE X Y

Create a unit with the Undead and Loyal traits.

ON_SIGHTING ID SIGHTING_SIDE SIGHTED_FILTER ACTION_WML

deprecated 1 Use an [event]name=sighted instead. NOTE: As of version 1.11, this macro is unnecessary, since sighted events now work as intended.

This is intended to be used when a regular sighted event can't be relied on (that'd be most of the time). This event triggers when a unit matching SIGHTED_FILTER is first seen by a unit of side SIGHTING_SIDE. This works whether the sighting happens due to moving, recruiting, recalling, attacking (in case DSU was on before the attack) or advancing. If none of those actions manage to "catch" the moment of sighting, then it will occur when the current side ends their turn.

The 'unit' and 'second_unit' message speaker shortcuts as well as the auto-stored $unit and $second_unit should work normally: the sighting unit is the primary unit and the sighted unit is the secondary unit.

You need to provide a unique ID if you use several of these events in the same scenario. Otherwise it can be left empty.

Only works if SIGHTING_SIDE has fog and/or shroud.

Example:

 {ON_SIGHTING () 1 side=2,3 (
     [message]
         speaker=unit
         message= _ "I can see a side $second_unit.side $second_unit.language_name|!"
     [/message]
     [message]
         speaker=second_unit
         message= _ "Oh my! I was seen by a side $unit.side $unit.language_name|!"
     [/message]
 )}
ANIMATED_CAMPFIRE X Y

deprecated 2 1.15 Use the campfire terrain overlay (^Ecf) instead. Embed this at scenario toplevel, not within an event. Note that it will freeze while dialogue popups are onscreen.

ANIMATED_BRAZIER X Y

deprecated 2 1.15 Use the campfire terrain overlay (^Eb) instead. Embed this at scenario toplevel, not within an event. Note that it will freeze while dialogue popups are onscreen.

MAKE_AI_SIDE_PERSISTENT SIDE

Macro to make a ai controlled side persistent. Needs to be placed below the side definition.

FOREACH ARRAY_VALUE VAR

deprecated 1 You should use the [foreach] WML tag instead. Macro to begin a WML clause that iterates over an array.

NEXT VAR

deprecated 1 You should use the [foreach] WML tag instead of {FOREACH}. Macro to end a WML clause that iterates over an array.

SOUND:SLOW

deprecated 3 1.15 This was used to play a sound when slowing a unit, it had to deprecated 3 1.15 be placed inside an attack animation. Now this sound is played deprecated 3 1.15 automatically, there is no other use for this macro.

SOUND:POISON

deprecated 3 1.15 This was used to play a sound when poisoning a unit, it had to deprecated 3 1.15 be placed inside an attack animation. Now this sound is played deprecated 3 1.15 automatically, there is no other use for this macro.

NO_INTERRUPT_NO_UNDO

This can be used in mid-movement events (enter_hex and exit_hex) to cause no interruption of movement, yet prevent the move from being undone.

KHALIFATE_NAMES

deprecated 3 1.15 Use DUNEFOLK_NAMES instead.

From file: event-utils.cfg

This file contains shortcuts for common WML events (such as prestart, side turn, and such), which can be used to write events faster and in less space.

It is recommended that you only use these if you're confident you could write the expanded form as well; these are mostly intended as shortcuts for experienced WML authors.

CALL_FUNCTION EVENT_NAME PARAMETER_WML

This will fire an event with a set of parameters, for example:

 {CALL_FUNCTION my_event a,b,c=1,2,3}

That example would fire an event with name "my_event" and inside that event, $param.c will be equal to "3" This will hold true even if the event is fired recursively

From file: image-utils.cfg

Utility macros for images, overlays, and display effects.

IS_HERO

Embed this into a unit declaration to add a hero icon to the unit.

IS_LOYAL

Embed this into a unit declaration to add a loyalty icon to the unit.

IS_EXPENDABLE_LEADER

Embed this into a unit declaration to add an expendable leader icon to the unit.

NEW_JOURNEY X Y

Make a new journey mark on a tracking map

OLD_JOURNEY X Y

Make an old journey mark on a tracking map

NEW_BATTLE X Y

Make a new battle mark on a tracking map, with a blinking animation. Because of the animation, generally you should only use this as the final journey marker in any given story screen.

OLD_BATTLE X Y

Make an old battle mark on a tracking map

NEW_REST X Y

Make a new rest mark on a tracking map, with a blinking animation. Because of the animation, generally you should only use this as the final journey marker in any given story screen.

OLD_REST X Y

Make an old rest mark on a tracking map

PLACE_IMAGE IMAGE X Y

Place an image at a specified location on the map.

REMOVE_IMAGE X Y

Removes a previously set image from a tile.

Example:

 {REMOVE_IMAGE 14 5}
TEAM_COLOR_OVERRIDE FILTER TEAMCOLOR_ID

Override the team color of filtered units.

MAKE_HERO ID_STRING

Give an existing unit a hero overlay

UNMAKE_HERO ID_STRING

Remove the hero overlay from a unit

FLAG_VARIANT NAME

Enable the specified flag variant: knalgan, loyalist, ragged, long, undead, or wood-elvish. Use within a [side] block; only affects that side. Since the ragged variant has six frames instead of the usual four, for that flag it's better to use FLAG_VARIANT6 below instead.

FLAG_VARIANT6 NAME

Like FLAG_VARIANT, but this supports flags with six frames. Currently only the ragged flag has six frames.

ANIMATED_MAUSOLEUM X Y

Embed this at scenario toplevel, not within an event. Note that it will freeze while dialogue popups are onscreen.

From file: interface-utils.cfg

Interface shortcut macros.

HIGHLIGHT_IMAGE X Y IMAGE BACKGROUND_VALUE

Scrolls to the given location, blinks the given image in and out a few times, and then leaves the image in place. Use this to pinpoint an important location to the player. If there's an existing [item] on the location, specify it as the BACKGROUND_VALUE or else it'll get lost during the blinking.

CLEAR_FOG SIDE X Y RADIUS

Clears fog in a specific area for the given side. This will persist until {UNCLEAR_FOG} (below) is used.

UNCLEAR_FOG

Restores fog that was temporarily cleared (check CLEAR_FOG above). Only one UNCLEAR_FOG is required no matter how many times CLEAR_FOG was used.

SET_LABEL X Y STRING

Puts STRING on the map at X,Y. Strictly a syntactic shortcut.

For example:

 {SET_LABEL 4 7 ( _ "There be dragons here!")}
REMOVE_LABEL X Y

Removes a label from a given tile.

For example, remove it from 4,7

 {REMOVE_LABEL 4 7}
FAKE_UNIT_MOVE FROM_X TO_X FROM_Y TO_Y SIDE TYPE MODIFIER_WML

Moves a fake unit using TYPE's animations, from (FROM_X, FROM_Y) to (TO_X, TO_Y). You can also specify modifiers that change the baseframe displayed by unit's gender or variation, or none at all.

Example:

 {FAKE_UNIT_MOVE 1 2 1 2 1 (Dark Adept) (
     gender=female
     variation=fancy
 )}
SCROLL X Y

Scrolls the screen by the specified offsets

For example, let's scroll 5 right and 3 down:

 {SCROLL 5 3}
SCROLL_TO X Y

Scrolls the screen to focus on the specified coordinates

For example, let's focus on 26,35:

 {SCROLL 26 35}
QUAKE SOUND

Visuals and sound for an earth tremor.

EARTHQUAKE ACTION_WML

Creates an earthquake-effect while performing ACTION_WML For example we could kill all non-leader units in the earthquake:

 {EARTHQUAKE (
   [kill]
       canrecruit=no
       animate=yes
   [/kill]
 )}
COLOR_ADJUST RED GREEN BLUE

Adjusts the color of the screen by a tint or red, green and blue for example, let's make it very blueish:

 {COLOR_ADJUST 0 0 100}
FLASH_WHITE ACTION_WML

Flash the screen momentarily white.

FLASH_RED ACTION_WML

Flash the screen momentarily red.

FLASH_GREEN ACTION_WML

Flash the screen momentarily green.

FLASH_BLUE ACTION_WML

Flash the screen momentarily blue.

THUNDER ACTION_WML

Creates a thunder-and-lightning effect while performing ACTION_WML. For example, player 3 might disappear in the flash of lightning:

 {THUNDER (
   [store_unit]
       [filter]
           side=3
       [/filter]
       variable=player3
       kill=yes
   [/store_unit]
 )}
FADE_TO_BLACK

Fades the screen to black. Use {FADE_IN} to return to normal

FADE_TO_BLACK_HOLD TIME

Fades the screen to black and then pauses for TIME milliseconds. Use {FADE_IN} to return to normal

FADE_IN

Brings the screen back from a {FADE_TO_BLACK}

From file: items.cfg

Macros for items and objects

PICKUPPABLE_ITEM ID X Y CAN_TAKE_FILTER_WML IMAGE TEXT TAKE_IT_STRING LEAVE_IT_STRING CANNOT_TAKE_TEXT OBJECT_WML

This places an item on the map which can be picked up once, but allows the player to choose whether the unit stepping on it should take it or not. The "object" doesn't necessarily need to be an [object], any action works.

An example which shows the:

 {PICKUPPABLE_ITEM ring_of_hp 8 12 race=human items/ring-red.png
     _"$unit.name finds a pretty ring. Should he pick it up?"
     _"ring of HP^Take it"
     _"ring of HP^Leave it"
     _"$unit.name finds a pretty ring. But only a human can take it!" (
     [object]
         name= _ "Ring of HP"
         image=items/ring-red.png
         description= _ "This ring grants the wearer +10 max hp!"

         [effect]
             apply_to=hitpoints
             increase_total=10
         [/effect]
     [/object]
 )}
LIGHTNING_ANIMATION NAME_STRING DIRECTION_NUMBER

"Effect generating a new animation that throws lightning in a specified direction."

From file: scenario-utils.cfg

Utility macros for scenario-objective control.

NO_MAP_DATA

The display code in the game becomes confused if you give it a scenario with no map data (like, a text epilogue). Use this macro to feed it dummy map data that won't actually be used.

AI_CANT_PLAY SIDES

Displays a standard warning at the start of the first AI turn for each given side about the AI not knowing how to play this side properly. Use this to tag sides intended solely for human players in special multiplayer scenarios (ones with shops, custom right-click options and such).

Example:

 {AI_CANT_PLAY 1,2,3,4}

From file: side-utils.cfg

LIMIT_CONTEMPORANEOUS_RECRUITS SIDES TYPE LIMIT_NUMBER

Limit the number of units passing a specified filter that a side can have simultaneously. When the number of matching units side has reaches or exceeds LIMIT_NUMBER, that side is prevented from recruiting more until the number of units of that type drops below LIMIT_NUMBER again.

Allow sides 2 and 3 no more than 2 Troll Rocklobbers at a time

 {LIMIT_CONTEMPORANEOUS_RECRUITS 2,3 "Troll Rocklobber" 2}
LIMIT_RECRUITS SIDE TYPE LIMIT_NUMBER

Limit the total number of units passing a specified filter that a given side can recruit in the scenario.

Allow side 2 no more than 1 Draug in the entire scenario

 {LIMIT_RECRUITS 2 Draug 1}
CAPTURE_VILLAGES_OF_TYPE TERRAIN SIDE X Y RADIUS

Change ownership of the villages on a specified terrain type near a specified location.

CAPTURE_VILLAGES SIDE X Y RADIUS

Change ownership of all villages near a specified location.

STARTING_VILLAGES SIDE RADIUS

Macro to make a side start a scenario with villages. Creates an event, so it must be called from within the toplevel scenario tag. Also note that this relies on the side having a unit with canrecruit-yes at start; if it doesn't, you should use STARTING_VILLAGES_AREA instead.

STARTING_VILLAGES_AREA SIDE X Y RADIUS

Make a side start with ownership of villages in a given area. Creates an event, so it must be called from within the toplevel scenario tag.

STARTING_VILLAGES_ALL SIDE

Make a side start with ownership of all villages. Creates an event, so it must be called from within the toplevel scenario tag.

TRANSFER_VILLAGE_OWNERSHIP FROM_SIDE TO_SIDE

Transfers ownership of all villages of one side to another side. Useful when you're for example moving all units of some side to another, and want to transfer the village ownership as well.

From file: sound-utils.cfg

Music control macros, and declarations of sound resource lists.

As of 1.1.3, music is parsed as follows:

 1. the [scenario]-level [music] tag
 2. the [story]-level music key
 3. any [event]-level [music] tags

If you change the music at a lower level, the tags above it will NOT be re-parsed and your scenario will sound wrong. For example, if you set scenario music with the normal [scenario]-level music tag but change the music during the [story], it is never reset back to normal. Therefore, these macros are intended to catch instances like that. Of course, if you want something more elaborate, code it manually.

DEFAULT_MUSIC_PLAYLIST

A macro to define a standard playlist suitable for any level. The music is defined twice to catch instances where music is changed in a story and not set back.

FULL_MUSIC_PLAYLIST

A macro to define a playlist of all tracks in alphabetical order. The music is defined twice to catch instances where music is changed in a story and not set back

SCENARIO_MUSIC MUSIC

This music macro ensures that the correct music is selected for a scenario just in case it is changed by [story]. It should be positioned at the top of the scenario file so it can be overridden by other prestart or start events.

It also allows for the convenient use of standardized intra-scenario music, should we decide to use one.

EXTRA_SCENARIO_MUSIC MUSIC

Use this immediately after the above SCENARIO_MUSIC macro to append extra tracks to the playlist.

Example:

 {SCENARIO_MUSIC battle.ogg}
 {EXTRA_SCENARIO_MUSIC knolls.ogg}
 {EXTRA_SCENARIO_MUSIC frantic.ogg}
INTRO_AND_SCENARIO_MUSIC INTRO_MUSIC SCENARIO_MUSIC

This works as SCENARIO_MUSIC does, except that it allows you to specify the music used for the story screen (if any) as well.

LET_INTRO_MUSIC_FINISH

Use immediately following INTRO_AND_SCENARIO_MUSIC, to let the intro music finish before switching to scenario music.

INCIDENTAL_MUSIC MUSIC

To be played immediately to mark an incident, but not appended to the scenario playlist. The playlist will be resumed afterwards.

APPEND_MUSIC MUSIC

Append to playlist. Meant to be used after REPLACE_SCENARIO_MUSIC.

REPLACE_SCENARIO_MUSIC MUSIC

To be used mid-scenario to replace the current playlist.

SOUND:HIT_AND_MISS HITSOUND MISSSOUND TIME

A more convenient way of wiring in hit and miss sounds to an attack animation. Just specify the sounds to use and the time when they should trigger.

SOUND:HIT HITSOUND TIME

A more convenient way of wiring in hit only sounds to an attack animation. Just specify the sound to use and the time when it should trigger.

From file: teleport-utils.cfg

Macros for teleporting units.

TELEPORT_UNIT FILTER X Y

Teleports a unit matching FILTER to X,Y

For example, teleport player 3's leader to 4,5

 {TELEPORT_UNIT (
 	side=3
 	canrecruit=yes
 ) 4 5}
TELEPORT_TILE OLD_X OLD_Y NEW_X NEW_Y

Teleports a unit on tile OLD_X,OLD_Y to NEW_X,NEW_Y

For example, teleport any unit that's currently on 1,1 to 4,5

 {TELEPORT_TILE 1 1 4 5}
TELEPORT_OUT_ANIMATION

Generalized silver mage teleport out (disappear) animation

For example, to apply a teleport animation to a custom unit definition:

[animation]
    apply_to=pre_teleport
    {TELEPORT_OUT_ANIMATION}
[/animation]
TELEPORT_IN_ANIMATION

Generalized silver mage teleport in (reappear) animation

For example, to apply a teleport animation to a custom unit definition:

[animation]
    apply_to=post_teleport
    {TELEPORT_IN_ANIMATION}
[/animation]
TELEPORT_EFFECT_OBJECT_ID _ID_

Creates and assigns a temporary object which applies the generalized silver mage teleport animations to the unit with the matching ID

For example, to apply teleport animations to the unit 'Bob':

{TELEPORT_EFFECT_OBJECT_ID Bob}
TELEPORT_EFFECT_OBJECT

Creates and assigns a temporary object which applies the generalized silver mage teleport animations to the primary unit

For example, to apply teleport animations to the unit that triggered a 'move_to' event:

{TELEPORT_EFFECT_OBJECT}

From file: terrain-utils.cfg

Utility macros for manipulating map terrain and overlays.

MODIFY_TERRAIN TERRAIN X_SPAN Y_SPAN

Changes the terrain at a given list of coordinates

For example, we could make 14,15 and 14,16 grassland:

 {MODIFY_TERRAIN Gg (14,14) (15,16)}
MODIFY_TERRAIN_MASK X Y MASK_VALUE RULES_WML

Changes the terrain for a given area

SCATTER_IMAGE FILTER NUMBER IMAGE

Place NUMBER copies of the IMAGE on map hexes matching FILTER.

This call will scatter 20 copies of a pine-tree graphic over grassland:

 {SCATTER_IMAGE (terrain=Gg) 20 scenery/pine1.png}
SCATTER_EMBELLISHMENTS TERRAINLIST EMBELLISHMENT_NAME PERCENTAGE

Adds the given embellishment to the given percentage of the given terrain on the map.

For example, this will add flowers to 5% of all grassland:

 {SCATTER_EMBELLISHMENTS G* ^Efm 5}

From file: traits.cfg

Traits for the [modifications] clause of SingleWML descriptions

TRAIT_LOYAL

Units with trait Loyal have no upkeep.

TRAIT_UNDEAD

Units with trait Undead cannot be drained, poisoned, or plagued.

TRAIT_MECHANICAL

Units with trait Mechanical cannot be drained, poisoned, or plagued.

TRAIT_ELEMENTAL

Units with trait Elemental cannot be drained, poisoned, or plagued.

TRAIT_STRONG

Units with trait Strong get a +1 increment in hitpoints and melee damage.

TRAIT_DEXTROUS

Units with trait Dextrous get a +1 to ranged damage.

TRAIT_QUICK

Units with trait Quick have +1 movement and 5% less hitpoints.

TRAIT_INTELLIGENT

Units with trait Intelligent get a 20% decrease in XP required to advance.

TRAIT_RESILIENT

Units with trait Resilient get 4 more HP plus 1 per level.

TRAIT_HEALTHY

Units with trait Healthy get 1 more HP plus 1 per level and always rest heal.

TRAIT_FEARLESS

Units with trait Fearless fight normally during unfavorable day/night times.

TRAIT_FEARLESS_MUSTHAVE

A clone of the above that would be generated even if random trait generation is not used. This is needed for WCs and Soullesses

TRAIT_FERAL_MUSTHAVE

Units with trait Feral only receive 50% defense in villages regardless of the base terrain the village is on.

TRAIT_WEAK

Units with trait Weak get a -1 increment in hitpoints and melee damage.

TRAIT_SLOW

Units with trait Slow have -1 movement and 5% more hitpoints.

TRAIT_DIM

Units with trait Dim get a 20% increase in XP required to advance.

TRAIT_AGED

Units with trait Aged get a 8 points HP decrease and have -1 movement and melee damage.

From file: unit-utils.cfg

This file contains unit utility macros for WML authors.

These don't rely on any other macros. Please don't change this.

UNIT SIDE TYPE X Y WML

Place a unit with embedded WML specified.

GENERIC_UNIT SIDE TYPE X Y

Creates a generic unit of TYPE belonging to SIDE at X,Y, which has a random name, gender and traits (just like a recruited unit).

NOTRAIT_UNIT SIDE TYPE X Y

Creates a unit with no traits, random gender and generated name.

Example:

 {NOTRAIT_UNIT 1 (Elvish Fighter) 19 16}
LOYAL_UNIT SIDE TYPE X Y

Creates a unit with the Loyal trait.

Example:

 {LOYAL_UNIT 1 (Elvish Fighter) 19 16}
NAMED_UNIT SIDE TYPE X Y ID_STRING NAME_STRING WML

Place a named unit with embedded WML specified.

NAMED_LOYAL_UNIT SIDE TYPE X Y ID_STRING NAME_STRING

Creates a unit with the Loyal trait.

Example:

 {NAMED_LOYAL_UNIT 1 (Elvish Fighter) 19 16 (Myname) ( _ "Myname")}
NAMED_GENERIC_UNIT SIDE TYPE X Y ID_STRING NAME_STRING

Creates a generic unit of TYPE belonging to SIDE at X,Y, which has a generated gender and traits (just like a recruited unit).

NAMED_NOTRAIT_UNIT SIDE TYPE X Y ID_STRING NAME_STRING

Creates a unit with no traits, random gender and specified name.

Example:

 {NAMED_NOTRAIT_UNIT 1 (Elvish Fighter) 20 22 (Mochi) (_"Mochi") }
RECALL_XY ID_STRING X Y

Note that id precedes x and y, unlike with the unit-generating macros.

GUARDIAN

Meant to be used as a suffix to a unit-generating macro call.

NO_UPKEEP

Meant to be used as a suffix to a unit-generating macro call. Use this when you don't want to use up a traits slot.

FACING DIRECTION

Meant to be used as a suffix to a unit-generating macro call.

VARIATION VARIATION_NAME

Meant to be used as a suffix to a unit-generating macro call.

STORE_UNIT_VAR FILTER VAR TO_VAR_NAME

Stores an attribute of a unit to the given variable.

Example where this is used to flip all orcs to whatever side James is on:

 {STORE_UNIT_VAR (id=James) side side_of_James}
 {MODIFY_UNIT (race=orc) side $side_of_James}
ADVANCE_UNIT FILTER ID_STRING

Advances all units matching the filter to ID_STRING or if missing, their normal advancement

Example to advance all spearmen to a cavalrymen:

 {ADVANCE_UNIT type=Spearman Cavalryman}

Example to advance your leader normally:

 {ADVANCE_UNIT canrecruit,side=yes,1 ""}
TRANSFORM_UNIT FILTER TYPE

Transforms all units matching the filter into TYPE or if missing, their normal advancement Keeps the unit's hitpoints, experience and status intact.

Example to turn all spearmen into cavalrymen:

 {TRANSFORM_UNIT type=Spearman Cavalryman}

From file: utils.cfg

This file contains general utility macros for WML authors.

Later macros in this file are built using earlier ones, which is why they live here rather than being broken out into topic-specific files.

QUANTITY NAME EASY_VALUE NORMAL_VALUE HARD_VALUE

Macro to define a 'quantity' differently based on difficulty levels. ifdef EASY

QUANTITY4 NAME EASY_VALUE NORMAL_VALUE HARD_VALUE NIGHTMARE_VALUE

Four-difficulty version of QUANTITY ifdef EASY

TURNS EASY_AMOUNT NORMAL_AMOUNT HARD_AMOUNT

Macro to define number of turns for different difficulty levels.

TURNS4 EASY_AMOUNT NORMAL_AMOUNT HARD_AMOUNT NIGHTMARE_AMOUNT

Four-difficulty version of TURNS

GOLD EASY_AMOUNT NORMAL_AMOUNT HARD_AMOUNT

Macro which will let you say {GOLD x y z} to set starting gold depending on easy/medium/hard - x/y/z

GOLD4 EASY_AMOUNT NORMAL_AMOUNT HARD_AMOUNT NIGHTMARE_AMOUNT

Four-difficulty version of GOLD

INCOME EASY_AMOUNT NORMAL_AMOUNT HARD_AMOUNT

Macro which will let you say {INCOME x y z} to set per-turn income depending on easy/medium/hard - x/y/z

INCOME4 EASY_AMOUNT NORMAL_AMOUNT HARD_AMOUNT NIGHTMARE_AMOUNT

Four-difficulty version of INCOME

NO_INCOME

Used to specify when a side should not have any income every turn.

ATTACK_DEPTH EASY_VALUE NORMAL_VALUE HARD_VALUE

Macro to define AI attack depth for different difficulty levels (set it to 1-6)

ATTACK_DEPTH4 EASY_VALUE NORMAL_VALUE HARD_VALUE NIGHTMARE_VALUE

Four-difficulty version of ATTACK_DEPTH

NO_SCOUTS

Macro to make an AI team not recruit scouts.

RANDOM THING_VALUE

Macro to quickly pick a random value (in the $random variable, to avoid cluttering up savegames with such temporary variables).

VARIABLE VAR VALUE

Macro to initialize a variable. Strictly a syntatic shortcut.

GLOBAL_VARIABLE NAMESPACE LOCAL_VAR_NAME GLOBAL_VAR_NAME SIDE

Assigns a persistent variable with the contents of a standard variable.

VARIABLE_FROM_GLOBAL NAMESPACE GLOBAL_VAR_NAME LOCAL_VAR_NAME SIDE

Retrieves the contents of a persistent variable and stores them in a standard variable.

VARIABLE_OP VAR OP_NAME VALUE

Macro to do mathematical operations on variables.

VARIABLE_CONDITIONAL VAR OP_NAME VALUE

Macro to do conditional operations on variables.

CLEAR_VARIABLE VAR_NAME

Macro to clear a variable previously set.

CLEAR_GLOBAL_VARIABLE NAMESPACE MY_VARIABLE_NAME SIDE

Clears a persistent variable entirely.

REPEAT NUMBER BODY_WML

Macro to execute some WML a defined number of times.

Example that causes screen to quake 5 times:

 {REPEAT 5 (
     {QUAKE "rumble.ogg"}
 )}
LOOKUP_INDEX FROM_ARRAY_NAME WHERE_KEY_NAME WHERE_VALUE SAVE_AS_NAME

Call this to lookup an array element that has a particular key-value pair then it saves the index of that element, or if the key-value pair is not found it saves the array's length

LOOKUP_VALUE FROM_ARRAY_NAME WHERE_KEY_NAME WHERE_VALUE SAVE_KEY_NAME DEFAULT_VALUE SAVE_AS_NAME

Call this to look up an array element that has a particular key-value pair then it saves another key from that same element.

MODIFY_UNIT FILTER VAR VALUE

Alters a unit variable (such as unit.x, unit.type, unit.side), handling all the storing and unstoring.

Example that flips all spearmen to side 2:

 {MODIFY_UNIT type=Spearman side 2}
MOVE_UNIT_BY FILTER OFFSET_X OFFSET_Y

TODO COMMENT

MOVE_UNIT FILTER TO_X TO_Y

Moves a unit from its current location to the given location, displaying movement normally.

Note that setting the destination on an existing unit does not kill either one, but causes the unit to move to the nearest vacant hex instead.

PUT_TO_RECALL_LIST FILTER

This places a given unit back to the recall list of the side it is on. Note however, that the unit is not healed to full health, so when recalled (even if not until the next scenario) the unit may have less than his maximum hp left.

An example that returns all units stepping on (20,38) back to the recall list:

 [event]
     name=moveto

     [filter]
         x,y=20,38
     [/filter]

     {PUT_TO_RECALL_LIST x,y=20,38}
 [/event]
RECRUIT_UNIT_VARIATIONS SIDE TYPE VARIATIONS_VALUE

Allows a side to seemingly recruit variations of a given unit, such as the the Walking Corpse.

An example which makes side 2 have a 50% chance of getting a normal WC and a 50% chance of getting either a drake or dwarf variation:

 {RECRUIT_UNIT_VARIATIONS 2 "Walking Corpse" none,none,drake,dwarf}
SCATTER_UNITS NUMBER TYPES PADDING_RADIUS FILTER UNIT_WML

Scatters the given kind of units randomly on a given area on the map.

An example which scatters some loyal elves on forest hexes in x,y=10-30,20-40, at a minimum of three hexes apart from each other and never on top of or adjacent to any already existing units:

 {SCATTER_UNITS 20 "Elvish Fighter,Elvish Archer,Elvish Shaman" 3 (
     terrain=Gs^Fp
     x=10-30
     y=20-40

     [not]
         [filter]
         [/filter]
     [/not]

     [not]
         [filter_adjacent_location]
             [filter]
             [/filter]
         [/filter_adjacent_location]
     [/not]
 ) (
     side=2
     generate_name=yes
     random_traits=yes

     [modifications]
         {TRAIT_LOYAL}
     [/modifications]
 )}
FORCE_CHANCE_TO_HIT FILTER SECOND_FILTER CTH_NUMBER EXTRA_CONDITIONS_WML

Invisibly forces certain units to always have a specific chance to hit when fighting against certain other units.

Note that the player still only sees the regular damage calculations, so this is useful if you need to give an invisible helping hand to the player or AI. For example, if the player is forced to attack with only a couple of units at the beginning of a scenario, you can use this to ensure that simply having bad luck cannot ruin their attempt so easily. Also you might have enemy leaders which the player is not supposed to fight or be able to defeat due to storyline reasons, but could theoretically still kill with some clever trick, AI mistake or sheer exceptional luck.

An example which forces Konrad's attacks to always hit Li'sar, but only after turn 10:

 {FORCE_CHANCE_TO_HIT id=Konrad id="Li'sar" 100 (
     [variable]
         name=turn_number
         greater_than=10
     [/variable]
 )}