NewLand - Reference to Macros

 

When creating new scenarios for A New Land, it helps to know the macros. This page documents the macros in 0.9.0a and later versions of A New Land. Kernigh is amid the process of updating this page for 0.9.0b. Upon this page, a matching pair of tags, including their attributes and elements, is an element, for example a "store_unit" element. An invocation in curly braces, such as {AUTO_FARMINING "Peasant"}, is a macro substitution.

 

For general information about macros in WML, consult PreprocessorRef.

 

NewLand - Reference to Macros auto_peasant.cfg AUTO_FARMING AUTO_GOLD_MINING AUTO_IRON_MINING FARM_MOVE AUTO_MOVE_INIT blacksmith.cfg BLKSMTH_OPTION BLACKSMITH builders.cfg BUILDER_GRASSLAND_ACTIONS BUILDER_HILLS_ACTIONS BUILDER_MOUNTAINS_ACTIONS BUILDER_CASTLE_ACTIONS BUILDER_VILLAGE_ACTIONS CREATING_BUILDERS IF_BUILDER_ADVANCES leaders.cfg SHARE_GOLD SHARE_FARMING_KNOWLEDGE SHARE_GOLDMINING_KNOWLEDGE SHARE_IRONMINING_KNOWLEDGE LEADERS macros.cfg VERSION BEGIN_MSG_OPTION END_MSG_OPTION MSG_OPTION_SEPARATOR MSG_OPTION_END_LOOP MSG_OPTION_ALLOW_RECRUIT MSG_OPTION_DONE BEGIN END CONDITION STORE_SIDE_GOLD_TO_VAR ADD_GOLD_SIDE BEGIN_PROCESS_BUILD_ACTIONS BEGIN_PROCESS_BUILDER_BUILD_ACTIONS END_PROCESS_BUILD_ACTIONS BEGIN_BUILD_DIALOGUE END_BUILD_DIALOGUE ALLOW_RECRUIT CAPTURE_VILLAGE SET_TERRAIN SET_ITEM_IMAGE REMOVE_ITEM SCROLL_TO PLAY_SOUND DELAY REDRAW CONCATENATE mages.cfg RESEARCH misc.cfg SET_MAGE_TYPES COMPLETE_ACTION SET_NAMES HELP_SUBMENU A_NEW_LAND_HELP ENABLE_INITIAL_HELP INIT_SIDE_OLD INIT_SIDE ogres_infdrake.cfg peasants.cfg GRASSLAND_ACTIONS FOREST_ACTIONS HILLS_ACTIONS MOUNTAINS_ACTIONS WATER_ACTIONS FORD_ACTIONS RUBBLE_ACTIONS CAVE_ACTIONS CASTLE_ACTIONS VILLAGE_ACTIONS FARM_CASHCROP MINE_GOLD MINE_IRON sounds.cfg BUILD_SOUND_1 BUILD_SOUND_2 BUILD_SOUND_3 BEEP special.cfg TRAPPED_CREATURE thieves.cfg

 

auto_peasant.cfg

This file controls automatic farmining and mining. In A New Land, a peasant who idles upon a cash crop, a gold mine, or an iron mine will automatically harvest the crop or extract some gold or iron at the start of the next turn. A peasant who idles on plain grassland will automatically plant a cash crop at the start of the next turn. This allows players to have peasants work continuously, simply by parking them at the correct squares.

 

AUTO_FARMING

Arguments	#define AUTO_FARMING TYPES
Context	new event
Since	0.9.0a

 

 

Creates a "new turn" event that causes the units of TYPES to automatically plant crops on grassland or harvest crops from dirt. TYPES is typically "Peasant".

 

AUTO_GOLD_MINING

Arguments	#define AUTO_GOLD_MINING TYPES
Context	new event
Since	0.9.0a

 

 

Creates a "new turn" event that causes the units of TYPES to automatically extract gold from hill villages. TYPES is typically "Peasant".

 

AUTO_IRON_MINING

Arguments	#define AUTO_IRON_MINING TYPES
Context	new event
Since	0.9.0a

 

 

Creates a "new turn" event that causes the units of TYPES to automatically extract gold from mountain villages. TYPES is typically "Peasant".

 

FARM_MOVE

Arguments	#define FARM_MOVE TYPES
Context	new event
Since	0.9.0a
Removed	0.9.0b

 

This macro became AUTO_MOVE_INIT in 0.9.0b, perhaps because it applies to both farms and mines, and the name FARM_MOVE suggested otherwise. All of the calls to FARM_MOVE (in places like ANL_Maps) must be changed into calls into AUTO_MOVE_INIT.]

 

AUTO_MOVE_INIT

Arguments	#define AUTO_MOVE_INIT TYPES
Context	new event
Since	0.9.0b

 

Creates an event or events to handle units of TYPES (typically "Peasant") who move onto an existing farm or mine and have movement points remaining. The idea is to set the movement points to 0 and permit the harvest or mining at next turn.

 

The implementation in 0.9.0a did not work; it tried to permit the harvest or mining by setting "unit.resting" to no, but Wesnoth would set "unit.resting" to yes after firing the event, causing a lag of one turn. Kernigh (in patch k4) and governor (in official 0.9.0b) have different approaches to making this macro work.

 

blacksmith.cfg

This file contains the BLACKSMITH macro, that causes dungeon villages "D" to act as blacksmiths.

 

BLKSMTH_OPTION

Arguments	#define BLKSMTH_OPTION TEXT COST EFFECTS
Context	message option
Since	0.9.0a

 

 

Creates a message option, labeled TEXT, that requires COST iron nuggets to perform the EFFECTS. If the player cannot afford this option, then it beeps and returns the player to the menu. This macro only works from within the message menu of the BLACKSMITH macro, because it requires the BLACKSMITH macro to set up certain variables. However, in the future, if someone designs a custom blacksmith for a new scenario, then this macro may have an important role.

 

BLACKSMITH

Arguments	#define BLACKSMITH SIDES
Context	new event
Since	0.9.0a

 

 

Creates a "moveto" event that triggers for all units belonging to SIDES, except for $mage_types units, "Peasant" units, or units that the blacksmith has already once upgraded. If such a unit moves onto a dungeon village, then the blacksmith menu appears and the player may upgrade that unit.

 

In 0.9.0a, this macro uses IF_TERRAIN, not filter_location. Thus it fires when the unit does not land on a blacksmith and prevents the unit from undoing its move.

 

builders.cfg

Before patch k7, the builders.cfg file duplicated a lot of markup of peasants.cfg. The BUILDER_*_ACTIONS macros in this file are copies of the *_ACTIONS macros from peasants.cfg, but adjusted to provide the 2 gold discount that applies to builders when they build villages. This duplication of markup may caused builders.cfg to miss various bug fixes and improvements applied to peasants.cfg.

 

The builders.cfg macros differ from the peasants.cfg by not taking a SIDES parameter. Instead, they apply to all sides that have units that match ROLES and TYPES. In practice, ROLES must be "builder" and TYPES must be "Peasant".

 

Patch k7 removed the duplication of markup by emptying the BUILDER_*_ACTIONS macros. The macros still exist in patch k7, but they have no effect. Instead, patch k7 modified the BEGIN_PROCESS_BUILD_ACTIONS macro in macros.cfg so that the *_ACTIONS macros in peasants.cfg would also apply to builders. The macros in peasants.cfg check whether the unit is a builder and apply the appropriate discount, if any.

 

Patch k7 retains the CREATING_BUILDERS and IF_BUILDER_ADVANCES macros from 0.9.0a. These two macros reside in builders.cfg and have the same function as they did since 0.9.0a.

 

 

BUILDER_GRASSLAND_ACTIONS

Arguments	#define BUILDER_GRASSLAND_ACTIONS ROLES TYPES
Context	new event
Since	0.9.0a
Modified	patch k7: the macro exists but has no effect

 

BUILDER_HILLS_ACTIONS

Arguments	#define BUILDER_HILLS_ACTIONS ROLES TYPES
Context	new event
Since	0.9.0a
Modified	patch k7: the macro exists but has no effect

 

BUILDER_MOUNTAINS_ACTIONS

Arguments	#define BUILDER_MOUNTAINS_ACTIONS ROLES TYPES
Context	new event
Since	0.9.0a
Modified	patch k7: the macro exists but has no effect

 

BUILDER_CASTLE_ACTIONS

Arguments	#define BUILDER_CASTLE_ACTIONS ROLES TYPES
Context	new event
Since	0.9.0a
Modified	patch k7: the macro exists but has no effect

 

BUILDER_VILLAGE_ACTIONS

Arguments	#define BUILDER_VILLAGE_ACTIONS ROLES TYPES
Context	new event
Since	0.9.0a
Modified	patch k7: the macro exists but has no effect

 

CREATING_BUILDERS

Arguments	#define CREATING_BUILDERS TYPES
Context	new event
Since	0.9.0a

 

Creates an event that allows units of TYPES (typically "Peasant") to visit a blacksmith "D" and upgrade to role=builder status at the cost of 2 iron nuggets.

 

IF_BUILDER_ADVANCES

Arguments	#define IF_BUILDER_ADVANCES TYPES
Context	new event
Since	0.9.0a

 

Creates an event that causes of units of TYPES and of role=builder status to lose their "blue shield" overlay after they level. With {IF_BUILDER_ADVANCES "Peasant"}, a builder Peasant that becomes Spearman or Bowman retains the role=builder status but loses the overlay, which is well if the calls to BUILDER_*_ACTIONS only allowed Peasants, and not Spearmen or Bowmen, to build.

 

leaders.cfg

This file contains the LEADERS macro, that permits leaders to perform diplomacy at universities (elven villages "t" or "e"). It also contains several other macros that implement diplomatic actions for the LEADERS macro.

 

SHARE_GOLD

Arguments	#define SHARE_GOLD SIDE SIDE_TARGET AMOUNT
Context	action
Since	0.9.0a

 

 

Transfers AMOUNT gold from $side_number to SIDE_TARGET. This fails and beeps if $side_number equals SIDE_TARGET, or if the $side_number cannot afford the transfer.

 

In 0.9.0a, the macro does not use its SIDE argument. It instead uses the side_number variable.

 

SHARE_FARMING_KNOWLEDGE

Arguments	#define SHARE_FARMING_KNOWLEDGE SIDE SIDE_TARGET
Context	action
Since	0.9.0a

 

 

Adds 1 point to the progress of farming of SIDE_TARGET, but only if $side_number has more advances in farming than SIDE_TARGET. Otherwise, it beeps. If $side_number equals SIDE_TARGET, then this triggers a DEBUG_MSG.

 

In 0.9.0a, the macro does not use its SIDE argument. It instead uses the side_number variable. This macro expects that you copy $player[$side_number].farming.target to $temp_farming_target before entering this macro.

 

SHARE_GOLDMINING_KNOWLEDGE

Arguments	#define SHARE_GOLDMINING_KNOWLEDGE SIDE SIDE_TARGET
Context	action
Since	0.9.0a

 

 

Acts like SHARE_FARMING_KNOWLEDGE, but with knowledge of gold mining.

 

In 0.9.0a, the macro does not use its SIDE argument. It instead uses the side_number variable. This macro expects that you copy $player[$side_number].gold_mining.target to $temp_gold_mining_target before entering this macro.

 

Beware of an inconsistency of underscores: the macro name contains GOLDMINING not GOLD_MINING. The reason may be that gold-mining is an adjective in the name of the macro.

 

SHARE_IRONMINING_KNOWLEDGE

Arguments	#define SHARE_GOLDMINING_KNOWLEDGE SIDE SIDE_TARGET
Context	action
Since	0.9.0a

 

 

Acts like SHARE_FARMING_KNOWLEDGE, but with knowledge of iron mining.

 

In 0.9.0a, the macro does not use its SIDE argument. It instead uses the side_number variable. This macro expects that you copy $player[$side_number].iron_mining.target to $temp_iron_mining_target before entering this macro.

 

Beware of an inconsistency of underscores: the macro name contains IRONMINING not IRON_MINING. The reason may be that gold-mining is an adjective in the name of the macro.

 

LEADERS

Arguments	#define LEADERS SIDES
Context	new event
Since	0.9.0a

 

 

Creates an event that permits the leaders of SIDES to perform diplomatic actions when they land at a university.

 

Importantly, the SIDES argument only effects which leaders gain access to diplomacy. The diplomatic menu will always permit these players to share with players 1,2,3,4, even if there are less than four players or if those players are not on the same team. In the future, it may be best to have an alternative to the LEADERS macro that does not provide sharing; said alternative macro would appear in free-for-all scenarios or in scenarios that lack the usual four players.

 

macros.cfg

This file contains "general dev macros". There are many useful shortcuts of scripting in here. Some of these macros were in governor.cfg before 0.9.0a.

 

VERSION

Arguments	#define VERSION
Context	attributes of [objectives]
Since	0.9.0a

 

 

Provides the side= and summary= attributes for the "objectives" element, such that the objectives contain the version number of A New Land. This macro is the place to update the version number for new versions or variants.

 

BEGIN_MSG_OPTION

Arguments	#define BEGIN_MSG_OPTION MSG
Context	message option, opening an "option" tag
Since	0.9.0a

 

Create a menu option with the MSG label. This macro belongs in a message tag. The actual attribute is "message= _ {MSG}", thus this macro will mark the message for translation.

 

This shortcut may not seem useful, but A New Land employs message menus many times, and instances of BEGIN_MSG_OPTION and END_MSG_OPTION appear again and again in the macros.

 

END_MSG_OPTION

Arguments	#define END_MSG_OPTION
Context	message option, closing an"option" tag
Since	0.9.0a

 

Ends a menu option created with BEGIN_MSG_OPTION. Actually, this macro only contains a closing "[/option]" tag, but we use it to balance instances of BEGIN_MSG_OPTION.

 

MSG_OPTION_SEPARATOR

Arguments	#define MSG_OPTION_SEPARATOR
Context	message option
Since	0.9.0a

 

Creates an empty message option with a null command, to act as a separator in a menu. The selection of this option does dismiss the menu, thus one should only use MSG_OPTION_SEPARATOR from within a looping menu system.

 

MSG_OPTION_END_LOOP

Arguments	#define MSG_OPTION_END_LOOP MSG_TEXT TOGGLE_VAR TOGGLE_VAL
Context	message option
Since	0.9.0a

 

Creates a message option labeled MSG_TEXT that sets TOGGLE_VAR to TOGGLE_VAL. The typical use for this is to break the condition that keeps the player within a looping menu system, so as to exit the system. This macro implements many of the "Back" or "Do Nothing" options in various menus.

 

MSG_OPTION_ALLOW_RECRUIT

Arguments	#define MSG_OPTION_ALLOW_RECRUIT SIDE TYPE
Context	message option
Since	0.9.0a

 

Creates a message option labeled TYPE that allows SIDE to recruit units of TYPE. In A New Land, there are few macros which present a menu of MSG_OPTION_ALLOW_RECRUIT message options, after the player studies the Art of War or negotiates with the dwarves or elves.

 

MSG_OPTION_DONE

Arguments	#define MSG_OPTION_DONE VAR MSG
Context	message option
Since	0.9.0a

 

This older macro remains in the source, but effectively performs the same task as {MSG_OPTION_END_LOOP {MSG} {VAR} 1}.

 

BEGIN

Arguments	#define BEGIN TAG
Context	opening tag
Since	0.9.0a

 

 

See description for END.

 

END

Arguments	#define END TAG
Context	closing tag
Since	0.9.0a

 

 

The BEGIN and END macros provide opening and closing tags. To Kernigh, who uses a text editor that provides syntax coloring for WML tags but not for WML macro substitutions, there seems no reason to use these macros. However, in 0.9.0b, governor added a comment that explains, BEGIN and END are not useless, since this was originally not my project, I added them to make sure I could easily identify the WML that I had added.

 

CONDITION

Arguments	#define CONDITION VAR TEST VALUE
Context	condition
Since	0.9.0a

 

 

Provides a condition for use inside an "if" or "while" element. It is much easier to write a one line CONDITION then to write a "condition" element of four lines, including the name={VAR} and {TEST}={VALUE} attributes.

 

This is the sort of macro that utils.cfg should have. Know that utils.cfg of Wesnoth 1.2.4 provides useful macros like VARIABLE, VARIABLE_OP, IF_TERRAIN but not CONDITION. Do not use CONDITION in other add-ons unless you first define it.

 

STORE_SIDE_GOLD_TO_VAR

Arguments	#define STORE_SIDE_GOLD_TO_VAR SIDE VAR
Context	action
Since	0.9.0a

 

Stores the gold of SIDE into VAR.

 

In 0.9.0a, this macro uses the "store_gold" element, but a look into wesnoth-1.2.4/src/game_events.cpp reveals that "store_gold" elements are deprecated. In 0.8.5r02 patch k4, a similar STORE_GOLD macro employed the "store_side" element.

 

ADD_GOLD_SIDE

Arguments	#define ADD_GOLD_SIDE SIDE AMOUNT
Context	action
Since	0.9.0a

 

Adds AMOUNT gold to SIDE. To make SIDE pay for shopping, let AMOUNT be negative.

 

Though this macro is a simple wrapper around a "gold" element, it is one of the most significant macros in A New Land. Its absence from 0.8.5r02 prevented farms and gold mines from actually giving gold to the player, and rose the strategy of building villages, not farms. It also spawned four patches of 0.8.5r02 from Kernigh, the first of which provided ADD_GOLD_SIDE in auto_peasant.cfg to satisfy the two substitutions of that macro. In patch k4, the macro became ADD_SIDE_GOLD in governor.cfg, but in 0.9.0a, it is ADD_GOLD_SIDE in macros.cfg.

 

This macro is misnamed, because though we call it "ADD_GOLD_SIDE", the side comes before the gold with the order of arguments!

 

BEGIN_PROCESS_BUILD_ACTIONS

Arguments	#define BEGIN_PROCESS_BUILD_ACTIONS TERRAIN_TYPES FILTER_1 FILTER_2
Context	new event, opening an "event" tag and an "if" tag
Since	0.9.0a
Modified	patch k5: TERRAIN_TYPES now expects commas between terrain letters
Modified	0.9.0b: TERRAIN_TYPES now expects commas between terrain letters
Modified	patch k7: this macro also applies to role=builder units

 

 

Create a moveto event that fires for a unit that satisfies FILTER_1 and FILTER_2. Before patch k7, this macro creates an event that only fires for non-builder units, and one must use BEGIN_PROCESS_BUILDER_BUILD_ACTIONS to create a separate event that fires for builders.

 

If the unit has at least one movement point remaining and the unit lands on TERRAIN_TYPES, then fire the "then" element that you place after the substitution of this macro. After closing the "then" tag, you must substitute END_PROCESS_BUILD_ACTIONS. This macro is difficult to call correctly, but the calls are normally from builder.cfg or peasants.cfg.

 

This macro should store the unit in the "unit" variable, then store the gold of the unit's side in the "gold" variable. However, versions 0.8.5r02 and 0.9.0a it performs these two operations in the wrong order, thus potentially setting "gold" to the gold of the wrong side. A bug fix in patch k5 corrects this.

 

This macro places both FILTER_1 and FILTER_2 inside of the same "filter" element, so these arguments should contain "filter" attributes or "not" elements. The same "filter" element also requires that the role of the unit is not builder. Typically, FILTER_1 is a type= attribute and FILTER_2 is a side= attribute.

 

Versions 0.8.5r02 and 0.9.0a pass TERRAIN_TYPES to a "store_locations" tag, so it may be a string of terrain letters such as "fTF". This is incompatible with patch k5, which passed TERRAIN_TYPES to a "filter_location" tag; that tag (in 1.2.4) imposes the requirement for comma-separated values such as "f,T,F".

 

It is important to not provide any "else" element after the "then" element, because the condition that fires "else" is undefined; the BEGIN_PROCESS_BUILD_ACTIONS macro may have opened more than one "if" tag, and the "else" attaches only to the innermost "if" tag. (In patch k7, the "else" element fires when the unit has zero movement points, and there is one such "else" element in GRASSLAND_ACTIONS.)

 

BEGIN_PROCESS_BUILDER_BUILD_ACTIONS

Arguments	#define BEGIN_PROCESS_BUILDER_BUILD_ACTIONS TERRAIN_TYPES FILTER_1 FILTER_2
Context	new event, opening an "event" tag and an "if" tag
Since	0.9.0a

 

Creates a new moveto event, like BEGIN_PROCESS_BUILD_ACTIONS, but for builder units. The only difference is that BEGIN_PROCESS_BUILD_ACTIONS is for non-builder units, while BEGIN_PROCESS_BUILDER_BUILD_ACTIONS is for builder units. This allows the developer to implement completely different actions for peasants whom a blacksmith has upgraded.

 

In 0.9.0a, this has the same bug that BEGIN_PROCESS_BUILD_ACTIONS has.

 

Patch k7 retains this macro but does not use it.

 

END_PROCESS_BUILD_ACTIONS

Arguments	#define END_PROCESS_BUILD_ACTIONS
Context	new event, closing an "if" tag and an "event" tag
Since	0.9.0a

 

Closes the tags opened by either BEGIN_PROCESS_BUILD_ACTIONS or BEGIN_PROCESS_BUILDER_BUILD_ACTIONS. This macro is the only correct way to close the tags, because there may be multiple "if" tags to close. This macro also completes the actions of the event by unstoring "unit", thus applying any modifications, and by clearing the "gold" variable.

 

BEGIN_BUILD_DIALOGUE

Arguments	#define BEGIN_BUILD_DIALOGUE UNIT_VAR MSG LOOP_VAR LOOP_VAR_INIT_VALUE
Context	action, opening "while" and "do" and "message" tags
Since	0.9.0a

 

Commences a message menu that uses the looping message system. LOOP_VAR becomes LOOP_VAR_INIT_VALUE; the loop repeatedly displays the message until something sets LOOP_VAR to another value (probably with MSG_OPTION_END_LOOP or MSG_OPTION_DONE). After substituting this macro, you sould provide some message options, before substituting END_BUILD_DIALOGUE.

 

Version 0.9.0a (but not 0.9.0b) had the peculiar requirement that LOOP_VAR must be "finished_options". No other variable would work, because the condition in this macro checks "finished_options" instead of "{LOOP_VAR}". However, 0.9.0b correctly checks "{LOOP_VAR}" and does not have this problem.

 

Note of technique: The origin of the looping-menu technique may be in a scenario called Platypus' Colosseum. This technique became popular in Defense of the Wose, Defense of the Goblin and in SurvivalXtreme. The basic idea is that the message menu displays itself again and again until the player chooses an option to leave. This allows a player to buy multiple things from a shop. In A New Land, it is normally possible to perform only one action. However, the looping system remains necessary because the player may choose an invalid option from the menu, for example when the player lacks sufficient gold. There is no way in WML to conditionally remove options from a message menu, but it remains possible to test conditions inside of a menu command.

 

END_BUILD_DIALOGUE

Arguments	#define END_BUILD_DIALOGUE LOOP_VAR
Context	action, closing "message" and "do" and "while" tags
Since	0.9.0a

 

Closes the tags opened by BEGIN_BUILD_DIALOGUE.

 

ALLOW_RECRUIT

Arguments	#define ALLOW_RECRUIT SIDE TYPE
Context	action
Since	0.9.0a

 

Allows SIDE to recruit TYPE. This macro wraps the "allow_recruit" element.

 

CAPTURE_VILLAGE

Arguments	#define CAPTURE_VILLAGE
Context	action
Since	0.9.0a

 

 

Flags the village at $x1, $y1 for $side_number. This macro wraps the "capture_village" element and uses the three variables from a moveto event. The typical use is for a moveto event to construct a new village, then flag it for the side that built it.

 

SET_TERRAIN

Arguments	#define SET_TERRAIN X Y TERRAIN
Context	action
Since	0.9.0a

 

 

Change the terrain at X, Y into terrain letter TERRAIN. This wraps the "terrain" element, but we must have this macro, because of its very frequent appearance in the other macros. The main idea behind Bob_the_mighty's original concept is that different terrains have different special functions. This is the macro that allows us to construct and destroy.

 

SET_ITEM_IMAGE

Arguments	#define SET_ITEM_IMAGE X Y IMAGE
Context	action
Since	0.9.0a

 

 

Place IMAGE at X, Y. This wraps the "item" element, which draws an item or other suitable image on the map. When a unit moves to X, Y, nothing happens unless we also have a moveto event (such as the peasant's ability to harvest crops or clear rubble).

 

A New Land uses SET_ITEM_IMAGE as a cosmetic. The actual determination of the function of a hex is the terrain letter. Thus peasants may harvest dirt without a flower, may clear desert roads without rubble, for example.

 

We are limited to the images bundled with Wesnoth, most of which are in $PREFIX/share/wesnoth/images/ on a Unix system (where $PREFIX may be "/usr/local" or "/usr" for example).

 

REMOVE_ITEM

Arguments	#define REMOVE_ITEM X Y
Context	action
Since	0.9.0a

 

Remove image from X, Y, thus cancelling the effect of SET_ITEM_IMAGE. This wraps the "removeitem" element. It is useful when the peasant finally harvested that crop or cleared that rubble, and we now need to remove the image of the flower or rubble.

 

SCROLL_TO

Arguments	#define SCROLL_TO X Y
Context	action
Since	0.9.0a

 

 

Scroll to position X, Y. This is a simple wrapper around the "scroll_to" element. This macro encounters a lot of use during a new turn, as the game scrolls to show peasants automatically work.

 

PLAY_SOUND

Arguments	#define PLAY_SOUND SOUND_FILE
Context	action
Since	0.9.0a

 

 

Play SOUND_FILE. This simply wraps the "sound" element and name= attribute. All players may hear the sound, so you may want to listen to your opponents build things, in addition to peeking under the fog for their terrain changes.

 

We are limited to the sounds bundled with Wesnoth, most of which are in $PREFIX/share/wesnoth/sounds/ on a Unix system (where $PREFIX may be "/usr/local" or "/usr" for example).

 

DELAY

Arguments	#define DELAY TIME
Context	action
Since	0.9.0a

 

 

Wait for TIME milliseconds. This simply wraps the "delay" element and time= attribute. A New Land uses this to creatively combine short sound effects into new sound effects.

 

REDRAW

Arguments	#define REDRAW
Context	action
Since	0.9.0b

 

 

Redraw; this wraps the "redraw" element.

 

CONCATENATE

Arguments	#define VAR STRING1 STRING2
Context	action
Since	0.9.0b

 

Stores "{STRING1}|{STRING2}" into {VAR}. Typically, STRING1 is a substitution like "$some_variable" so that the | between {STRING1} and {STRING2} only marks the end of the substitution and the | is not part of the concatenated string.

 

(Does WML already have a concatenation operator?)

 

mages.cfg

RESEARCH

Arguments	#define RESEARCH SIDES
Context	new event
Since	0.9.0a

 

 

Creates a moveto event to permit the mages belonging to SIDES to study at universities. You musts also call SET_MAGE_TYPES in a prestart event to determine which units qualify as mages; otherwise all types of units of SIDES will be able to study.

 

misc.cfg

This file contains miscellaneous macros that did not gain a spot in macros.cfg; most of the macros here are more specific to A New Land, while the macros in macros.cfg are more portable to other add-ons.

 

SET_MAGE_TYPES

Arguments	#define SET_MAGE_TYPES TYPES SIDES
Context	action
Since	0.9.0a

 

 

Declares that TYPES are mages, and allows SIDES to recruit units of TYPES. (Bug: however, if SIDES is a list of multiple sides, then only the first side is used. So {SET_MAGE_TYPES "Mage" "1,2,3,4"} really acts as {SET_MAGE_TYPES "Mage" "1"}.) This macro, in conjunction with the RESEARCH macro, permites TYPES to study at universities. The study progress per turn is equal to the level of the unit, so a level 1 "Mage" would study 1 point per turn, while a level 2 "Red Mage" would study 2 points per tur.

 

This macro sets the "mage_types" variable to {TYPES}; only those units may research. With the typical {SET_MAGE_TYPES "Mage" "1,2,3,4"}, the Red Mage and White Mage are not mages who may research. Thus, if a Mage enters combat and levels up, then the resulting Red Mage or White Mage may not study at university, even though that unit would have been able to study twice as fast. The {SET_MAGE_TYPES "Mage,Red Mage" "1,2,3,4"} also allows Red Mages to research, but because of the bug, it only allows player 1 to recruit Red Mages.

 

Note that "Mage" is also on the list of recruits in the A New Land era. Thus, players in the A New Land era may already recruit level 1 Mages even if this macro fails to permit recruitment. If "Mage" is not in the list of TYPES for SET_MAGE_TYPES, then these level 1 Mages are normal mages. To remove "Mage" from the list of recruits, use the "disallow_recruit" tag.

 

In 0.9.0a, the SET_MAGE_TYPES also sets the "number_of_units" variable to 0, even though this variable has not any further use, purpose or function in A New Land.

 

COMPLETE_ACTION

Arguments	#define COMPLETE_ACTION GOLD
Context	action
Since	0.9.0a

 

Sets finished_options to 1, sets unit.moves to 0, and adds GOLD to $unit.side. GOLD may be a positive number (for example, the profit from chopping lumber) but is often negative (for example, the cost of building a village). This is a macro because it occurs so frequently in builders.cfg and peasants.cfg.

 

During the typical case, finished_options controls a menu loop created with the macro BEGIN_BUILD_DIALOGUE of macros.cfg; and the building unit was stored to variable "unit". Thus, the purpose of this macro is to break the loop, to adjust the gold, and to exhaust the movement points of the unit.

 

This macro, given negative GOLD, is able to lower a player's gold below zero, thus there should be some check for affordability before calling COMPLETE_ACTION.

 

SET_NAMES

Arguments	#define SET_NAMES
Context	action
Since	0.9.0a

 

Sets the variables name1, name2, name3, name4 to the names of the players 1 through 4. Each scenario contains an event that invokes SET_NAMES at the start of every turn. We use SET_NAMES so that we need not use "store_unit" to store the leaders every time we want to use the name of a leader in a diplomatic message. The only disadvantage is that after a player changes names, we must wait for the start of the next turn to again use correct names.

 

HELP_SUBMENU

Arguments	#define HELP_SUBMENU
Context	message option
Since	patch k5

 

Adds a "Finished" message option to a help message, effectively transforming it into a message menu, which prevents the help from appearing on the screens of other players. There a few calls to HELP_SUBMENU from A_NEW_LAND_HELP.

 

This feature was not in 0.8.5r02 but not 0.9.0a. Kernigh ported it to patch k5.

 

A_NEW_LAND_HELP

Arguments	#define A_NEW_LAND_HELP
Context	action
Since	0.9.0a

 

Displays the help. The scenarios typically invoke this macro from within an moveto event that fires at the start of the game upon the leader's first move. There is also a substitution of this macro within the LEADERS macro of leaders.cfg, enabling leaders to visit a university to access to the help.

 

In 0.9.0a, the scenarios will only permit player 1 to see the help at the start of the game. This is a regression from the scenarios of 0.8.5r02, that permitted all 4 human players to access the help.

 

ENABLE_INITIAL_HELP

Arguments	#define ENABLE_INITIAL_HELP SIDE
Context	new event
Since	patch k5

 

 

Creates a one-time event that displays the help (see A_NEW_LAND_HELP above) after the leader of SIDE moves for the first time. Because this is a moveto event, it prevents the player SIDE from undoing the first move of the leader.

 

Kernigh created this macro for patch k3, retained it in patch k4. This macro is not part of 0.9.0a, but Kernigh ported this macro to patch k5. The scenarios of Nyogtha's "ANL_Maps" call this macro. This macro in patch k3 used an "allow_undo" element to permit the leader to undo its first move, but that feature caused multiplayer games to become out of sync.

 

INIT_SIDE_OLD

Arguments	#define INIT_SIDE_OLD SIDE
Context	action
Since	0.9.0a
Deprecated	0.9.0a

 

Sets initial values to variables for the player SIDE, using the old names from 0.8.5r02. A comment reads, "there is a major error here!!!!", though it does not state what is the error. However, the names are confusing. (What is the difference between gold_mining1, gold_mining_target1, and mining1.gold?) This macro is now useless, because the other parts of A New Land 0.9.0a use the new variable names.

 

INIT_SIDE

Arguments	#define INIT_SIDE SIDE
Context	action
Since	0.9.0a

 

 

Sets initial values to variables for the player SIDE. Each player begins with 0 iron nuggets and with 0 progress toward any kind of research or diplomatic negotiation. This macro also sets up the initial targets for completion of study, and it establishes that the player may initially harvest farms for 3 gold each, and extract 4 gold or 1 iron nugget from a mine each turn.

 

To customize the initial values for a new scenario, you could call INIT_SIDE_FIRST, then manually adjust some of the variables to your prefer value.

 

ogres_infdrake.cfg

In 0.9.0a, the ogres_infdrake.cfg file does not actually contain any macros, but it contains "event" elements related to ogres and inferno drakes. Perhaps in a future version, this functionality will become a macro.

 

There are two important changes in 0.9.0a:

• Inferno drakes are the demons that appear at the end of A New Land: End Of Days. In 0.8.5r02, the inferno drakes would change to lava, any hex that they land on. However, in 0.9.0a, the inferno drakes do not create lava, but instead cause the same destruction as ogres.
• Ogres no longer have the option of capturing villages, staying in villages, or staying in castles. Now they always destroy them.

 

peasants.cfg

The peasants.cfg file enables those menus that appear after you move each peasant. Here, we find the markup that dictates the possible terrain changes and the cost of each change. Each macro enables peasants to take action upon one type of terrain.

 

If you are reading the code, note that the macros in peasants.cfg make frequent use of the BEGIN_PROCESS_BUILD_ACTIONS and BEGIN_BUILD_DIALOGUE and macros from misc.cfg. BEGIN_PROCESS_BUILD_ACTIONS opens a new event and an "if" tag, while BEGIN_BUILD_DIALOGUE opens a loop and a "message" tag. To break the loop, the markup must set "finished_options" variable to 1 (or to any value other than 0).

 

Because these macros use BEGIN_PROCESS_BUILD_ACTIONS, they impose the two requirements that:

1. The peasant must have at least one movement point remaining to perform an action. If a peasant uses all movement points to move, then the event will fire, and the player will be unable to undo the move, but no message menu will appear. Many actions use the COMPLETE_ACTION macro to set the remaining movement points to zero.
2. The peasant must not have the role of "builder". To enable players to use their builders after they upgrade peasant to builder at a blacksmith, you want the macros in builders.cfg.

 

Many of the macros here take a SIDES parameter. The macro creates an event only for peasants belonging to SIDES. We should have SIDES exclude any sides controlled by AI that does not know what to select from these menus.

 

GRASSLAND_ACTIONS

Arguments	#define GRASSLAND_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

 

Creates a moveto event that permits non-builder peasants of SIDES to perform the following actions upon grassland "g":

• "Plant a Cash Crop", 0 gold, creates dirt "r" with flower
• "Pave the ground", 0 gold, creates paved road "R"
• "Flood the field", 0 gold, creates shallow water "c"
• "Plant Sapling", -1 gold, creates forest "f"
• "Build Castle", -6 gold, creates human castle "C"
• "Build Village", -15 gold, creates human village "v"

 

FOREST_ACTIONS

Arguments	#define FOREST_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to perform the following actions upon forest "f", snow forest "F", or tropical forest "T" (but not great tree "?"):

• "Chop down forest", +1 gold, creates grassland "g"

 

HILLS_ACTIONS

Arguments	#define HILLS_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to perform the following actions upon hills "h" or snow hills "H" (but not dunes "J"):

• "Build Gold Mine", -25 gold, creates human hill village "a"

 

MOUNTAINS_ACTIONS

Arguments	#define MOUNTAINS_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to perform the following actions upon mountains "m" or desert mountains "M":

• "Build Iron Mine", -25 gold, creates human mountain village "b"

 

WATER_ACTIONS

Arguments	#define WATER_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to perform the following actions upon shallow water "c":

• "Make a Ford", -3 gold, creates river ford "k"
• "Convert to Grassland", -5 gold, creates grassland "g"

 

FORD_ACTIONS

Arguments	#define FORD_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to perform the following actions upon river ford "k":

• "Destroy the Ford", 0 gold, creates shallow water "c"
• "Convert to Grassland", -1 gold, creates grassland "g"

 

The name of this macro is FORD_ACTIONS, not FORDS_ACTIONS.

 

RUBBLE_ACTIONS

Arguments	#define RUBBLE_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to performm the following actions upon desert road "E":

• "Clear Rubble", -2 gold, creates grassland "g"

 

In A New Land, desert road "E" acts as rubble, and the scenario draws rubble wherever it creates desert road. It results when someone destroys a castle or a village (but not a hill village or mountain village), and requires some cleanup from a peasant before it can become grassland that permits new construction.

 

CAVE_ACTIONS

Arguments	#define CAVE_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to performm the following actions upon cave "u", rockbound cave "[", or mushroom grove "]" (but not lit cave "'"):

• "Convert to Grassland", -3 gold, creates grassland "g"

 

CASTLE_ACTIONS

Arguments	#define CASTLE_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to performm the following actions upon human castle "C", castle ruin "N", dwarven castle "o", sunken ruin "Q", or swamp ruin "q" (but not encampment "n"):

• "Knock down Castle", 0 gold, creates grassland "g"
• "Build a Keep", 0 gold, creates keep "K"

 

VILLAGE_ACTIONS

Arguments	#define VILLAGE_ACTIONS SIDES
Context	new event
Since	0.9.0a

 

Creates a moveto event that permits non-builder peasants of SIDES to performm the following actions upon human village "v", or snow village "V" (but not any other type of village):

• "Burn down the village", 0 gold, creates desert road "E" with rubble
• "Establish University", -7 gold, creates elven town "t"
• "Build Blacksith", -12 gold, creates dungeon village "D"

 

FARM_CASHCROP

Arguments	#define FARM_CASHCROP SIDES
Context	new event
Since	0.9.0a
Deprecated	0.9.0a

 

MINE_GOLD

Arguments	#define MINE_GOLD SIDES
Context	new event
Since	0.9.0a
Deprecated	0.9.0a

 

MINE_IRON

Arguments	#define MINE_IRON SIDES
Context	new event
Since	0.9.0a
Deprecated	0.9.0a

 

These macros do not work because they do not use the new variable names (INIT_SIDE versus INIT_SIDE_OLD). The macros FARM_CASHCROP, MINE_GOLD, MINE_IRON implemented the old behavior, before the creation of auto_peasant.cfg, that required players to move their peasants off an on farms and mines every turn.

 

sounds.cfg

BUILD_SOUND_1

Arguments	#define BUILD_SOUND_1
Context	action
Since	0.9.0a

 

Plays the sound of a peasant building a village.

 

 

BUILD_SOUND_2

Arguments	#define BUILD_SOUND_2
Context	action
Since	0.9.0a

 

 

Plays the sound of a peasant building a castle.

 

BUILD_SOUND_3

Arguments	#define BUILD_SOUND_3
Context	action
Since	0.9.0a

 

Plays a sound. Strangely, no scenario in A New Land ever uses this macro or this sound for any purpose.

 

BEEP

Arguments	#define BEEP
Context	action
Since	0.9.0a

 

Plays the turn bell "bell.wav". This beep notifies everyone that a player chose an invalid option from a menu.

 

special.cfg

This file contains the TRAPPED_CREATURE macro. It might be a good place to add unusual but scenario-independent macros.

 

TRAPPED_CREATURE

Arguments	#define TRAPPED_CREATURE X Y TYPE SIDE PLAYERS
Context	action
Since	0.9.0a

 

Creates a unit of TYPE at X, Y, stuck underneath a spider web; the creature belongs to SIDE. Also creates a moveto event for units from PLAYERS, such that if one of said units moves adjacent to the to the trapped creature, then the creature becomes "free" and joins the side of the rescuing unit. To make this work, the scenario needs to have a leaderless SIDE under control of the AI and allied with the PLAYERS.

 

The creature under the web is not stoned, but is actually and fully able to move around and participate in combat. However, it has ai_special=guardian, thus it will never move. However, enemies of SIDE may attack the trapped creature.

 

In A New Land: The Last Stand, the map designer has dropped the trap creatures in isolated caves. Appropriately, there is a nearby enemy spider (wounded, so a peasant may try to kill it), but no other enemy units come that way. However, there have been rare games where a player sent a peasant to attack the spider, and the spider takes an injury when attacking the peasant. Then the spider may choose to poison the trapped creature in a suicide attack. Though the trapped creature receives the experience from killing the spider, this is annoying because a rescuing player must heal the creature.

 

thieves.cfg

In 0.9.0a, the thieves.cfg file does not actually contain any macros, but it contains "event" elements related to thieves. Perhaps in a future version, this functionality will become a macro.

---

You may edit this wiki page. The text is in the PublicDomain. The Wesnoth Markup Language code is under the GNU GeneralPublicLicense.