TerrainCodesWML

From The Battle for Wesnoth Wiki
Revision as of 21:41, 2 January 2007 by SkeletonCrew (talk | contribs) (added info on the new terrain system)

[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, 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, 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;

Values of terrain letters

What each letter represents in Wesnoth maps, and the possible values of the letter key.

See TerrainWML for information on how to define a terrain.

  • A human (snow) hill village
  • a human hill village
  • B desert village (adobe)
  • b human mountain village
  • C castle
  • c shallow water, "coast"
  • D underground village (cave, village), "dungeon village"
  • d sand, (old desert)
  • E desert road
  • e elven (snow) village
  • F forest (snow)
  • f forest
  • G savanna (grass)
  • g grass
  • H hills (snow)
  • h hills
  • I desert
  • i ice (tundra)
  • J desert hills
  • j -nothing- (will be snowy mountains)
  • K keep (castle)
  • k river ford (grass, shallow water)
  • L tropical forest village (savanna, village)
  • l lava (canyon)
  • M desert mountains
  • m mountain
  • N ruined castle
  • n encampment (castle)
  • O -nothing- (will probably be an Orc Castle one day)
  • o dwarven castle (castle)
  • P desert oasis
  • p dwarven village
  • Q sunken ruin
  • q ruin (swamp)
  • R road (grass)
  • r dirt (grass)
  • S tundra
  • s deep water
  • T forest (tropical)
  • t village
  • U desert village (tent)
  • u cave
  • V snow village (tundra, village)
  • v human village (village)
  • W cavewall
  • w swamp
  • X canyon (replaced by chasm in trunk)
  • x reserved for UMCs
  • Y swamp village (swamp, village)
  • y reserved for UMCs
  • Z mermen village (shallow water)
  • z reserved for UMCs
  • /,|,\ bridge (grass, shallow water)
  • ~ fog
  • ' ' void/shroud (it uses the "space" character)
  • * reserved for UMCs
  • ^ reserved for UMCs
  • % reserved for UMCs
  • @ reserved for UMCs
  • [ rockbound cave
  • ] mushroom grove
  • ' illuminated cave
  •  ? great Elven tree
  • & impassable mountains
  • "  ???
  • $  ???
  • .  ???
  •  ;  ???
  •  :  ???
  • <  ???
  • >  ???
  • _  ???
  • `  ???

Reserved letters and non-letter Characters

Reserved letters are for custom terrains in user-made campaigns. In addition to these it is currently also possible to use other characters not on the above list to represent custom terrain, such as ½ § @ % etc., but new "official" terrain may be assigned for these characters in the future. So when creating custom terrain, the letters marked as reserved on the above list should be used first. Use campaign definitions (see CampaignWML) to prevent your custom terrains from interfering with other campaigns.

Terrain strings (SVN terrain only)

The terrains will be changed from a single letter to a multi letter system. There will be a compability layer for a short while. This layer doesn't work for campaigns with custom terrains, these campaigns have to be changed to use the new system.

The following rules are stated for the new terrain letters, note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.

  • terrain strings are between 2 and 4 characters
  • terrain strings start with a capital letter and the following letters are lower case
  • terrain strings can only contain letters
  • the underscore is used for internal terrains
  • the star '*' can be used for wildcards in some parts

Starting positions are defined by a number followed by 1 space and then the terrain string; this means that a starting position is no longer automatically a keep.

The letters Y,y,Z,z are reserved for UMC so any string containing any of these letters is a custom terrain. Other undefined terrain strings are reserved for future expansion within Wesnoth.

Conversion form old to new

There's a conversion perl script for map named map_convert.pl. This script will convert a map with the old letters to the new strings. Some parts still have to be done manually, here a lookup table with the letters. 

char= a    b    c    d    e    f    g    h    i    j    k    l    m      
str=  Vhh  Vhm  Ww   Ds   Vea  Ff   Gg   Hh   Ai        Wwf  Ql   Mm   

char= n    o    p    q    r    s    t    u    v    w    x    y    z
str=  Ce   Cud  Vud  Chs  Re   Wo   Veg  Uu   Vhg  Ss 

char= A    B    C    D    E    F    G    H    I    J    K    L    M      
str=  Vhha Vda  Ch   Vu   Rd   Fa   Gs   Ha   Dd   Hd   _K   Vht  Md

char= N    O    P    Q    R    S    T    U    V    W    X    Y    Z
str=  Chr       Do   Chw  Rr   Aa   Ft   Vdt  Vha  Xu   Qxu  Vs   Vwm

char= /    |    \    &    _    ~    ?    ]
str=  Bww/ Bww| Bww\ Xu   _s   _f   Fet  Uh


  • added reminder to add fog/shroud to the editor
  • added idea to maybe add support to add tiles at the top and left

proposal 2.0

  • removed editor changes from proposal and moved to own topic
  • removed the discussion points and wrote the conclusion
  • rewrote User:SkeletonCrew#terrain_strings
  • rewrote the letter proposal, with the input given so far

proposal 2.1

  • Eleazar changed some terrain definitions and fixed some errors I made in them
  • added section about starting positions and the new definition
  • added extra keeps and changed the way they're going to work

proposal 2.2

  • added AnimationWML section

proposal 2.3

  • changed encountered terrain section

terrain

Every terrain type gets a new field named string this will be the new string to use to refer to the terrain. The old char field will stay for the existing terrains, this is needed to convert older maps to be used with the new engine.

This string will exist of 2 to 4 characters, the allowed characters are all letters (the engine is case sensitive), all numbers and the symbols / | \. Note leading numbers are not allowed in the string, they might give confusion with starting locations. Other characters are reserved for special uses in the engine.

The limit of 4 characters is not the upper limit of the engine, but the upper level for easy parsing. The internal format uses 4 bytes and every character is 1 byte. This way it's very easy to convert the characters to the internal format. If more letters are required it will require some modifications to the engine.

I'm considering to allow 1 character terrains as well since I've some trouble to find a second letter everywhere.

Every terrain will also get a new field named theme this is explained in the editor section.

scenario map

The map will use the new strings instead of the old letters. For every tile a string will be used instead of one letter, these strings are separated with a comma. Between the string and the comma one or more spaces are allowed.

Instead of spaces tabs are allowed, but keep in mind what looks good in your text editor, might look horrible in the editor of somebody else. The official files should use spaces.

The WML for map will use the same format. The letter for map WML will use a single terrain string without comma's.

Terraingraphics

The need two modifications the map format and the type format.

map

This format will change a bit more than the other items. The old format is described here TerrainGraphicsWML. According to mog the letters in the map are never used, only the anchors are used. The new format will only accept anchors. The special characters . and * will stay the same.

This map file will no longer be space separated but comma separatedand. Odd lines will start with a leading comma instead of 2 spaces. Spaces are allowed for padding

Also here tabs are allowed instead of spaces, see previous section.

For example this 

map="
  1
1   1
  2
1   1
  1"

will become 

map="
,1
1,1
,2
1,1
,1"

or 

map="
, 1
1 , 1
, 2
1 , 1
, 1"

type

The type will be a list of terrains, comma separated. Spaces are allowed but then the items need to be between brackets. (A WML rule.) Also after special modifiers a comma is required (at the moment only the ! is a special modifier, but that might change in the future.)

Mog had an idea which will also be implanted, the * can be used in a terrain string, V* would match all terrain strings starting with the letter 'V'. Vh* would match all terrain strings starting with 'Vh' eg Vh, Vha, Vhaa but not VH or vH.

terrain files

Eleazar would like to move the terrains in subfolders, this seems to be possible with the current system. The required modifications can be found in the following changelog http://svn.gna.org/viewcvs/wesnoth?rev=14069&view=rev

I've no idea what the best possible directory layout will be. I'll ask Eleazar to do this change when I'm ready for it. At the moment I've some patches in my queue which will conflict with these changes.

terrain strings

The terrain strings will consist of 2 till 4 letters which indicate the terrain. Numbers are not allowed except for starting positions. See next section. The following special characters can be used /|\ these should be used for directional terrains, which are only bridges at the moment.

The terrain letter _ is reserved for interal special terrains this will alway be used as leading character and not used inside strings.

For readability terrains should start with a capital letter followed by one or more lowercase letters (with a maximum of 3 lower case letters). The official terrains must follow these rules, the custom terrains should follow these rules.

There will be some letters reserved for user made content these letters are Y, y, Z, z. This means every terrain with one or more of these letters inside are custom terrains. This way it's easier to integrate a new terrain without having to change the terrain-graphics.cfg.

Since UTBS is mainline the custom terrain used there will be moved to the new system.

starting positions

The new system will allow to define a starting position and terrain in the map file.

The new format is "nnwtttt"

  • n is a number and must be at least 1 position, this number defines the starting position, for alignment the engine assumes a maximum of 2 positions
  • w is one space, needed for readability and easy parsing
  • t is the terrain string

For backwards compability the "wtttt" part can be ommitted and the terrain will automatically become _K but support won't last forever (see User:SkeletonCrew#Specials).

At the moment Wesnoth supports 9 starting positions, this proposal allows for more positions but the engine can't use the extra positions. This limit will be removed in the near future.

aliases

The aliases will also be a comma separated list, where the same discussion about the + and - can be started as in the types.

terrains sorted per group

This list shows the string for the terrains, the italic strings are reservations for terrains. The old letter is extra shown for as an extra reference.

Snow terrains

String Old letter Description Theme
Ai i ice snow
Aa S tundra "Arctic" snow

Bridges

Since bridges are directional all strings here will be appended with either /|\ to show their direction. In this list these signs are replaced with a *.

String Old letter Description Theme
Brx* Bridge of stones over chasm for aboveground bridge
Bxu* Bridge over chasm underground bridge
Bsw* wooden bridge over swamp NOTE bws Brigde wood swamp bridge
Bwr* Stone Bridge over shallow water NOTE bss Bridge stone swamp not better? bridge
Bww* /|\ wooden bridge bridge, over wadeable, wooden NOTE Brigde wood or Bridge wood water not better? bridge, common

Castles

String Old letter Description Theme
Ce n encampment (castle) castle, common
Ch C human castle castle, common
Chr N ruined castle castle
Chs q human ruin (swamp) castle
Chw Q human sunken ruin castle
Co O will be an Orc Castle one day castle
Cud o dwarven castle "castle underground, dwarf" castle, underground

desert

NOTE still need to add the UTBS terrains

String Old letter Description Theme
Dd I desert desert
Do P desert oasis desert
Ds d sand, (old desert) desert

Forest

String Old letter Description Theme
Fa F forest (snow) "forest arctic" forrest, snow
Fb Sinister Forest "Forest, Bad" forrest
Fet ? great Elven tree forrest
Ff f forrest forrest, common
Ft T forrest tropical forrest

Grass

String Old letter Description Theme
Gb dying "Grass brown/bad" grass
Gf Farmer's Fields grass
Gg g grass grass, common
Gs G savanna (grass) grass

hill

String Old letter Description Theme
Ha H hills (snow) "hills arctic" hill, snow
Hd J desert hills (dunes) hill, desert
Hh h hills hill, common

Keep

The keep definition is now done with terrain transition WML, since we're no longer out of letters, this will be done manually. the _K is for backwards compability but this will remove at some point see specials. The _K uses the castle transition WML the new ones don't. This would also allow to mix items, eg een Kh keep in a Ce castle.

String Old letter Description Theme
_K K keep (castle) keep, common
Ke encampment (keep) keep, common
Kh keep castle keep, common
Khr ruined keep keep
Khs human ruin keep(swamp) keep
Khw human sunken ruin keep keep
Ko will be an Orc keep one day keep
Kud dwarven keep "keep underground, dwarf" keep, underground

Mountain

String Old letter Description Theme
Ma j snowy mountains mountain, snow
Md M desert mountains mountain, desert
Mm m mountain mountain, common

(mostly) Impassable

String Old letter Description Theme
Qx chasm for above ground misc
Qxu X chasm for underground misc, underground
Qxw aboveground chasm with water pouring over the edge misc
Ql l lava misc
Qr stone wall misc

road

String Old letter Description Theme
Rc Carpeted Floor road
Rd E desert road road, desert
Re r dirt road "earth" road, common
Rr stone road "rock" road
Rw Wood floor (interior) road

swamp

String Old letter Description Theme
Sb fetid swamp "Swamp Bad" swamp
Ss w swamp swamp

underground

String Old letter Description Theme
Uf ] mushroom grove "underground forest" underground
Uh [ rockbound cave (functionally "underground hill") underground
Uu u normal cave underground
Uuc normal cave, carved underground
Uui ' illuminated cave underground

village

String Old letter Description Theme
Vda B desert village (adobe) village, desert
Vdt U desert village (test) village, desert
Veg t elven village "village elven grassland" village
Ves e elven (snow) village village, snow
Vha V village, snow snow village (tundra, village) village, snow
Vhg v human village (village) village, common
Vhh a human hill village village, hill, common
Vhha A human (snow) hill village village, snow, hill
Vhm b human mountain village village, mountain
Vht L tropical village (savanna, village) --nothing foresty about this village village
Vu D underground village (cave, village) village, underground
Vud p dwarven village village, underground
Vwm Z mermen village (shallow water) village, water
Vs Y swamp village (swamp, village) village, swamp

water

String Old letter Description Theme
Wo s deep water "water, ocean" water, common
Ww c shallow water, "water, wade-able" water, common
Wwf k river ford "water wadeable, ford" water
Wwu shallow underground water water, underground

Impassable

String Old letter Description Theme
Xm & impassable moutains impassable, mountain
Xrw Impassable stone "rock" wall (interior) impassable
Xu W cavewall impassable, underground
Xuc cavewall, carved impassable, underground
Xww Impassable wooden wall (interior) impassable

Specials

These terrains are hardcoded in the game and translated automatically. The old UMC terrains are here for backwards compability this compability will only be guaranteed till the next major release after 1.2.(That would be 1.4 or 2.0.) As stated before the * will no longer be supported.

String Old letter Description Theme
_f ~ fog misc
_s (space character) void/shroud misc

See Also

Retrieved from "https://wiki.wesnoth.org/index.php?title=TerrainCodesWML&oldid=13249"