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.

Documented files:

[ top ]

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_EXTRA_HEAL: No documentation available for this macro.
ABILITY_UNPOISON: No documentation available for this macro.
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_SELF_HEAL: Canned definition of the regenerate 4 hp ability, to be included in an [abilities] clause.
ABILITY_STEADFAST: Canned definition of the Steadfast ability to be included in an [abilities] clause.
ABILITY_DIVERSION: Canned definition of the Distraction 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 Optional arguments: HALO: 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_BURROW: Canned definition of the Burrow 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. This works because of data/lua/feeding.lua

[ top ]

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 main_loop special_poisoning_formula} example: {MODIFY_AI_DELETE_CANDIDATE_ACTION 1 main_loop 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 main_loop special_poisoning_formula} example: {MODIFY_AI_TRY_DELETE_CANDIDATE_ACTION 1 main_loop 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

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

The attack_depth aspect has no effect on the AI any more.

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_FORMULA_AI_EXPERIMENTAL_RECRUITMENT

No documentation available for this macro.

_AI_ASPECT_LEADER_GOAL_MOVE_TO X Y AUTOREMOVE_VALUE

No documentation available for this macro.

_AI_ASPECT_LEADER_GOAL_RISKY_MOVE_TO X Y AUTOREMOVE_VALUE

No documentation available for this macro.

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

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.15.

Use ai_algorithm=experimental_ai in the [ai] tag instead Note: The Experimental AI and the default AI are currently almost identical. This is a placeholder for future development. Put this into the [side][ai] tag. Does not work in [modify_side][ai] or [modify_ai] at the moment.

CUSTOMIZABLE_EXPERIMENTAL_AI ARGS

Note: The Experimental AI and the default AI are currently almost identical. However, this macro allows the use of custom parameters. Use the Experimental AI with custom parameter setting Put this into the [side][ai] tag. Does not work in [modify_side][ai] or [modify_ai] at the moment.

[ top ]

From file: `ai_candidate_actions.cfg`

AI_CA_GOTO_SCORE

No documentation available for this macro.

AI_CA_RECRUIT_RUSHERS_SCORE

No documentation available for this macro.

AI_CA_CASTLE_SWITCH_SCORE

No documentation available for this macro.

AI_CA_RETREAT_INJURED_SCORE

No documentation available for this macro.

AI_CA_GRAB_VILLAGES_SCORE

No documentation available for this macro.

AI_CA_SPREAD_POISON_SCORE

No documentation available for this macro.

AI_CA_RECRUITMENT_SCORE

No documentation available for this macro.

AI_CA_MOVE_LEADER_TO_GOALS_SCORE

No documentation available for this macro.

AI_CA_MOVE_LEADER_TO_KEEP_SCORE

No documentation available for this macro.

AI_CA_HIGH_XP_ATTACK_MAX_SCORE

No documentation available for this macro.

AI_CA_COMBAT_SCORE

No documentation available for this macro.

AI_CA_PLACE_HEALERS_SCORE

No documentation available for this macro.

AI_CA_HEALING_SCORE

No documentation available for this macro.

AI_CA_VILLAGES_SCORE

No documentation available for this macro.

AI_CA_RETREAT_SCORE

No documentation available for this macro.

AI_CA_VILLAGE_HUNT_SCORE

No documentation available for this macro.

AI_CA_MOVE_TO_TARGETS_SCORE

No documentation available for this macro.

AI_CA_LEADER_SHARES_KEEP_SCORE

No documentation available for this macro.

AI_CA_MOVE_TO_ANY_ENEMY_SCORE

No documentation available for this macro.

AI_CA_PASSIVE_LEADER_SHARES_KEEP_SCORE

No documentation available for this macro.

AI_CA_GOTO

RCA AI candidate action: goto

AI_CA_RECRUIT_RUSHERS

RCA AI candidate action: recruit_rushers

AI_CA_CASTLE_SWITCH

RCA AI candidate action: castle_switch

AI_CA_RETREAT_INJURED

RCA AI candidate action: retreat_injured

AI_CA_GRAB_VILLAGES

RCA AI candidate action: grab_villages

AI_CA_SPREAD_POISON

RCA AI candidate action: spread_poison

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_HIGH_XP_ATTACK

No documentation available for this macro.

AI_CA_COMBAT

RCA AI candidate action: combat

AI_CA_PLACE_HEALERS

RCA AI candidate action: place_healers

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_VILLAGE_HUNT

RCA AI candidate action: village_hunt

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_MOVE_TO_ANY_ENEMY

RCA AI candidate action: move_to_any_enemy

AI_CA_PASSIVE_LEADER_SHARES_KEEP

No documentation available for this macro.

AI_CA_SIMPLE_MOVE_TO_TARGETS

No documentation available for this macro.

AI_CA_POISONING

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A poisoning CA is now included in the default AI. If you're building a custom main_loop stage it can also be included with {AI_CA_SPREAD_POISON}. Extra candidate action: Formula AI CA for poisoners to spread poison around

[ top ]

From file: `ai_controller.cfg`

AI_CONTROLLER_ALLOW_UNIT_CONTROL CONTROLLER_SIDE UNIT_ID

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided. Right-click content menu item for issuing instructions to an allied AI unit

AI_CONTROLLER_ALLOW_LEADER_CONTROL CONTROLLER_SIDE CONTROLLED_SIDE

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided. Right-click content menu item for issuing instructions to an allied AI side's leader

AI_CONTROLLER_NOTE

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided. Note for the objectives that instructions can be issued to an allied AI side

AI_CONTROLLER AFFIX PLAYER_SIDES ALLY_SIDES VARIABLES_WML

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided. Right-click content menu item for issuing instructions to an allied AI side

DISABLE_AI_CONTROLLER AFFIX

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided.

DISABLE_AI_CONTROLLER_FOR_SIDE AFFIX SIDE

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided.

ENABLE_AI_CONTROLLER_FOR_SIDE AFFIX SIDE

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided.

AI_LOCATION AFFIX STRING RADIUS X Y

No documentation available for this macro.

AI_CONTROLLER_FUTURE_STRINGS

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

A replacement is not currently provided. These will be used for the special orders menu and the order for telling the ally leader to move someplace

[ top ]

From file: `amla.cfg`

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

AMLA_DEFAULT: Canned definition of the default AMLA.

[ top ]

From file: `animation-utils.cfg`

Macros for setting animations.

STANDING_ANIM_DIRECTIONAL BASE_SE_IMAGE BASE_NE_IMAGE: No documentation available for this macro.
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
TEACHING_ANIM FULL_IMAGE HALFWAYS_IMAGE OFFSET_POSITION ATTACK: 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_DIRECTIONAL REACTION_SE_IMAGE BASE_SE_IMAGE REACTION_NE_IMAGE BASE_NE_IMAGE HIT_SOUND: No documentation available for this macro.
DEFENSE_ANIM_DIRECTIONAL_RANGE REACTION_SE_IMAGE BASE_SE_IMAGE REACTION_NE_IMAGE BASE_NE_IMAGE HIT_SOUND RANGE: No documentation available for this macro.
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.
STANDING_COMBAT_FILTER: Units next to enemies should not have idle animations
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 Optional arguments: IPF: 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.
HALO_FRAME_SAURIAN: No documentation available for this macro.
MISSILE_FRAME_ICE: No documentation available for this macro.
MISSILE_FRAME_HATCHET: Animate a projectile for a thrown-hatchet attack.
FIRE_BURST_SMALL: No documentation available for this macro.
LIGHTNING_BOLT DIRECTION_NUMBER: No documentation available for this macro.
MAGIC_MISSILE OFFSET_X OFFSET_Y: No documentation available for this macro.
MAGIC_MISSILE_STAFF_FLARE START_TIME DURATION_TIME OFFSET_X OFFSET_Y: No documentation available for this macro.
MERMAID_STAFF_FLARE OFFSET_X OFFSET_Y: No documentation available for this macro.
MERMAID_WATER_BLAST_HALO: No documentation available for this macro.
MISSILE_FRAME_MUZZLE_FLARE_MISS X Y: No documentation available for this macro.
MISSILE_FRAME_MUZZLE_FLARE_HIT_NORTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_MUZZLE_FLARE_HIT_SOUTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_MUZZLE_FLARE_HIT_DIAG_NORTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_MUZZLE_FLARE_HIT_DIAG_SOUTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_DG_SECOND_MUZZLE_FLARE_HIT_NORTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_DG_SECOND_MUZZLE_FLARE_HIT_SOUTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_DG_SECOND_MUZZLE_FLARE_HIT_DIAG_NORTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_DG_SECOND_MUZZLE_FLARE_HIT_DIAG_SOUTH START_X START_Y: No documentation available for this macro.
MISSILE_FRAME_STONE_HIT OFFSET_X OFFSET_Y: No documentation available for this macro.
MISSILE_FRAME_STONE_MISS OFFSET_X OFFSET_Y: No documentation available for this macro.
MISSILE_FRAME_CHILL_WAVE X Y: No documentation available for this macro.
MISSILE_FRAME_CHILL_TEMPEST X Y: No documentation available for this macro.
MISSILE_FRAME_SHADOW_WAVE: No documentation available for this macro.
DRAKE_UNWALKABLE_TERRAINS: No documentation available for this macro.
DRAKE_STANDING_ANIM DRAKE_NAME: No documentation available for this macro.
DRAKE_FIRE_ANIM DRAKE_NAME DIRECTION_SUFFIX DIRECTION OFFSET_X OFFSET_Y: No documentation available for this macro.
DRAKE_FIRE_ANIM_S_DIAGONAL DRAKE_NAME OFFSET_POSITION: No documentation available for this macro.
DRAKE_FIRE_ANIM_N_DIAGONAL_CURRENT DRAKE_NAME OFFSET_POSITION: No documentation available for this macro.
DRAKE_FIRE_ANIM_S DRAKE_NAME OFFSET_POSITION: No documentation available for this macro.
DRAKE_FIRE_ANIM_N_CURRENT DRAKE_NAME OFFSET_POSITION: No documentation available for this macro.
DRAKE_MOVEMENT_ANIM DRAKE_NAME: No documentation available for this macro.
DRAKE_WEAPON_ANIM DRAKE_NAME: No documentation available for this macro.
STANDING_ANIM_BIG_TORCH IMG X X2 Y Optional arguments: IMG_NE X_NE Y_NE: No documentation available for this macro.
STANDING_ANIM_SMALL_TORCH IMG X X2 Y Optional arguments: IMG_NE X_NE Y_NE: No documentation available for this macro.

[ top ]

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.
ATTACK_ANIM_DIRECTIONAL_9_FRAME BASE_IMAGE_NAME TAIL_IMAGE_NAME HIT_SOUND MISS_SOUND: No documentation available for this macro.
ATTACK_ANIM_DIRECTIONAL_10_FRAME BASE_IMAGE_NAME TAIL_IMAGE_NAME HIT_SOUND MISS_SOUND: No documentation available for this macro.
ATTACK_ANIM_QUAD_DIRECTIONAL_10_FRAME BASE_IMAGE_NAME TAIL_IMAGE_NAME HIT_SOUND MISS_SOUND: No documentation available for this macro.
ATTACK_ANIM_QUAD_DIRECTIONAL_12_FRAME BASE_IMAGE_NAME TAIL_IMAGE_NAME HIT_SOUND MISS_SOUND: No documentation available for this macro.
DEATH_ANIM_DIRECTIONAL_4_FRAME BASE_IMAGE_NAME: No documentation available for this macro.
STANDING_ANIM_DIRECTIONAL_6_FRAME_FILTERED BASE_IMAGE_NAME FILTER: No documentation available for this macro.
STANDING_ANIM_DIRECTIONAL_6_FRAME BASE_IMAGE_NAME: No documentation available for this macro.
STANDING_ANIM_DIRECTIONAL_8_FRAME_FILTERED BASE_IMAGE_NAME FILTER: No documentation available for this macro.
STANDING_ANIM_DIRECTIONAL_8_FRAME BASE_IMAGE_NAME: No documentation available for this macro.
MOVING_ANIM_DIRECTIONAL_8_FRAME BASE_IMAGE_NAME: No documentation available for this macro.
MOVING_ANIM_SOUTH_9_FRAME BASE_IMAGE_NAME: No documentation available for this macro.
MOVING_ANIM_DIRECTIONAL_10_FRAME BASE_IMAGE_NAME: No documentation available for this macro.
MOVING_ANIM_DIRECTIONAL_12_FRAME BASE_IMAGE_NAME: No documentation available for this macro.

[ top ]

From file: `carryover-utils.cfg`

Utility macros for defining carryover gold, mostly in the [endlevel] tag. Macros for describing the current scenario's carryover in the objectives dialog are in objective-utils.cfg.

NEW_GOLD_CARRYOVER PERCENTAGE_NUMBER: No documentation available for this macro.

[ top ]

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]
 )}

[ top ]

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]

[ top ]

From file: `deprecated-utils.cfg`

These are clutter, scheduled to be removed.

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.

DEPRECATED_UNIT OLD_NAME NEW_NAME VERSION_NAME

Tag [unit_type] for removal, where VERSION_NAME is the the next development series from the date of deprecation. NEW_NAME can be an empty string to indicate that there's no replacement. Place this macro in the [unit_type] definition.

EARLY_FINISH_BONUS_NOTE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.0.

This is now automatically generated and not required. Use [objectives][gold_carryover]bonus=yes instead.

NO_EARLY_FINISH_BONUS_NOTE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.0.

This is now automatically generated and not required. Use [objectives][gold_carryover]bonus=no instead.

NO_GOLD_CARRYOVER_NOTE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.0.

This is now automatically generated and not required. Use [objectives][gold_carryover]carryover_percentage=0 instead.

NEW_GOLD_CARRYOVER_NOTE_100

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.0.

This is now automatically generated and not required. Use [objectives][gold_carryover]carryover_percentage=100 instead.

NEW_GOLD_CARRYOVER_NOTE_40

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.0.

This is now automatically generated and not required. Use [objectives][gold_carryover]carryover_percentage=40 instead.

NEW_GOLD_CARRYOVER_NOTE_20

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.0.

This is now automatically generated and not required. Use [objectives][gold_carryover]carryover_percentage=20 instead.

MISSILE_FRAME_FIREBALL

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.15.

Use MISSILE_FRAME_FIREBALL_XY instead

MESSAGE SPEAKER_ID IMAGE CAPTION_TEXT MESSAGE_TEXT

Deprecated macro. Deprecation level: 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.."}

STORY_PART_SPEECH BACKGROUND_IMAGE SPEAKER_VALUE SPEECH_VALUE

Deprecated macro. Deprecation level: 1.

No documentation available for this macro.

LOYAL_UNDEAD_UNIT SIDE TYPE X Y

Deprecated macro. Deprecation level: 1.

Use LOYAL_UNIT instead Create a unit with the Undead and Loyal traits.

ON_SIGHTING ID SIGHTING_SIDE SIGHTED_FILTER ACTION_WML

Deprecated macro. Deprecation level: 2.

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 macro. Deprecation level: 2. Scheduled for removal in 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 macro. Deprecation level: 2. Scheduled for removal in 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

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.15.

Just put the persistent key in [side] directlyMacro to make a ai controlled side persistent. Needs to be placed below the side definition.

FOREACH ARRAY_VALUE VAR

Deprecated macro. Deprecation level: 1.

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

NEXT VAR

Deprecated macro. Deprecation level: 1.

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

DRAKE_FLYING_ANIM STANDING_IMAGE FLYING_IMAGE

Deprecated macro. Deprecation level: 2.

No documentation available 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.

ENABLE_NIGHTBLADE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.17.

This advancement is now enabled by default.

[ top ]

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

[ top ]

From file: `image-utils.cfg`

Utility macros for images, overlays, and display effects.

COLOR_HEAL

No documentation available for this macro.

COLOR_HARM

No documentation available for this macro.

COLOR_WHITE

No documentation available for this macro.

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.

PLACE_IMAGE_SUBMERGED IMAGE X Y

Place an image at a specified location on the map, submerging in water.

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_NONLOYAL ID_STRING

Removes the loyal trait from the unit.

MAKE_LOYAL_HERO ID_STRING

Makes the unit a hero unit.

MAKE_LOYAL_NORMAL ID_STRING

Makes the unit a regular loyal unit (not a hero).

MAKE_LOYAL_LEADER ID_STRING

Makes the unit a leader.

MAKE_HERO ID_STRING

Give an existing unit a hero overlay, without making them loyal.

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.

[ top ]

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 Optional arguments: EXTRA_WML

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_TO 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 terrain by a tint of red, green and blue for example, let's make it very blueish:

 {COLOR_ADJUST 0 0 100}

SCREEN_FADE RED GREEN BLUE DURATION

No documentation available for this macro.

SCREEN_UNFADE DURATION

No documentation available for this macro.

SCREEN_FADE_OUT

No documentation available for this macro.

SCREEN_FADE_IN

No documentation available for this macro.

FLASH RED GREEN BLUE ACTION_WML

Flash the screen this colour, performing the action during the flash. The action will be performed at the height of the flash, and the screen will still be slightly visible during the action. For example to flash the screen orange and play an explosion sound:

 {FLASH 255 128 0 (
     [sound]
         name=explosion.ogg
     [/sound]
 )}

FLASH_WHITE ACTION_WML

Flash the screen momentarily white, performing the given action during the flash.

FLASH_RED ACTION_WML

Flash the screen momentarily red, performing the given action during the flash.

FLASH_GREEN ACTION_WML

Flash the screen momentarily green, performing the given action during the flash.

FLASH_BLUE ACTION_WML

Flash the screen momentarily blue, performing the given action during the flash.

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]
 )}

FLASH_LIGHTNING ACTION_WML

Perform the given action WML with an accompanying lightning effect.

FADE_STEP_RGB RED GREEN BLUE DELAY_TIME

Defines a single step in a fade animation; used internally by the other fade macros.

FADE_STEP NUMBER DELAY_TIME

Defines a single step in a monochrome fade animation; used internally in the fade to black macros.

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}

WHISPER TEXT

No documentation available for this macro.

ASIDE TEXT

No documentation available for this macro.

CAPTION TEXT

No documentation available for this macro.

[ top ]

From file: `items.cfg`

Macros for items and objects

ITM_WISHINGWELL X Y

Places a wishing well that allows a player to drop in a coin to make a wish. There is no effect of the wish other than losing 1 gold.

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]
 )}

OBJ_POTION_HEALING X Y ID

Places a potion of healing that heals 10% of the unit's hitpoints. It can only be used once.

OBJ_POTION_POISON X Y ID

Places a poison potion that poisons the unit who uses it. It can only be used once.

OBJ_POTION_HOLY_COMMON X Y ID ARCANE

Places holy water that turns the unit's melee attacks into arcane attacks. It can only be used once.

OBJ_POTION_HOLY X Y ID

No documentation available for this macro.

SET_WEAPON_ARCANE

No documentation available for this macro.

OBJ_POTION_HOLY_ALT X Y ID

No documentation available for this macro.

OBJ_POTION_STRONG X Y ID

Places a potion of strength that increases the unit's damage by 1 per strike on melee attacks. It can only be used once.

OBJ_POTION_DECAY X Y ID

Places a potion of decay that damages 10% of the unit's hitpoints. It can only be used once.

OBJ_RING_REGENERATION X Y ID

Places a ring of regeneration that gives the unit a regenerates ability. It can only be used once.

OBJ_RING_SLOW X Y ID

Places a potion of slowness that slows the unit. It can only be used once.

OBJ_STAFF_SPEED X Y ID

Places a staff of speed that adds 2 movement ponts to the unit. It can only be used once.

LIGHTNING_ANIMATION NAME_STRING DIRECTION_NUMBER

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

OBJ_TRIDENT_STORM X Y ID

Places a storm trident that grants merfolk a lightning attack. It can only be used once.

SCEPTRE_OF_FIRE_EFFECT

Adds the Sceptre of Fire as an additional attack to a unit

[ top ]

From file: `movetypes.cfg`

LESS_NIMBLE_ELF: a special macro to define slightly less nimble elves such as fighters, who don't do quite so well in forest
WOODLAND_RESISTANCE: Resistance values for woodland creatures such as elves
FLY_MOVE: Standard movement costs for a flying unit
FLY_DEFENSE DEFENSE_NUMBER: Sets a fixed defense for all terrain types
FLY_RESISTANCE: Resistance values for a flying unit
MOUNTAIN_MOVE: Movement costs for a mountain unit such as a troll or dwarf
MOUNTAIN_DEFENSE: Defense values for a mountain unit such as a troll or dwarf
DRAKEFLY_MOVE: Standard movement costs for flying drakes.
DRAKEFLY_RESISTANCE: Standard resistances for flying drakes.

[ top ]

From file: `multiplayer.cfg`

RANDOM_SIDE: No documentation available for this macro.
QUICK_4MP_LEADERS: This makes all leaders with 4 MP receive the quick trait, except ones with unit.variables.dont_make_me_quick=yes (boolean)
TURNS_OVER_ADVANTAGE: No documentation available for this macro.
ERA_DEFAULT: No documentation available for this macro.
ERA_HEROES: No documentation available for this macro.

[ top ]

From file: `names.cfg`

Defines name generation rules for all of the standard races.

DRAKE_NAMES: No documentation available for this macro.
DWARVISH_NAMES: No documentation available for this macro.
ELVISH_NAMES: No documentation available for this macro.
GRYPHON_NAMES: No documentation available for this macro.
HUMAN_NAMES: No documentation available for this macro.
DUNEFOLK_NAMES: No documentation available for this macro.
LIZARD_NAMES: Saurian name generation rules
MERMAN_NAMES: No documentation available for this macro.
NAGA_NAMES: No documentation available for this macro.
OGRE_NAMES: No documentation available for this macro.
ORCISH_NAMES: No documentation available for this macro.
TROLL_NAMES: No documentation available for this macro.
WOSE_NAMES: No documentation available for this macro.
VILLAGE_NAMES: Name generation rules for villages on random maps

[ top ]

From file: `objective-utils.cfg`

Utility macros for use in the objectives dialog

TURNS_RUN_OUT: Adds an objective indicating that you lose when turns run out
OBJECTIVE_FOOTNOTE TEXT: No documentation available for this macro.
EARLY_FINISH_BONUS_FOOTNOTE: No documentation available for this macro.
ALTERNATIVE_OBJECTIVE_CAPTION: Add a caption for an alternative objective
BONUS_OBJECTIVE_CAPTION: Add a caption for a bonus objective
OPTIONAL_OBJECTIVE_CAPTION: Add a caption for an optional objective
ALTERNATIVE_OBJECTIVE OBJECTIVE_TEXT: Add an alternative objective that can be attained in place of the primary objective to win the scenario.
ALTERNATIVE_OBJECTIVE_BONUS OBJECTIVE_TEXT: Add an alternative objective that grants an early finish bonus.
IS_LAST_SCENARIO: Add a note to the objectives indicating that this is the final scenario in the campaign.
HAS_NO_TURN_LIMIT: Add a note to the objectives indicating that there is no turn limit.

[ top ]

From file: `optional_unit_advancements.cfg`

ENABLE_ADVANCEMENT UNIT ADVANCEMENT_TYPE EXTRA_WML: Place in a campaign or scenario definition to allow {UNIT} to advance to {ADVANCEMENT_TYPE}. {EXTRA_WML} is mostly for (set_experience=XX) in case the max XP required needs to be overridden.
DISABLE_ADVANCEMENT UNIT ADVANCEMENT_TYPE EXTRA_WML: Place in a campaign or scenario definition to disallow {UNIT} from advancing to {ADVANCEMENT_TYPE}. {EXTRA_WML} is mostly for (set_experience=XX) in case the max XP required needs to be overridden.
ENABLE_PARAGON: Place in a campaign or scenario definition to allow Dune Blademaster to advance to Dune Paragon.
DISABLE_GRAND_MARSHAL: Place in a campaign or scenario definition to disallow General from advancing to Grand Marshal.
ENABLE_ARMAGEDDON_DRAKE: Place in a campaign or scenario definition to allow Inferno Drake to advance to Armageddon Drake.
ENABLE_DWARVISH_ARCANISTER: Place in a campaign or scenario definition to allow Dwarvish Runemaster to advance to Dwarvish Arcanister.
ENABLE_DWARVISH_RUNESMITH: Place in a campaign or scenario definition to allow Dwarvish Fighter to advance to Dwarvish Runesmith.
ENABLE_WOLF_ADVANCEMENT: Place in a campaign or scenario definition to allow Wolf to advance to Great Wolf and Great Wolf to advance to Direwolf.
ENABLE_TROLL_SHAMAN: Place in a campaign or scenario definition to allow Troll Whelp to advance to Troll Shaman.
ENABLE_ANCIENT_LICH: Place in a campaign or scenario definition to allow Lich to advance to Ancient Lich.
ENABLE_DEATH_KNIGHT: Place in a campaign or scenario definition to allow Revenant to advance to Death Knight.
ENABLE_WOSE_SHAMAN: Place in a campaign or scenario definition to allow Wose to advance to Wose Shaman.
ENABLE_SAURIAN_SPEARTHROWER: Place in a campaign or scenario definition to allow Saurian Skirmisher to advance to Saurian Spearthrower.

[ top ]

From file: `scenario-utils.cfg`

Utility macros for scenario-objective control.

FOREVER

No documentation available for this macro.

INFINITY

No documentation available for this macro.

EVERYWHERE

No documentation available for this macro.

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}

CAMPAIGN_DIFFICULTY DEFINE IMAGE LABEL DESCRIPTION

Define a difficulty level for a campaign

DEFAULT_DIFFICULTY

Append to {CAMPAIGN_DIFFICULTY} to mark it as the default difficulty.

[ top ]

From file: `schedules.cfg`

This file defines all the standard time schedules.

TOD_COLOR_SHIFT RED GREEN BLUE: Append to any time definition to add a color shift.
DAWN: No documentation available for this macro.
MORNING: No documentation available for this macro.
MIDDAY: No documentation available for this macro.
AFTERNOON: No documentation available for this macro.
DUSK: No documentation available for this macro.
FIRST_WATCH: No documentation available for this macro.
MIDNIGHT: No documentation available for this macro.
SECOND_WATCH: No documentation available for this macro.
INDOORS: A time schedule that's always bright, for indoor settings.
UNDERGROUND: A time schedule that's always dark, for underground settings.
DEEP_UNDERGROUND: A time schedule that's extremely dark, for deep underground settings. The chaotic bonus is 30%.
DEFAULT_SCHEDULE: The default schedule, with dawn, morning, afternoon, dusk, and first and second watches.
SUMMER_SCHEDULE: A summer schedule, witha longer daylight segment.
WINTER_SCHEDULE: A winter schedule, with a longer nighttime segment.
DEFAULT_SCHEDULE_DAWN: Default schedule, starting at dawn.
DEFAULT_SCHEDULE_MORNING: Default schedule, but starting at morning.
DEFAULT_SCHEDULE_AFTERNOON: Default schedule, but starting at afternoon.
DEFAULT_SCHEDULE_DUSK: Default schedule, but starting at dusk.
DEFAULT_SCHEDULE_FIRST_WATCH: Default schedule, but starting at first watch.
DEFAULT_SCHEDULE_SECOND_WATCH: Default schedule, but starting at second watch.
MIDNIGHT_HOUR: No documentation available for this macro.
SECOND_WATCH_HOUR1: No documentation available for this macro.
SECOND_WATCH_HOUR2: No documentation available for this macro.
SECOND_WATCH_HOUR3: No documentation available for this macro.
SECOND_WATCH_HOUR4: No documentation available for this macro.
SECOND_WATCH_HOUR5: No documentation available for this macro.
SECOND_WATCH_HOUR6: No documentation available for this macro.
DAWN_HOUR: No documentation available for this macro.
MORNING_HOUR1: No documentation available for this macro.
MORNING_HOUR2: No documentation available for this macro.
MORNING_HOUR3: No documentation available for this macro.
MORNING_HOUR4: No documentation available for this macro.
MIDDAY_HOUR: No documentation available for this macro.
AFTERNOON_HOUR1: No documentation available for this macro.
AFTERNOON_HOUR2: No documentation available for this macro.
AFTERNOON_HOUR3: No documentation available for this macro.
AFTERNOON_HOUR4: No documentation available for this macro.
AFTERNOON_HOUR5: No documentation available for this macro.
AFTERNOON_HOUR6: No documentation available for this macro.
DUSK_HOUR: No documentation available for this macro.
FIRST_WATCH_HOUR1: No documentation available for this macro.
FIRST_WATCH_HOUR2: No documentation available for this macro.
FIRST_WATCH_HOUR3: No documentation available for this macro.
FIRST_WATCH_HOUR4: No documentation available for this macro.
DEFAULT_SCHEDULE_24H: A 24-hour schedule, where each turn represents 1 hour.
DAWN1: No documentation available for this macro.
DAWN2: No documentation available for this macro.
MORNING1: No documentation available for this macro.
MORNING2: No documentation available for this macro.
MIDDAY1: No documentation available for this macro.
MIDDAY2: No documentation available for this macro.
AFTERNOON1: No documentation available for this macro.
AFTERNOON2: No documentation available for this macro.
DUSK1: No documentation available for this macro.
DUSK2: No documentation available for this macro.
SHORTDARK: No documentation available for this macro.
LONGDARK1: No documentation available for this macro.
LONGDARK2: No documentation available for this macro.
LONGDARK3: No documentation available for this macro.
LONGDARK4: No documentation available for this macro.
TWO_SUNS_DEFAULT_SCHEDULE: The standard After the Fall schedule, with two uneven days.

[ top ]

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.

[ top ]

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_NO_EVENT

No documentation available for this macro.

DEFAULT_MUSIC_PLAYLIST

No documentation available for this macro.

FULL_MUSIC_PLAYLIST_NO_EVENT

No documentation available for this macro.

FULL_MUSIC_PLAYLIST

No documentation available for this macro.

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_LIST:HOLY

No documentation available for this macro.

SOUND_LIST:HOLY_MISS

No documentation available for this macro.

SOUND_LIST:MISS

No documentation available for this macro.

SOUND_LIST:THROW

No documentation available for this macro.

SOUND_LIST:SWORD_SWISH

No documentation available for this macro.

SOUND_LIST:BAT_HIT

No documentation available for this macro.

SOUND_LIST:DRAKE_HIT

No documentation available for this macro.

SOUND_LIST:DWARF_HIT

No documentation available for this macro.

SOUND_LIST:DWARF_DIE

No documentation available for this macro.

SOUND_LIST:ELF_HIT

No documentation available for this macro.

SOUND_LIST:ELF_FEMALE_HIT

No documentation available for this macro.

SOUND_LIST:GOBLIN_HIT

No documentation available for this macro.

SOUND_LIST:GOBLIN_DIE

No documentation available for this macro.

SOUND_LIST:GRYPHON_HIT

No documentation available for this macro.

SOUND_LIST:GRYPHON_DIE

No documentation available for this macro.

SOUND_LIST:HORSE_HIT

No documentation available for this macro.

SOUND_LIST:HUMAN_HIT

No documentation available for this macro.

SOUND_LIST:HUMAN_FEMALE_HIT

No documentation available for this macro.

SOUND_LIST:HUMAN_OLD_HIT

No documentation available for this macro.

SOUND_LIST:HUMAN_OLD_DIE

No documentation available for this macro.

SOUND_LIST:HUMAN_DIE

No documentation available for this macro.

SOUND_LIST:HUMAN_FEMALE_DIE

No documentation available for this macro.

SOUND_LIST:LICH_HIT

No documentation available for this macro.

SOUND_LIST:NAGA_HIT

No documentation available for this macro.

SOUND_LIST:OGRE_HIT

No documentation available for this macro.

SOUND_LIST:OGRE_DIE

No documentation available for this macro.

SOUND_LIST:ORC_HIT

No documentation available for this macro.

SOUND_LIST:ORC_DIE

No documentation available for this macro.

SOUND_LIST:ORC_SMALL_HIT

No documentation available for this macro.

SOUND_LIST:ORC_SMALL_DIE

No documentation available for this macro.

SOUND_LIST:SKELETON_HIT

No documentation available for this macro.

SOUND_LIST:SKELETON_BIG_HIT

No documentation available for this macro.

SOUND_LIST:SKELETON_DIE

No documentation available for this macro.

SOUND_LIST:TROLL_HIT

No documentation available for this macro.

SOUND_LIST:TROLL_DIE

No documentation available for this macro.

SOUND_LIST:WOLF_GROWL

No documentation available for this macro.

SOUND_LIST:WOLF_HIT

No documentation available for this macro.

SOUND_LIST:WOLF_DIE

No documentation available for this macro.

SOUND_LIST:ZOMBIE_WEAK_HIT

No documentation available for this macro.

SOUND_LIST:ZOMBIE_HIT

No documentation available for this macro.

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.

[ top ]

From file: `special-notes.cfg`

NOTE_REMOVE

Deprecated macro. Deprecation level: 4.

This does not work on notes added by abilities, weapon specials or damage types

SPECIAL_NOTES

Deprecated macro. Deprecation level: 4.

Use [special_note]note= tags and special_note= attributes instead.

SPECIAL_NOTES_SPIRIT

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_ARCANE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_HEALS

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_EXTRA_HEAL

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_CURES

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_UNPOISON

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_REGENERATES

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_STEADFAST

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_LEADERSHIP

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_SKIRMISHER

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_ILLUMINATES

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_TELEPORT

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_AMBUSH

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_NIGHTSTALK

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_CONCEALMENT

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_SUBMERGE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_FEEDING

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_BERSERK

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_BACKSTAB

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_PLAGUE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_SLOW

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_PETRIFY

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_STONE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_MARKSMAN

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_MAGICAL

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_SWARM

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_CHARGE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_DRAIN

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_FIRSTSTRIKE

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_POISON

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

SPECIAL_NOTES_DEFENSE_CAP

Deprecated macro. Deprecation level: 2. Scheduled for removal in 1.19.

This note is now added automatically.

[ top ]

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}

[ top ]

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}

[ top ]

From file: `traits.cfg`

Traits for the [modifications] clause of SingleWML descriptions

TRAIT_LOYAL Optional arguments: OVERLAY: Units with trait Loyal have no upkeep.
TRAIT_LOYAL_HERO: No documentation available for this macro.
TRAIT_LOYAL_HERO_NOSLOT: loyal hero unit where for some reason we don't want the loyal to appear in the traits list, i really think its be better if stayed consitent and decided for one way and removed either this or TRAIT_LOYAL_HERO
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.

[ top ]

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.

UNREACHABLE

No documentation available for this macro.

NOT_ON_RECALL_LIST

No documentation available for this macro.

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 Optional arguments: FEMALE_NAME

Creates a generic unit of TYPE belonging to SIDE at X,Y, which has a generated gender and traits (just like a recruited unit). FEMALE_NAME may also be specified, mainly for translation purposes.

Example:

 {NAMED_NOTRAIT_UNIT 1 (Dark Sorcerer) 20 22 (Guard) (_"Dark Sorcerer")
  FEMALE_NAME=_"female^Dark Sorceress"}

NAMED_NOTRAIT_UNIT SIDE TYPE X Y ID_STRING NAME_STRING Optional arguments: FEMALE_NAME

Creates a unit with no traits, random gender and specified name. FEMALE_NAME may also be specified, mainly for translation purposes.

Example:

 {NAMED_NOTRAIT_UNIT 1 (Mage) 20 22 (Mochi) (_"Mochi")
  FEMALE_NAME=_"female^Mochi"}

RECALL ID_STRING

No documentation available for this macro.

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.

PASSABLE_HEX

Meant to be used as a suffix to a unit-generating macro call. Makes sure the generated unit is in a passable hex

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}
 {CLEAR_VARIABLE 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}

WOUNDED_UNIT OTHER_FILTERS

Currently used in sprite animations, see also STANDARD_IDLE_FILTER in animation-utils.cfg

[ top ]

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

ON_DIFFICULTY EASY_VALUE NORMAL_VALUE HARD_VALUE

No documentation available for this macro.

ON_DIFFICULTY4 EASY_VALUE NORMAL_VALUE HARD_VALUE NIGHTMARE_VALUE

No documentation available for this macro.

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

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

The attack_depth aspect has no effect on the AI any more.

ATTACK_DEPTH4 EASY_VALUE NORMAL_VALUE HARD_VALUE NIGHTMARE_VALUE

Deprecated macro. Deprecation level: 3. Scheduled for removal in 1.17.

The attack_depth aspect has no effect on the AI any more.

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

Moves a unit from its current location by the given offset, 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.

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.

FULL_HEAL FILTER

Heals maching units to full hitpoints.

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]
 )}

WARNING : if an unit must disappear in mid-battle before attack end was fired, don't use [unstore_unit] but recreate unit or cth modifications persist. Or don't use this macro.

LOOT AMOUNT SIDE

Gives the player some gold, with a message.

CREDITS_SEPARATOR

Add a credits entry that serves as a separator between groups.

[ top ]

From file: `weapon_specials.cfg`

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

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_DEFLECT: Canned definition of the Deflect 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_ABSORB AMT: Canned definition of the Absorb 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.
WEAPON_SPECIAL_STUN: Canned definition of the Stun ability to be included in a [specials] clause.
WEAPON_SPECIAL_ARCANE: No documentation available for this macro.

[ top ]

WML Macros Reference

From file: abilities.cfg

From file: ai.cfg

From file: ai_candidate_actions.cfg

From file: ai_controller.cfg

From file: amla.cfg

From file: animation-utils.cfg

From file: animation-utils2.cfg

From file: carryover-utils.cfg

From file: conditional-utils.cfg

From file: debug-utils.cfg

From file: deprecated-utils.cfg

From file: event-utils.cfg

From file: image-utils.cfg

From file: interface-utils.cfg

From file: items.cfg

From file: movetypes.cfg

From file: multiplayer.cfg

From file: names.cfg

From file: objective-utils.cfg

From file: optional_unit_advancements.cfg

From file: scenario-utils.cfg

From file: schedules.cfg

From file: side-utils.cfg

From file: sound-utils.cfg

From file: special-notes.cfg

From file: teleport-utils.cfg

From file: terrain-utils.cfg

From file: traits.cfg

From file: unit-utils.cfg

From file: utils.cfg

From file: weapon_specials.cfg

From file: `abilities.cfg`

From file: `ai.cfg`

From file: `ai_candidate_actions.cfg`

From file: `ai_controller.cfg`

From file: `amla.cfg`

From file: `animation-utils.cfg`

From file: `animation-utils2.cfg`

From file: `carryover-utils.cfg`

From file: `conditional-utils.cfg`

From file: `debug-utils.cfg`

From file: `deprecated-utils.cfg`

From file: `event-utils.cfg`

From file: `image-utils.cfg`

From file: `interface-utils.cfg`

From file: `items.cfg`

From file: `movetypes.cfg`

From file: `multiplayer.cfg`

From file: `names.cfg`

From file: `objective-utils.cfg`

From file: `optional_unit_advancements.cfg`

From file: `scenario-utils.cfg`

From file: `schedules.cfg`

From file: `side-utils.cfg`

From file: `sound-utils.cfg`

From file: `special-notes.cfg`

From file: `teleport-utils.cfg`

From file: `terrain-utils.cfg`

From file: `traits.cfg`

From file: `unit-utils.cfg`

From file: `utils.cfg`

From file: `weapon_specials.cfg`