Difference between revisions of "TerrainMaskWML"

From The Battle for Wesnoth Wiki
(border feature)
(Update references to obsolete terrain codes. Also "alot" -> "a lot".)
(4 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== The [terrain_mask] tag ==
+
{{WML Tags}}
  
 
The [terrain_mask] tag makes map manipulation from within WML much easier.
 
The [terrain_mask] tag makes map manipulation from within WML much easier.
 
It uses a Wesnoth map as a "mask" over a given location,
 
It uses a Wesnoth map as a "mask" over a given location,
 
placing it down on top of the scenario map.
 
placing it down on top of the scenario map.
Fog('~') and void(' ') are used like alpha in an image; i.e. they cause the previous terrain to be used.
+
Fog ('_f') and Shroud ('_s') are used like alpha in an image; i.e. they cause the previous terrain to be used.
  
 
* '''x,y''': the x,y location in the scenario map to place the top-left corner of the mask onto
 
* '''x,y''': the x,y location in the scenario map to place the top-left corner of the mask onto
 
* '''mask''': a Wesnoth map; see [[BuildingMaps]].
 
* '''mask''': a Wesnoth map; see [[BuildingMaps]].
* {{DevFeature}} '''border''': (default=no) Overlay on the border as well as the playable map area. The mask used must have a border_size equal to the map's border size (i.e. it must be a normal map), otherwise it will be ignored
+
* '''border''': (default=no) Overlay on the border as well as the playable map area. The mask used must have a border_size equal to the map's border size (i.e. it must be a normal map), otherwise it will be ignored
 
* '''[rule]''': specifies a rule for blending the mask with the scenario.
 
* '''[rule]''': specifies a rule for blending the mask with the scenario.
 
The terrain on each hex fitting the rule will be changed to the terrain specified in the rule.
 
The terrain on each hex fitting the rule will be changed to the terrain specified in the rule.
** '''old''': a comma-separated list of terrain codes. The rule fits only those hexes that have one of these terrains in the scenario.
+
** '''old''': a comma-separated list of terrain codes. The rule fits only those hexes that have one of these terrains in the scenario. If omitted, matches any hex on the base map.
** '''new''': a list of terrain letters. The rule fits only those hexes with this terrain specified in the mask.
+
** '''new''': a list of terrain letters. The rule fits only those hexes with this terrain specified in the mask. If omitted, matches any hex on the mask.
** '''terrain''': the letter of the terrain to change hexes which fit this rule (i.e. for which the '''new''' terrain code in the mask falls on top of the '''old''' terrain in the scenario) into.
+
** '''terrain''': the letter of the terrain to change hexes which fit this rule (i.e. for which the '''new''' terrain code in the mask falls on top of the '''old''' terrain in the scenario) into. If omitted, defaults to either the old or new terrain depending on the value of use_old.
**  {{DevFeature}} '''layer''': (overlay|base|both, default=both) only change the specified layer.
+
**  '''layer''': (overlay|base|both, default=both) only change the specified layer.
**  {{DevFeature}} '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
+
**  '''replace_if_failed''': (default=no) When replacing just one layer failed, try to replace the whole terrain. If '''terrain''' is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
 +
** '''use_old''': if yes, no change is done to hexes matching this rule. If no, the hex is changed to the new terrain or, if specified, the value of the terrain key.
  
 
As an example, suppose you want to lay down a road somewhere. You could specify by hand the path the road takes using
 
As an example, suppose you want to lay down a road somewhere. You could specify by hand the path the road takes using
Line 21: Line 22:
 
[terrain_mask]:
 
[terrain_mask]:
  
 +
<pre>
 
[terrain_mask]
 
[terrain_mask]
 
     x,y=12,10
 
     x,y=12,10
Line 40: Line 42:
 
  "
 
  "
 
  [/terrain_mask]
 
  [/terrain_mask]
 +
</pre>
  
For instance, suppose you want snow to fall in an area. You want villages (v) to turn into snowed-villages (V), forest
+
For instance, suppose you want snow to fall in an area. You want villages on green grass (Gg^Vh) to turn into snowy villages on snow (Aa^Vha), pine forest on semi-dry grass (Gs^Fp) to turn into snowy pine forest on snow (Aa^Fpa), hills (Hh) to turn into snowy hills (Ha), and green grass (Gg) and regular dirt (Re) to turn into snow (Aa), while other terrain remains untouched. You could look over your destination map and work out which terrain type is which and draw your mask, but that's a lot of effort, you want to just draw a simple mask which has areas of snow and areas of no snow, and make the game work out the rest.
(f) to turn into snowed-forest (F), hills
 
(h) to turn into snowed-hills (H), and grassland (g) and roads (r) to turn into snow (S), while other terrain remains
 
untouched. You could look over your
 
destination map and work out which terrain type is which and draw your mask, but that's alot of effort, you want to just
 
draw a simple mask which has
 
areas of snow and areas of no snow, and make the game work out the rest.
 
  
 
You can do it like this:
 
You can do it like this:

Revision as of 16:36, 18 March 2013

[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 [terrain_mask] tag makes map manipulation from within WML much easier. It uses a Wesnoth map as a "mask" over a given location, placing it down on top of the scenario map. Fog ('_f') and Shroud ('_s') are used like alpha in an image; i.e. they cause the previous terrain to be used.

  • x,y: the x,y location in the scenario map to place the top-left corner of the mask onto
  • mask: a Wesnoth map; see BuildingMaps.
  • border: (default=no) Overlay on the border as well as the playable map area. The mask used must have a border_size equal to the map's border size (i.e. it must be a normal map), otherwise it will be ignored
  • [rule]: specifies a rule for blending the mask with the scenario.

The terrain on each hex fitting the rule will be changed to the terrain specified in the rule.

    • old: a comma-separated list of terrain codes. The rule fits only those hexes that have one of these terrains in the scenario. If omitted, matches any hex on the base map.
    • new: a list of terrain letters. The rule fits only those hexes with this terrain specified in the mask. If omitted, matches any hex on the mask.
    • terrain: the letter of the terrain to change hexes which fit this rule (i.e. for which the new terrain code in the mask falls on top of the old terrain in the scenario) into. If omitted, defaults to either the old or new terrain depending on the value of use_old.
    • layer: (overlay|base|both, default=both) only change the specified layer.
    • replace_if_failed: (default=no) When replacing just one layer failed, try to replace the whole terrain. If terrain is an overlay only terrain, use the default_base as base layer. If the terrain has no default base, do nothing.
    • use_old: if yes, no change is done to hexes matching this rule. If no, the hex is changed to the new terrain or, if specified, the value of the terrain key.

As an example, suppose you want to lay down a road somewhere. You could specify by hand the path the road takes using [terrain], or you could use [terrain_mask]:

[terrain_mask]
    x,y=12,10
    mask="border_size=1
 usage=map
 
   Re,   Re,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f
   Re,   Re,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f
   Re,   Re,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f
   _f,   _f,   Re,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f
   _f,   _f,   Re,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f
   Re,   Re,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f,   _f
   _f,   _f,   Re,   _f,   _f,   Re,   Re,   _f,   _f,   _f,   _f,   _f
   _f,   _f,   _f,   Re,   Re,   Re,   _f,   Re,   Re,   _f,   _f,   _f
   _f,   _f,   _f,   _f,   _f,   _f,   _f,   Re,   _f,   _f,   _f,   _f
   _f,   _f,   _f,   _f,   _f,   _f,   _f,   Re,   Re,   _f,   _f,   _f
   _f,   _f,   _f,   _f,   _f,   _f,   _f,   Re,   Re,   Re,   Re,   Re
   _f,   _f,   _f,   _f,   _f,   _f,   _f,   Re,   Re,   Re,   Re,   Re
 "
 [/terrain_mask]

For instance, suppose you want snow to fall in an area. You want villages on green grass (Gg^Vh) to turn into snowy villages on snow (Aa^Vha), pine forest on semi-dry grass (Gs^Fp) to turn into snowy pine forest on snow (Aa^Fpa), hills (Hh) to turn into snowy hills (Ha), and green grass (Gg) and regular dirt (Re) to turn into snow (Aa), while other terrain remains untouched. You could look over your destination map and work out which terrain type is which and draw your mask, but that's a lot of effort, you want to just draw a simple mask which has areas of snow and areas of no snow, and make the game work out the rest.

You can do it like this:

[terrain_mask]
    x,y=1,1
    mask="border_size=1
usage=map

 _f,   _f,   Aa,   _f,   _f,   _f,   Aa,   _f,   _f
 _f,   _f,   Aa,   _f,   _f,   _f,   Aa,   _f,   _f
 _f,   _f,   Aa,   _f,   Aa,   _f,   Aa,   _f,   _f
 Aa,   Aa,   _f,   _f,   Aa,   Aa,   Aa,   _f,   _f
 _f,   _f,   Aa,   Aa,   Aa,   Aa,   Aa,   Aa,   Aa
 _f,   _f,   _f,   Aa,   Aa,   Aa,   Aa,   Aa,   Aa
 _f,   _f,   _f,   _f,   Aa,   Aa,   _f,   _f,   _f
 _f,   _f,   _f,   _f,   Aa,   Aa,   _f,   _f,   _f"
[rule]
   old=Gg^Vh
   new=Aa
   terrain=Aa^Vha
[/rule]
[rule]
   old=Gs^Fp
   new=Aa
   terrain=Aa^Fpa
[/rule]
[rule]
   old=Hh
   new=Aa
   terrain=Ha
[/rule]

[rule]
   old=Gg,Re
   new=Aa
   #don't specify terrain and it just uses the new terrain
[/rule]

#default: Will match everything, since 'old' and 'new' aren't
#specified. Set 'use_old=yes' to signal no change.
[rule]
use_old=yes
[/rule]
[/terrain_mask]