Difference between revisions of "EffectWML"
From The Battle for Wesnoth Wiki
(Mentioned small portraits) |
(Grouped [filter] with the other keys/tags instead of only mentioning it in the summary.) |
||
Line 2: | Line 2: | ||
== the [effect] tag == | == the [effect] tag == | ||
− | The tag [effect] is used to describe one modification to a unit. | + | The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification. Modifications are permanent changes to a unit; currently there is no way of removing a modification. |
− | Any number of [effect] tags can be used to describe a complete | ||
− | modification. | ||
− | Modifications are permanent changes to a unit; | ||
− | currently there is no way of removing a modification | ||
− | |||
− | |||
− | The following keys are always recognized | + | The following keys and subtags are always recognized: |
+ | * '''[filter]''': only apply this effect if the affected unit matches. See [[StandardUnitFilter]] for details. | ||
* '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list) | * '''unit_type''': only apply this effect if the affected unit's type name matches the value. (can be a list) | ||
* '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list) | * '''unit_gender''': only apply this effect if the affected unit's gender name matches the value. (can be a list) | ||
− | * '''times''': describes how | + | * '''times''': describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level. |
* '''apply_to''': describes what the effect actually affects. | * '''apply_to''': describes what the effect actually affects. | ||
[effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values: | [effect] uses different keys depending on the value of '''apply_to'''. '''apply_to''' can take the following values: |
Revision as of 16:02, 30 May 2011
the [effect] tag
The tag [effect] is used to describe one modification to a unit. Any number of [effect] tags can be used to describe a complete modification. Modifications are permanent changes to a unit; currently there is no way of removing a modification.
The following keys and subtags are always recognized:
- [filter]: only apply this effect if the affected unit matches. See StandardUnitFilter for details.
- unit_type: only apply this effect if the affected unit's type name matches the value. (can be a list)
- unit_gender: only apply this effect if the affected unit's gender name matches the value. (can be a list)
- times: describes how many times the effect is applied. The default is to apply the effect once. Other possible value : "per level" which means that the effect is applied level times, where level is the unit level.
- apply_to: describes what the effect actually affects.
[effect] uses different keys depending on the value of apply_to. apply_to can take the following values:
- new_attack: will use all other keys and tags as the description of an attack that will be added to the unit. See [attack] in UnitTypeWML.
- remove_attacks: remove the matching attacks. All tags from the attack filter construct will be used to match the attack; see FilterWML. Do not use a [filter] tag otherwise it will not work properly.
- attack: find an attack and modify it. All tags from the attack filter construct will be used to match the attack; see FilterWML. After that, the following keys and tags can be used to modify the attack. Note: do not use a [filter] tag. Just put the keys you want to filter on inside the [effect] tag.
- set_name: change the attack's name (ie identifier).
- set_description: change the attack's description (ie displayed name).
- set_type: change the attack type. The standard values are blade, pierce, impact, fire, cold, and arcane.
- [set_specials]: change the attack's specials. The specials to add are given exactly as in the [specials] tag.
- mode: if append, adds the given specials to the attack. If replace, replaces the existing specials with the given ones. Default replace.
- remove_specials: remove the listed specials. The value of this key is the coma-separated list of the id of the specials to remove. This key is always evaluated before a [set_specials] tags in the same [effect]
- increase_damage: increases the attack's damage. This can be positive or negative, so you can use it to decrease damage as well. If it ends in a percent('%'), the change in damage will be a percentage ratio of the attack's original damage.
- increase_attacks: increases the number of attack strikes. Like increase_damage, it can be positive or negative, or a percentage.
- attack_weight: change the attack's attack_weight. See [attack] in UnitTypeWML for explanations about attack_weight.
- defense_weight: change the attack's defense_weight. See [attack] in UnitTypeWML for explanations about defense_weight.
- hitpoints: modifies the unit's HP and/or max HP.
- increase: the amount to increase the unit's HP.
- heal_full: if present and not set to "no" the unit will be put back to full HP.
- increase_total: will increase the total HP of the unit. Can be specified either as a negative or a positive value. It can also be specified as a percentage of the current total; i.e. "-50%" will cut max HP in half.
- violate_maximum: it the unit ends up with more than its max HP after these modifications, and this key is present (set to any non-null value, ex. yes), the unit's HP won't be lowered to its max HP.
- movement: modifies the unit's movement points.
- increase: maximum movement is increased by this amount. It can be positive, negative, or specified as a percentage.
- set: maximum movement is set to a specific value.
- max_experience: affects the amount of XP the unit needs for the next level.
- increase: how to change the xp; again it can be negative, positive or a percentage.
- loyal: no keys associated. The affected unit will be loyal i.e have an upkeep of 0.
- movement_costs: speed through specific terrain is modified
- replace: If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
- [movement_costs]: a subtag that describes the new movement costs just like in UnitTypeWML for describing a unit type
- defense: Sets unit chance to be hit in specific terrain (100 - defense value)
- replace: If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
- [defense]: a subtag that describes the new defense just like in UnitTypeWML for describing a unit type
- resistance: Sets percent damage taken from combat
- replace: If set to "true", any new values replace the old ones. Otherwise, new values are added to old values (negative values allowed).
- [resistance]: a subtag that describes the new resistance just like in UnitTypeWML for describing a unit type
- variation: switches the unit into one of its variations.
- name: the id of the variation to invoke.
- type: transforms the unit into a new unit_type.
- name: the id of the unit_type to invoke.
- status: modifies the status affecting the unit.
- add: a list of status modifications to add. Beware, these may be reapplied later, such as when the unit is recalled or levels up; if in an event, you can use [store_unit] and [unstore_unit], modifying unit.status.name directly, to avoid this, or if you are creating the unit, you can just add it to the unit's [status] tag in the [unit] tag. These are listed in [status], SingleUnitWML.
- remove: a list of status modifications to remove.
- zoc: toggle the zone of control.
- value: new value for zoc (0=disable, other=enable).
- profile: customize the profile of the unit. See UnitTypeWML.
- portrait: new image to display when the unit speaks.
- small_portrait: Template:DevFeature1.9 new image to display in unit reports.
- description: sets the text to display when hovering over the unit's type in the righthand pane.
- new_ability: Adds one or more abilities to a unit.
- [abilities]: A subtag that contains the ability definitions.
- remove_ability: Removes one or more abilities from a unit. Abilities are not reference counted: added, added, removed = gone.
- [abilities]: A subtag that contains the ability definitions. Strictly speaking, all that is needed is the id= inside some tag.
- new_animation: contain animations that will be added to the unit, it can contain multiple animation blocks, Template:DevFeature1.9 and a single "id=" line. That Id should be unique for each effect block and is used by the engine to reuse WML parsing, making the loading faster.
- image_mod: modify the image path function(ImagePathFunctionWML) of all the unit's frames.
- replace: replaces the image path function(s) to be used, e.g. "RC(magenta>red)"
- add: adds an image path function without removing any existing ones.
- ellipse: Change the image used for the unit's ellipse.
- ellipse : the new image to use.