Difference between revisions of "InternalActionsWML"
From The Battle for Wesnoth Wiki
m (formatting) |
|||
| Line 3: | Line 3: | ||
Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable. | Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable. | ||
| − | The internal actions [if], [while], and [event] describe when/whether sets of actions should be executed. | + | The internal actions '''[if]''', '''[while]''', and '''[event]''' describe when/whether sets of actions should be executed. |
== [if] == | == [if] == | ||
| − | + | Executes different sets of actions based on whether the conditions described in the condition tags are true or not. | |
Condition tags: | Condition tags: | ||
* '''[have_unit]''' a unit passing this filter with >0 HP exists | * '''[have_unit]''' a unit passing this filter with >0 HP exists | ||
** standard unit filter | ** standard unit filter | ||
| − | * '''[or]''' | + | |
| − | one must evaluate to true in order for the [if] to evaluate true | + | * '''[or]''' If an [or] is present, one must evaluate to true in order for the [if] to evaluate true |
** condition tags as in [if] - if these evaluate to true, [or] evaluates to true. | ** condition tags as in [if] - if these evaluate to true, [or] evaluates to true. | ||
| + | |||
* '''[variable]''' tests something about the value of a WML variable (see [[VariablesWML]]) | * '''[variable]''' tests something about the value of a WML variable (see [[VariablesWML]]) | ||
| − | ** ''name'' the name of the variable to test the value of | + | ** ''name'' the name of the variable to test the value of<br>Only one of these keys should be used: |
| − | + | ** ''equals'' $name is equal (string wise) to ''equals'' | |
| − | Only one of these keys should be used: | + | ** ''not_equals'' $name is not equal to ''not_equals'' |
| − | ** ''equals'' $ | + | ** ''greater_than'' $name is numerically greater than ''greater_than'' |
| − | ** ''not_equals'' $ | + | ** ''less_than'' $name is less than ''less_than'' |
| − | ** ''greater_than'' $ | + | ** ''greater_than_equal_to'' $name is not less than ''greater_than_equal_to'' |
| − | ** ''less_than'' $ | + | ** ''less_than_equal_to'' $name is not greater than ''less_than_equal_to'' |
| − | ** ''greater_than_equal_to'' $ | + | ** ''numerical_not_equals'' $name is greater than or less than ''numerical_not_equals'' |
| − | ** ''less_than_equal_to'' $ | + | ** ''numerical_equals'' $name is not greater than or less than ''numerical_equals'' |
| − | ** ''numerical_not_equals'' $ | ||
| − | ** ''numerical_equals'' $ | ||
After condition tags: | After condition tags: | ||
| − | * '''[then]''' contains a set of action tags which should be executed if all conditions are true, or all conditions in any | + | * '''[then]''' contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true |
| − | single [or] are true | ||
* '''[else]''' contains a set of action tags which should be executed if any condition is false, and all [or] tags are false | * '''[else]''' contains a set of action tags which should be executed if any condition is false, and all [or] tags are false | ||
| Line 46: | Line 44: | ||
The [while] tag is useful for iterating over an array. | The [while] tag is useful for iterating over an array. | ||
An ''array'' is a list of values. | An ''array'' is a list of values. | ||
| − | The ''number | + | The ''number''th value in the array ''array'' is stored in the WML variable '''''array''[number]'''. |
Note that if ''number'' is the value of the variable ''variable'', | Note that if ''number'' is the value of the variable ''variable'', | ||
| − | the expression '''$''array | + | the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''. |
The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array; | The macros 'FOREACH' and 'NEXT' ([[UtilWML]]) can be used to iterate over an array; | ||
i.e. run a set of actions once per element of the array. | i.e. run a set of actions once per element of the array. | ||
| Line 61: | Line 59: | ||
* '''[set_variable]''' manipulates a WML variable. | * '''[set_variable]''' manipulates a WML variable. | ||
** ''name'' the name of the variable to manipulate | ** ''name'' the name of the variable to manipulate | ||
| − | ** ''value'' set the variable to the given value (can be numeric or string). | + | ** ''value'' set the variable to the given value (can be numeric or string). This does not interpret any dollars signs. |
| − | This does not interpret any dollars signs. | + | ** ''format'' set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]]) |
| − | ** ''format'' set the variable to the given value. | ||
| − | Interprets the dollar sign to a higher degree than most actions. (see [[VariablesWML]]) | ||
** ''to_variable'' Fully processes its value as in ''format'', and then gets the variable with that name. | ** ''to_variable'' Fully processes its value as in ''format'', and then gets the variable with that name. | ||
| − | ** ''add'' add the given amount to the variable. | + | ** ''add'' add the given amount to the variable. To subtract, add a negative number. |
| − | To subtract, add a negative number. | + | ** ''multiply'' multiply the variable by the given amount. To divide, multiply by a decimal. To negate, multiply by -1. |
| − | ** ''multiply'' multiply the variable by the given amount. | + | ** ''random'' the variable will be randomly set.<br>You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.<br>You may provide a range of numbers (integers), e.g. 'random=3..5'.<br>You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with ''format''. |
| − | To divide, multiply by a decimal. To negate, multiply by -1. | + | |
| − | ** ''random'' the variable will be randomly set. | + | * '''[store_unit]''' stores details about units into game variables.<br>Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.<br>Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]] |
| − | You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'. | + | ** '''[filter]''' (standard unit filter) all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables. |
| − | You may provide a range of numbers (integers), e.g. 'random=3..5'. | ||
| − | You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance | ||
| − | of getting 100, just like for each of 1 to 9. | ||
| − | Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. | ||
| − | You would need to create the random-string with ''format''. | ||
| − | * '''[store_unit]''' stores details about units into game variables. | ||
| − | Common usage is to manipulate a unit by using [store_unit] to store it into a variable, | ||
| − | followed by manipulation of the variable, | ||
| − | and then [unstore_unit] to re-create the unit with the modified variables. | ||
| − | Note: stored units also exist on the field, | ||
| − | and modifying the stored variable will not automatically change the stats of the units. | ||
| − | You need to use [unstore_unit]. | ||
| − | See also [unstore_unit], [[DirectActionsWML]], and '''FOREACH''', [[UtilWML]] | ||
| − | ** '''[filter]''' (standard unit filter) all units matching this filter will be stored. | ||
| − | If there are multiple units, they will be stored into an array of variables. | ||
** ''variable'' the name of the variable into which to store the unit(s) | ** ''variable'' the name of the variable into which to store the unit(s) | ||
| − | ** ''kill'' if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access | + | ** ''kill'' if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later |
| − | to a player's recall list, with the intent to restore the recall list later | + | * '''[store_starting_location]''' Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x' and 'y'. |
| − | * '''[store_starting_location]''' Stores the starting location of a side's leader in a variable. | ||
| − | The variable is a composite type which will have members 'x' and 'y'. | ||
** ''side'' the side whose starting location is to be stored | ** ''side'' the side whose starting location is to be stored | ||
** ''variable'' (default='location'): the name of the variable to store the location in | ** ''variable'' (default='location'): the name of the variable to store the location in | ||
| − | * '''[store_locations]''' Stores a series of locations that pass certain criteria into an array. | + | * '''[store_locations]''' Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y'. |
| − | Each member of the array has members 'x' and 'y'. | + | ** standard location filter- a location or location range which specifies the locations to store. You must specify this or no locations will be stored. |
| − | ** standard location filter- a location or location range which specifies the locations to store. | ||
| − | You must specify this or no locations will be stored. | ||
** ''variable'' the name of the variable (array) into which to store the locations | ** ''variable'' the name of the variable (array) into which to store the locations | ||
| − | ** ''terrain'' a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) | + | ** ''terrain'' a series of terrain characters. (See [[TerrainLettersWML]] for possible values.) If present, locations will only be chosen if the letter of the terrain type of that location is listed. |
| − | If present, locations will only be chosen if the letter of the terrain type of that location is listed. | + | ** ''radius'' if present, any locations which are within ''radius'' hexes of the location filter will also be stored |
| − | ** ''radius'' if present, any locations | + | ** '''[filter]''' (standard unit filter) only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units. |
| − | which are within ''radius'' hexes of the location filter will also be stored | ||
| − | ** '''[filter]''' (standard unit filter) only locations with units on them that match the filter will be stored. | ||
| − | Use a blank filter to only store locations with units | ||
* '''[store_gold]''' stores the gold for a certain side in a variable. | * '''[store_gold]''' stores the gold for a certain side in a variable. | ||
** ''side'' (default=1) the side for which the gold should be stored | ** ''side'' (default=1) the side for which the gold should be stored | ||
** ''variable'' (default='gold') the name of the variable to store the gold in | ** ''variable'' (default='gold') the name of the variable to store the gold in | ||
| − | * '''[clear_variable]''' This will delete the given variable or array. | + | * '''[clear_variable]''' This will delete the given variable or array. This is good to use to clean up the set of variables |
| − | This is good to use to clean up the set of variables | + | -- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario. |
| − | -- e.g. a well-behaved scenario will delete any variables | ||
| − | that shouldn't be kept for the next scenario before the end of the scenario. | ||
** ''name'' the name of the variable to clear. | ** ''name'' the name of the variable to clear. | ||
| − | * '''[role]''' tries to find a unit to assign a role to. | + | * '''[role]''' tries to find a unit to assign a role to.<br>This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use '''role=''' in a unit filter to identify the unit with that role (See [[FilterWML]]).<br>However, there is no guarantee that roles will ever be assigned. You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. |
| − | This is useful if you want to choose a non-major character | ||
| − | to say some things during the game. | ||
| − | Once a role is assigned, you can use '''role=''' in a unit filter | ||
| − | to identify the unit with that role (See [[FilterWML]]). | ||
| − | However, there is no guarantee that roles will ever be assigned. | ||
| − | You can use '''[have_unit]''' (see [if]) to see whether a role was assigned. | ||
** ''role'' the value to store as the unit's role | ** ''role'' the value to store as the unit's role | ||
| − | ** ''type'' a comma-separated list of possible types the unit can be. | + | ** ''type'' a comma-separated list of possible types the unit can be. A unit of the first type in the list for which a unit of that type exists will be assigned the role |
| − | A unit of the first type in the list for which a unit of that type exists will be assigned the role | ||
== See Also == | == See Also == | ||
| Line 130: | Line 95: | ||
** [[EventWML]] | ** [[EventWML]] | ||
** [[ReferenceWML]] | ** [[ReferenceWML]] | ||
| − | |||
Revision as of 11:44, 8 September 2005
Contents
Internal actions
Internal actions are actions that WML uses internally that do not directly affect gameplay, for example storing a variable.
The internal actions [if], [while], and [event] describe when/whether sets of actions should be executed.
[if]
Executes different sets of actions based on whether the conditions described in the condition tags are true or not.
Condition tags:
- [have_unit] a unit passing this filter with >0 HP exists
- standard unit filter
- [or] If an [or] is present, one must evaluate to true in order for the [if] to evaluate true
- condition tags as in [if] - if these evaluate to true, [or] evaluates to true.
- [variable] tests something about the value of a WML variable (see VariablesWML)
- name the name of the variable to test the value of
Only one of these keys should be used: - equals $name is equal (string wise) to equals
- not_equals $name is not equal to not_equals
- greater_than $name is numerically greater than greater_than
- less_than $name is less than less_than
- greater_than_equal_to $name is not less than greater_than_equal_to
- less_than_equal_to $name is not greater than less_than_equal_to
- numerical_not_equals $name is greater than or less than numerical_not_equals
- numerical_equals $name is not greater than or less than numerical_equals
- name the name of the variable to test the value of
After condition tags:
- [then] contains a set of action tags which should be executed if all conditions are true, or all conditions in any single [or] are true
- [else] contains a set of action tags which should be executed if any condition is false, and all [or] tags are false
[while]
executes commands if all conditions are true. Continues to execute them until a condition is not true.
Executes a maximum of 1024 iterations per invocation. Condition tags are the same as for [if]
After condition tags:
- [do] contains actions that should be executed repeatedly until some condition is false.
The [while] tag is useful for iterating over an array. An array is a list of values. The numberth value in the array array is stored in the WML variable array[number]. Note that if number is the value of the variable variable, the expression $array[$variable] will return the numberth value in array. The macros 'FOREACH' and 'NEXT' (UtilWML) can be used to iterate over an array; i.e. run a set of actions once per element of the array.
== [event] == this adds a new event to the scenario. The event is in the normal format for an [event] tag (See EventWML). This is useful if you want an event that can only be triggered when a prior event is fulfilled
These tags describe actions that affect the values of WML variables (see VariablesWML for information on WML variables, and UtilWML for convenient macro shortcuts for some of these):
- [set_variable] manipulates a WML variable.
- name the name of the variable to manipulate
- value set the variable to the given value (can be numeric or string). This does not interpret any dollars signs.
- format set the variable to the given value. Interprets the dollar sign to a higher degree than most actions. (see VariablesWML)
- to_variable Fully processes its value as in format, and then gets the variable with that name.
- add add the given amount to the variable. To subtract, add a negative number.
- multiply multiply the variable by the given amount. To divide, multiply by a decimal. To negate, multiply by -1.
- random the variable will be randomly set.
You may provide a comma separated list of possibilities, e.g. 'random=Bob,Bill,Bella'.
You may provide a range of numbers (integers), e.g. 'random=3..5'.
You may combine these, e.g. 'random=100,1..9', in which case there would be 1/10th chance of getting 100, just like for each of 1 to 9. Dollars signs are only normally interpreted here, so it is harder to have a dynamically determined range. You would need to create the random-string with format.
- [store_unit] stores details about units into game variables.
Common usage is to manipulate a unit by using [store_unit] to store it into a variable, followed by manipulation of the variable, and then [unstore_unit] to re-create the unit with the modified variables.
Note: stored units also exist on the field, and modifying the stored variable will not automatically change the stats of the units. You need to use [unstore_unit]. See also [unstore_unit], DirectActionsWML, and FOREACH, UtilWML- [filter] (standard unit filter) all units matching this filter will be stored. If there are multiple units, they will be stored into an array of variables.
- variable the name of the variable into which to store the unit(s)
- kill if 'yes' the units that are stored will be removed from play. This is useful for instance to remove access to a player's recall list, with the intent to restore the recall list later
- [store_starting_location] Stores the starting location of a side's leader in a variable. The variable is a composite type which will have members 'x' and 'y'.
- side the side whose starting location is to be stored
- variable (default='location'): the name of the variable to store the location in
- [store_locations] Stores a series of locations that pass certain criteria into an array. Each member of the array has members 'x' and 'y'.
- standard location filter- a location or location range which specifies the locations to store. You must specify this or no locations will be stored.
- variable the name of the variable (array) into which to store the locations
- terrain a series of terrain characters. (See TerrainLettersWML for possible values.) If present, locations will only be chosen if the letter of the terrain type of that location is listed.
- radius if present, any locations which are within radius hexes of the location filter will also be stored
- [filter] (standard unit filter) only locations with units on them that match the filter will be stored. Use a blank filter to only store locations with units.
- [store_gold] stores the gold for a certain side in a variable.
- side (default=1) the side for which the gold should be stored
- variable (default='gold') the name of the variable to store the gold in
- [clear_variable] This will delete the given variable or array. This is good to use to clean up the set of variables
-- e.g. a well-behaved scenario will delete any variables that shouldn't be kept for the next scenario before the end of the scenario.
- name the name of the variable to clear.
- [role] tries to find a unit to assign a role to.
This is useful if you want to choose a non-major character to say some things during the game. Once a role is assigned, you can use role= in a unit filter to identify the unit with that role (See FilterWML).
However, there is no guarantee that roles will ever be assigned. You can use [have_unit] (see [if]) to see whether a role was assigned.- role the value to store as the unit's role
- type a comma-separated list of possible types the unit can be. A unit of the first type in the list for which a unit of that type exists will be assigned the role