TerrainGraphicsWML

[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, core, credits_group, criteria;

D: damage, damage_type, 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, fonts, for, foreach, found_item, 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, resolution, 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 (action, scenario), 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_graphics] tag

For information about the multi-hex tiling system, see MultiHexTutorial

In terrain graphics, all images are assumed to be .png and relative to images/terrain/. For example, writing 'image=grassland' means that the image file is images/terrain/grassland.png.

The multi-hex tiling system adds a new top-level element to WML, [terrain_graphics]. A building rule is used to specify images to place when terrains are in a certain formation. When a building rule is applied to a map, it is applied once to each coordinate on the map; when it is applied to a coordinate then that coordinate is considered the base. All locations in [terrain_graphics] are relative to the base.

The following keys/tags are recognized:

• [tile] whenever a building rule is applied, each [tile] tag corresponds to a tile on the map. The corresponding tile must match each condition contained in [tile] for the [tile] tag to match. All [tile] tags must match in order for a rule to match. If the rule for a [tile] tag is applied, each action within [tile] will be executed on the tile corresponding to that [tile] tag
  • x,y standard coordinates - the location of the corresponding tile relative to the base.
  • pos a shortcut to specifying coordinates. Used in combination with map
  • Conditions for [tile]:
    • type a comma-separated list of terrain codes (See TerrainWML, data/terrain.cfg). In order for a tile to match this condition, it must be one of the terrains specified. However, if the string is preceded by "!", the terrain must not be listed in order to match. If the string is '*', or if it is empty, any tile matches.
    • has_flag a string. Matches if a flag named after the given string is attached to the corresponding tile. Flags are attached using the set_flag key.
    • no_flag a string. Matches if no flag named after the given string has been attached to the corresponding tile. Flags are attached using the set_flag key.
  • Actions for [tile]:
    • set_flag Followed by a string of characters. Attaches a flag named after the given string to the corresponding tile if the rule matches. The only difference a flag makes is being detected by has_flag and no_flag in [tile]. This is determined by the order of the [terrain_graphics] tags; a tag after another one cannot influence it. See also has_flag, no_flag
    • [image] images specified as a subtag to [tile] sets the images for a single tile.
      • layer an integer, usually negative. The more negative it is, the earlier it is drawn, and thus the farther "back" it is when compositing the terrain images together.
      • name the image to apply on this tile if appropriate
• [image] image may also be used directly in the rule, to specify multihex images.
• probability the percent probability for each position that if the position matches, then the rule will be applied. Default is 100(%). See Terrain Graphics Probability for mathematical complications.
• rotations 6 comma(,) separated input strings. A rule that contains this key is not actually checked against the terrain; it instead is used as a template to create 6 new rules, each corresponding to a rotated version of the current rule. Whenever a rotated version is applied, instances of @(at-sign)R0, @R1, ... @R6 in attributes in the [terrain_graphics] tag will be adjusted by the corresponding amount and replaced with the letters specified by that numbered rotation in the rotations list. Each value corresponds to the rotated version that is -Pi/3 (60° clockwise) from the previous version; the first value corresponds to the unrotated version.
  For example, if rotations=n,ne,se,s,sw,nw and it is being rotated 120°, then "@R0"->"@R2"->"se", "@R1"->"@R3"->"s", ... "@R6"->"@R1"->"ne".
  Basically the important thing is that this lets the rule be applied in any of the six hex-directions, allowing you to adjust the name of the image files automatically.
• set_flag,has_flag, no_flag shortcuts to putting these in the [tile] subtags; unbound attributes will apply to all [tile] subtags.
• map a shortcut for defining [tile] tags with type conditions. Inputs a multi-line string value visually describing the map. The lines are cut into words of 4 characters, which correspond to [tile] tags. The line types alternate between lines corresponding to relatively even-abciss tiles and lines preceded by two spaces corresponding to relatively odd-abciss tiles. Every two lines represent 1 row on the map.

Words

A word is a 4-character shortcut to a [tile] tag. There are different types of words:

• Usually a word is interpreted as being the input to the type key of the corresponding [tile]. That is, it creates a [tile] with the attribute type=word.
• A word can also be a digit followed by 3 spaces. In this case, it is a shortcut to the [tile] with the attribute pos=word. This is called anchoring.

(SVN terrain only) The map format for the new Wesnoth version has been changed so this description is for the newer version.

The format is basically the same but the following changes are made

• A word no longer needs to be 4 characters but is comma separated and spaces and tabs may be used for padding
• The 2 spaces for odd lines in no longer used, instead a leading comma is used on these lines (before the comma spaces and tabs are allowed for padding)
• A word may only be a dot a star or an anchor. The terrain letter format was not used and hard to support in the new engine, so that support is dropped.

Examples

To define a north-south 2-tile mountain, the following syntax can be used:

[terrain_graphics]
    [tile]
        x=0
        y=0
        type=m
    [/tile]
    [tile]
        x=0
        y=1
        type=m
    [/tile]
    no_flag="mountain-tile"
    set_flag="mountain-tile"
    image_background="mountain-n-s"
[/terrain_graphics]

This represents a tile T, and its 6 adjacent tiles A, in the map notation.

.   .   .   .
  .   A   .   .
.   A   A   .
  .   T   .   .
.   A   A   .
  .   A   .   .

(to be continued)

For example, the following notations are equivalent:

map="
1
  1
*"


[tile]
    pos=1
    type=CK
[/tile]

=

map="
CK
  CK
*"

=

[tile]
    x=0
    y=0
    type=CK
[/tile]
[tile]
    x=1
    y=0
    type=CK
[/tile]
[tile]
    x=0
    y=1
    type=*
[/tile]

As an example, here are the map representation of rule that would consist on a mountain hex, and 2 grass hexes, all aligned.

.   g    m   .    m    .   m    g   .    g
  g        g             g        g
m   .    .   g    g    g   .    .   m    g

                  g                      m

See Also

• MultiHexTutorial
• ReferenceWML
• Ayin's detailed Terrain Graphics document
• TerrainGraphicsTutorial - First half of Ayin's document, wikified
• TerrainGraphicsReference - Second (partial) half of Ayin's document, wikified