Difference between revisions of "TerrainWML"

From The Battle for Wesnoth Wiki
(prelim discussion of symbol_image key)
(the toplevel [terrain_type] tag: Note that max_light can stack with TOD bonus)
(37 intermediate revisions by 19 users not shown)
Line 1: Line 1:
== the toplevel [terrain] tag ==
+
{{WML Tags}}
 +
== the toplevel [terrain_type] tag ==
  
the [terrain] tag describes a terrain in WML.
+
The [terrain_type] tag describes a terrain in WML.
 
Terrains are usually described in the terrain.cfg file
 
Terrains are usually described in the terrain.cfg file
  
the [terrain] tag has the following keys and subtags
+
the [terrain_type] tag has the following keys and subtags
* ''image'' an image used for this terrain in the map editor
+
* '''symbol_image''': an image used for this terrain in the minimap
* ''symbol_image'' appears to work the same as ''image'' - clarification is needed
+
* '''editor_image''': an image used for this terrain in the map editor; if not defined uses symbol_image
* ''adjacent_image'' a prefix for adjacent terrain images. they will be postfixed with the orientation of the border to give the image name that will be used for the border terrain
+
* '''icon_image''': an image used for this terrain to indicate defence/movement; shown in the help, and in the sidebar when the terrain is highlighted
* ''name'' the name of the terrain
+
* '''id''': a non-translatable string identifying this terrain. It is used as the key for attributes in some parts of WML, such as {{tag|UnitsWML|movetype}} (but see also the aliasof= attribute below; not all ids need to be listed under movetypes).
* ''char'' the character used to represent this terrain in maps and scenarios
+
* '''name''': the name of the terrain, a translatable string used for the display of terrain type in the game and the map editor
* ''aliasof'' characters representing terrains that this terrain will be an alias of. (i.e. Units' defense and movement on this terrain is equal to their best defense/movement on one of these aliases.) (All terrains are aliases of themselves.)
+
* '''description''': the detailed description of the terrain, a translatable string used for the display of terrain type in the game and the map editor.  If this is not present, the game and editor will fall back to the '''name''' attribute.  The difference is that the name tends to describe the game effect of the terrain type (e.g., "Forest") but the description attribute also carries information about visual subtype (e.g. "Summer Deciduous Forest").
* ''unit_height_adjust'' how much the unit graphic should be moved up or down when on that terrain
+
* '''editor_name''': a detailed name for the terrain used only in the map editor. Terrains are presented in the editor as "''<editor_name>''/''<name>'' (''<aliases>'')" when this attribute is used.
* ''submerge'' float, between 0 and 1: stems how much of the unit graphic should be submerged by the terrain
+
* '''string''': this is the string that represents the terrain in maps and scenarios
* ''no_overlay'' whether this terrain should be overwritten by other terrain's borders; 'no_overlay=true' terrains are not overwritten.
+
* '''unit_height_adjust''': how much the unit graphic should be moved up or down when on that terrain
* ''light'' if set to true the text on it will be written in a dark color instead of a light one. This is useful when the terrain is either very light or very clear (like snow).
+
* '''submerge''': float, between 0 and 1: specifies how much of the unit graphic should be submerged by the terrain
* ''heals'' if set to true a unit on that terrain will be healed at the start of every turn
+
* '''light''': signed value: this will modify the local light level on that hex by that amount for gameplay.
* ''gives_income'' if set to true, this terrain will give income every turn when flagged as if it were a village
+
* '''max_light''': signed value: this is the maximum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is higher. If this is higher than the time-of-day lighting then the local light level can stack in addition to the TOD light - for example, lava (light=25, max_light=35) provides a 35% boost for lawful units at daytime.
* ''recruit_onto'' if set to true, it is possible to recruit or recall on that terrain
+
* '''min_light''': signed value: this is the minimum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is lower.
* ''recruit_from'' if set to true it is possible to recruit when a unit that can recruit is on that terrain
+
* '''heals''': positive value: the amount of HP a unit on this terrain will be healed at the start of every turn.
 +
* '''gives_income''': if set to true, this terrain will give income every turn when flagged, as if it were a village
 +
* '''recruit_onto''': if set to true, it is possible to recruit or recall on that terrain
 +
* '''recruit_from''': if set to true it is possible to recruit when a unit that can recruit is on that terrain
 +
* '''aliasof''': comma separated string of terrains of which this terrain will be an alias. This is a list of terrains, with + and - signs having special meanings. The string is read left to right taking the best value until a minus sign is encountered, after which it takes the worst value instead. The plus sign reverts to best value. (Note: after a + or - a comma is also required. In order to include a + sign the entire line must be placed between double quotes.)
 +
* '''def_alias''': like ''aliasof'' but overides it for defense calculation only
 +
* '''mvt_alias''': like ''aliasof'' but overides it for movement calculation only
 +
* '''vision_alias''': has no effect, see [https://github.com/wesnoth/wesnoth/pull/4278 PR #4278].
 +
* '''income_description''': for terrains with ''gives_income'' and owned by nobody this text is shown in the terrain description in the top bar before the brackets. This tag is optional, if not supplied Wesnoth will assume the terrain is a village and sets an appropriate message.
 +
* '''income_description_ally''': like ''income_description'' but if owned by an ally
 +
* '''income_description_enemy''': like ''income_description'' but if owned by an enemy
 +
* '''income_description_own''': like ''income_description'' but if owned by yourself
 +
* '''editor_group''': a comma separated list of editor_group ids to which this terrain belongs.
 +
* '''hidden''': (boolean) if set to 'yes', makes this terrain not appear in the map editor palettes.
 +
* '''hide_help''': (boolean) if set to 'yes', makes this terrain not appear in the terrain help browser.
  
 
== See Also ==
 
== See Also ==
  
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
* [[TerrainLettersWML]]
+
* [[TerrainCodesWML]]
 +
* [[EditorWML]]
 +
 
 +
 
 +
[[Category: WML Reference]]

Revision as of 15:23, 1 October 2019

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, credits_group, criteria;

D:

damage, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, found_item, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

the toplevel [terrain_type] tag

The [terrain_type] tag describes a terrain in WML. Terrains are usually described in the terrain.cfg file

the [terrain_type] tag has the following keys and subtags

  • symbol_image: an image used for this terrain in the minimap
  • editor_image: an image used for this terrain in the map editor; if not defined uses symbol_image
  • icon_image: an image used for this terrain to indicate defence/movement; shown in the help, and in the sidebar when the terrain is highlighted
  • id: a non-translatable string identifying this terrain. It is used as the key for attributes in some parts of WML, such as [movetype] (but see also the aliasof= attribute below; not all ids need to be listed under movetypes).
  • name: the name of the terrain, a translatable string used for the display of terrain type in the game and the map editor
  • description: the detailed description of the terrain, a translatable string used for the display of terrain type in the game and the map editor. If this is not present, the game and editor will fall back to the name attribute. The difference is that the name tends to describe the game effect of the terrain type (e.g., "Forest") but the description attribute also carries information about visual subtype (e.g. "Summer Deciduous Forest").
  • editor_name: a detailed name for the terrain used only in the map editor. Terrains are presented in the editor as "<editor_name>/<name> (<aliases>)" when this attribute is used.
  • string: this is the string that represents the terrain in maps and scenarios
  • unit_height_adjust: how much the unit graphic should be moved up or down when on that terrain
  • submerge: float, between 0 and 1: specifies how much of the unit graphic should be submerged by the terrain
  • light: signed value: this will modify the local light level on that hex by that amount for gameplay.
  • max_light: signed value: this is the maximum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is higher. If this is higher than the time-of-day lighting then the local light level can stack in addition to the TOD light - for example, lava (light=25, max_light=35) provides a 35% boost for lawful units at daytime.
  • min_light: signed value: this is the minimum local light level that may be indicated by light=. Defaults to the value of light= and is effectively overridden by the time-of-day lighting, if that is lower.
  • heals: positive value: the amount of HP a unit on this terrain will be healed at the start of every turn.
  • gives_income: if set to true, this terrain will give income every turn when flagged, as if it were a village
  • recruit_onto: if set to true, it is possible to recruit or recall on that terrain
  • recruit_from: if set to true it is possible to recruit when a unit that can recruit is on that terrain
  • aliasof: comma separated string of terrains of which this terrain will be an alias. This is a list of terrains, with + and - signs having special meanings. The string is read left to right taking the best value until a minus sign is encountered, after which it takes the worst value instead. The plus sign reverts to best value. (Note: after a + or - a comma is also required. In order to include a + sign the entire line must be placed between double quotes.)
  • def_alias: like aliasof but overides it for defense calculation only
  • mvt_alias: like aliasof but overides it for movement calculation only
  • vision_alias: has no effect, see PR #4278.
  • income_description: for terrains with gives_income and owned by nobody this text is shown in the terrain description in the top bar before the brackets. This tag is optional, if not supplied Wesnoth will assume the terrain is a village and sets an appropriate message.
  • income_description_ally: like income_description but if owned by an ally
  • income_description_enemy: like income_description but if owned by an enemy
  • income_description_own: like income_description but if owned by yourself
  • editor_group: a comma separated list of editor_group ids to which this terrain belongs.
  • hidden: (boolean) if set to 'yes', makes this terrain not appear in the map editor palettes.
  • hide_help: (boolean) if set to 'yes', makes this terrain not appear in the terrain help browser.

See Also