Difference between revisions of "TerrainCodesWML"

From The Battle for Wesnoth Wiki
(Conversion form old to new)
m (Decoding the Terrain Codes)
(38 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== Values of terrain letters ==
 
  
What each letter represents in Wesnoth maps,
+
Note: the old (1.2) terrain system is no longer documented here. If you have 1.2 maps you will need to convert them using [[Maintenance_tools|wmllint]].
and the possible values of the ''letter'' key.
 
  
See [[TerrainWML]] for information on how to define a terrain.
+
== Terrain strings ==
  
* '''A''' human (snow) hill village
+
The following rules hold for terrain strings. Note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.
* '''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==
+
* terrain strings are composed from one or more terrain codes of 2 to 4 characters each, separated by ^.
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.
+
* terrain codes start with a capital letter and the following letters are lower case
Use campaign definitions (see [[CampaignWML]]) to prevent your custom terrains from interfering with other campaigns.
+
* terrain strings can only contain letters, the symbols /|\ which are meant for directional items like bridges and the symbol ^
 
+
* the underscore is used as a leader for internal terrain codes
== Terrain strings '''''[[User:SkeletonCrew#Branch_terrain|(SVN terrain only)]]''''' ==
+
* the star '*' can be used for wildcards in some places where a terrain code is required
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 symbol ^ indicates that a terrain is created with layers, for example Gs^Fp means Semi-dry Grass(<b>Gs</b>) with a Forest(<b>Fp</b>) overlay.
 
 
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 and the symbols /|\ which are meant for directional items like bridges.
 
* 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.
 
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.
Line 99: Line 18:
 
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.
 
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 ===
+
=== Terrain Table ===
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     
+
The list of terrains can be found at [[TerrainCodeTableWML]]. Since most overlays can be combined with most bases the list is not complete.
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
+
== Adding terrains ==
str=  Ce  Cud  Vud  Chs  Re  Wo  Veg  Uu  Vhg  Ss
+
When adding terrains make sure the following files are also checked:
 
 
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\ Xm  _s  _f  Fet  Uf  Uh  Uui
 
 
 
=== 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 ====
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Ai</td>
 
<td>i</td>
 
<td>ice</td>
 
<td>snow</td>
 
</tr>
 
 
 
<tr>
 
<td>Aa</td>
 
<td>S</td>
 
<td>tundra "Arctic"</td>
 
<td>snow</td>
 
</tr>
 
 
 
</table>
 
 
 
==== 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 *.
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td><i>Brx*</i></td>
 
<td></td>
 
<td>Bridge of stones over chasm for aboveground</td>
 
<td>bridge</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Bxu*</i></td>
 
<td></td>
 
<td>Bridge over chasm underground</td>
 
<td>bridge</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Bsw*</i></td>
 
<td></td>
 
<td>wooden bridge over swamp</td>
 
<td>bridge</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Bwr*</i></td>
 
<td></td>
 
<td>Stone Bridge over shallow water</td>
 
<td>bridge</td>
 
</tr>
 
 
 
<tr>
 
<td>Bww*</td>
 
<td>/|\</td>
 
<td>wooden bridge bridge, over wadeable, wooden</td>
 
<td>bridge, common</td>
 
</tr>
 
 
 
</table>
 
 
 
==== Castles ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Ce</td>
 
<td>n</td>
 
<td>encampment (castle)</td>
 
<td>castle, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Ch</td>
 
<td>C</td>
 
<td>human castle</td>
 
<td>castle, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Cv</td>
 
<td></td>
 
<td>Elven castle</td>
 
<td>castle</td>
 
</tr>
 
 
 
<tr>
 
<td>Chr</td>
 
<td>N</td>
 
<td>ruined castle</td>
 
<td>castle</td>
 
</tr>
 
 
 
<tr>
 
<td>Chs</td>
 
<td>q</td>
 
<td>human ruin (swamp)</td>
 
<td>castle</td>
 
</tr>
 
 
 
<tr>
 
<td>Chw</td>
 
<td>Q</td>
 
<td>human sunken ruin</td>
 
<td>castle</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Co</i></td>
 
<td>O</td>
 
<td>will be an Orc Castle one day</td>
 
<td>castle</td>
 
</tr>
 
 
 
<tr>
 
<td>Cud</td>
 
<td>o</td>
 
<td>dwarven castle "castle underground, dwarf"</td>
 
<td>castle, underground</td>
 
</tr>
 
 
 
</table>
 
 
 
==== desert ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Dd</td>
 
<td>I</td>
 
<td>desert</td>
 
<td>desert</td>
 
</tr>
 
 
 
<tr>
 
<td>Do</td>
 
<td>P</td>
 
<td>desert oasis</td>
 
<td>desert</td>
 
</tr>
 
 
 
<tr>
 
<td>Ds</td>
 
<td>d</td>
 
<td>sand, (old desert)</td>
 
<td>desert</td>
 
</tr>
 
 
 
</table>
 
 
 
==== Forest ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Fa</td>
 
<td>F</td>
 
<td>forest (snow) "forest arctic"</td>
 
<td>forrest, snow</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Fb</i></td>
 
<td></td>
 
<td>Sinister Forest "Forest, Bad"</td>
 
<td>forrest</td>
 
</tr>
 
 
 
<tr>
 
<td>Fet</td>
 
<td>?</td>
 
<td>great Elven tree</td>
 
<td>forrest</td>
 
</tr>
 
 
 
<tr>
 
<td>Ff</td>
 
<td>f</td>
 
<td>forrest</td>
 
<td>forrest, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Ft</td>
 
<td>T</td>
 
<td>forrest tropical</td>
 
<td>forrest</td>
 
</tr>
 
 
 
</table>
 
 
 
==== Grass ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td><i>Gb</i></td>
 
<td></td>
 
<td>dying "Grass brown/bad"</td>
 
<td>grass</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Gf</i></td>
 
<td></td>
 
<td>Farmer's Fields</td>
 
<td>grass</td>
 
</tr>
 
 
 
<tr>
 
<td>Gg</td>
 
<td>g</td>
 
<td>grass</td>
 
<td>grass, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Gs</td>
 
<td>G</td>
 
<td>savanna (grass)</td>
 
<td>grass</td>
 
</tr>
 
 
 
</table>
 
 
 
==== hill ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Ha</td>
 
<td>H</td>
 
<td>hills (snow) "hills arctic"</td>
 
<td>hill, snow</td>
 
</tr>
 
 
 
<tr>
 
<td>Hd</td>
 
<td>J</td>
 
<td>desert hills (dunes)</td>
 
<td>hill, desert</td>
 
</tr>
 
 
 
<tr>
 
<td>Hh</td>
 
<td>h</td>
 
<td>hills</td>
 
<td>hill, common</td>
 
</tr>
 
 
 
</table>
 
 
 
==== 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 be removed in the near future. The _K uses the special
 
castle transition WML the new ones don't. This would
 
also allow to mix items, eg a Kh keep in a Ce castle.
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>_K</td>
 
<td>K</td>
 
<td>keep (castle)</td>
 
<td>keep, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Ke</td>
 
<td></td>
 
<td>encampment (keep)</td>
 
<td>keep, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Kh</td>
 
<td></td>
 
<td>keep castle</td>
 
<td>keep, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Khr</td>
 
<td></td>
 
<td>ruined keep</td>
 
<td>keep</td>
 
</tr>
 
 
 
<tr>
 
<td>Khs</td>
 
<td></td>
 
<td>human ruin keep(swamp)</td>
 
<td>keep</td>
 
</tr>
 
 
 
<tr>
 
<td>Khw</td>
 
<td></td>
 
<td>human sunken ruin keep</td>
 
<td>keep</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Ko</i></td>
 
<td></td>
 
<td>will be an Orc keep one day</td>
 
<td>keep</td>
 
</tr>
 
 
 
<tr>
 
<td>Kud</td>
 
<td></td>
 
<td>dwarven keep "keep underground, dwarf"</td>
 
<td>keep, underground</td>
 
</tr>
 
 
 
</table>
 
 
 
==== Mountain ==== 
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td><i>Ma</i></td>
 
<td></td>
 
<td>snowy mountains</td>
 
<td>mountain, snow</td>
 
</tr>
 
 
 
<tr>
 
<td>Md</td>
 
<td>M</td>
 
<td>desert mountains</td>
 
<td>mountain, desert</td>
 
</tr>
 
 
 
<tr>
 
<td>Mm</td>
 
<td>m</td>
 
<td>mountain</td>
 
<td>mountain, common</td>
 
</tr>
 
 
 
</table>
 
 
 
==== (mostly) Impassable ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td><i>Qx</i></td>
 
<td></td>
 
<td>chasm for above ground</td>
 
<td>misc</td>
 
</tr>
 
 
 
<tr>
 
<td>Qxu</td>
 
<td>X</td>
 
<td>chasm for underground</td>
 
<td>misc, underground</td>
 
</tr>
 
  
<tr>
+
data/multiplayer/factions/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.
<td><i>Qxw</i></td>
 
<td></td>
 
<td>aboveground chasm with water pouring over the edge</td>
 
<td>misc</td>
 
</tr>
 
  
<tr>
+
data/core/macros/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.
<td>Ql</td>
 
<td>l</td>
 
<td>lava</td>
 
<td>misc</td>
 
</tr>
 
  
<tr>
+
== Decoding the Terrain Codes ==
<td><i>Qr</i></td>
+
The initial letters of each terrain code have a standard meaning, though some are not obvious.
<td></td>
+
* A = “Arctic”  i.e. frozen
<td>stone wall</td>
+
* B = “Bridge”
<td>misc</td>
+
* C = “Castle”
</tr>
+
* D = “Desert”
 +
* E = "Embellishment"
 +
* F = “Forest”
 +
* G = “Grass” i.e. flat
 +
* H = “Hills”
 +
* I = "Interior" (possible future use)
 +
* J = ''testing''
 +
* K = “Keep”
 +
* L
 +
* M = “Mountains”
 +
* N
 +
* O
 +
* P
 +
* Q = "Un-walkable"
 +
* R = “Road”, also used for “Rails”
 +
* S = “Swamp”
 +
* T = {{DevFeature1.15|2}} “Toadstool” i.e. fungus
 +
* U = “Underground”
 +
* V = “Village”
 +
* W = “Water”
 +
* X = "Impassable"
 +
* Y = ''Reserved for UMC''
 +
* Z = ''Reserved for UMC''
 +
* _ = "special system stuff"
  
</table>
+
Additional letters do not always follow the same meaning, but are as consistent as possible.
  
==== road ====
+
* \, |, / = for indicating the direction of bridges
 +
* a =
 +
* b =
 +
* c = "city"
 +
* d = "dry or desert, deciduous"
 +
* e = "encampment"
 +
* f = "flowers, fall"
 +
* g
 +
* h = "human"
 +
* i = "ice"
 +
* j
 +
* k
 +
* l = "lava"
 +
* m = "mixed"
 +
* n
 +
* o = "orc"
 +
* p = "pine"
 +
* q
 +
* r
 +
* s = "simple"
 +
* t
 +
* u = "underground"
 +
* v = "elvish"
 +
* w
 +
* x = "chasm"
 +
* y = ''Reserved for UMC''
 +
* z = ''Reserved for UMC''
  
<table border="1"><tr>
+
== Terrain codes in map data ==
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
  
<tr>
+
This is not the Matrix. You normally don't need to look at encoded maps. However, it can be beneficial and useful for more advanced users to understand the usage of terrain strings in raw map file.
<td><i>Rc</i></td>
 
<td></td>
 
<td>Carpeted Floor</td>
 
<td>road</td>
 
</tr>
 
  
<tr>
+
The encoding for maps has a specific format in Wesnoth:
<td>Rd</td>
 
<td>E</td>
 
<td>desert road</td>
 
<td>road, desert</td>
 
</tr>
 
  
<tr>
+
* A map starts with a header with the following keys
<td>Re</td>
+
** '''usage''', this should be 'map' for a map and 'mask' for an overlay mask
<td>r</td>
+
** '''border_size''', the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
<td>dirt road "earth"</td>
+
** {{DevFeature1.13|12}} These keys are now deprecated and will be ignored if present. The blank line mentioned below is not required if these keys are absent.
<td>road, common</td>
+
* Between the header and the data should be 1 empty line
</tr>
+
* A map data file consists of any number of lines, each with the same number of terrain codes.
 
+
* Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
<tr>
+
* When the file is interpreted, each terrain code will be replaced by the terrain it refers to.
<td>Rr</td>
+
* Empty lines are allowed before, after and between lines of characters, between lines is not advised.
<td></td>
+
* Terrains may be prefixed with a number followed by one space, these indicate the starting position for side ''n''.
<td>stone road "rock"</td>
+
** For Wesnoth 1.12.6, ''n'' = 1, 2, 3, ... 9, and the multiplayer server will refuse maps with more than 9 sides.
<td>road</td>
+
** For Wesnoth 1.14, more than 9 sides can work, discussion https://r.wesnoth.org/t48129 and https://r.wesnoth.org/t48082
</tr>
+
* {{DevFeature1.13|12}} In addition to side numbers, terrains may be prefixed by any number of strings (which should consist of alphanumeric characters only, including underscores). All names and side numbers must be delimited by spaces and are separated from the actual terrain code by an additional space.
 
+
** This is broken according to https://r.wesnoth.org/p627595
<tr>
 
<td><i>Rw</i></td>
 
<td></td>
 
<td>Wood floor (interior)</td>
 
<td>road</td>
 
</tr>
 
 
 
</table>
 
 
 
==== swamp ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td><i>Sb</i></td>
 
<td></td>
 
<td>fetid swamp "Swamp Bad"</td>
 
<td>swamp</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Ss</i></td>
 
<td>w</td>
 
<td>swamp</td>
 
<td>swamp</td>
 
</tr>
 
 
 
</table>
 
 
 
==== underground ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Uu</td>
 
<td>u</td>
 
<td>normal cave</td>
 
<td>underground</td>
 
</tr>
 
 
 
<tr>
 
<td>Uui</td>
 
<td>'</td>
 
<td>illuminated cave</td>
 
<td>underground</td>
 
</tr>
 
 
 
<tr>
 
<td>Uf</td>
 
<td>]</td>
 
<td>mushroom grove "underground forest"</td>
 
<td>underground</td>
 
</tr>
 
 
 
<tr>
 
<td>Uh</td>
 
<td>[</td>
 
<td>rockbound cave (functionally "underground hill")</td>
 
<td>underground</td>
 
</tr>
 
 
 
<tr>
 
<td>Uhi</td>
 
<td></td>
 
<td>illuminated rockbound cave (functionally "underground hill")</td>
 
<td>underground</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Uuc</i></td>
 
<td></td>
 
<td>normal cave, carved</td>
 
<td>underground</td>
 
</tr>
 
 
 
 
 
</table>
 
 
 
==== village ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Vda</td>
 
<td>B</td>
 
<td>desert village (adobe)</td>
 
<td>village, desert</td>
 
</tr>
 
 
 
<tr>
 
<td>Vdt</td>
 
<td>U</td>
 
<td>desert village (tent)</td>
 
<td>village, desert</td>
 
</tr>
 
 
 
<tr>
 
<td>Veg</td>
 
<td>t</td>
 
<td>elven village "village elven grassland"</td>
 
<td>village</td>
 
</tr>
 
 
 
<tr>
 
<td>Vea</td>
 
<td>e</td>
 
<td>elven (snow) village</td>
 
<td>village, snow</td>
 
</tr>
 
 
 
<tr>
 
<td>Vha</td>
 
<td>V</td>
 
<td>village, snow            snow village (tundra, village)</td>
 
<td>village, snow</td>
 
</tr>
 
 
 
<tr>
 
<td>Vhg</td>
 
<td>v</td>
 
<td>human village (village)</td>
 
<td>village, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Vhh</td>
 
<td>a</td>
 
<td>human hill village</td>
 
<td>village, hill, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Vhha</td>
 
<td>A</td>
 
<td>human (snow) hill village</td>
 
<td>village, snow, hill</td>
 
</tr>
 
 
 
<tr>
 
<td>Vhm</td>
 
<td>b</td>
 
<td>human mountain village</td>
 
<td>village, mountain</td>
 
</tr>
 
 
 
<tr>
 
<td>Vht</td>
 
<td>L</td>
 
<td>tropical village (savanna, village) --nothing foresty about this village</td>
 
<td>village</td>
 
</tr>
 
 
 
<tr>
 
<td>Vu</td>
 
<td>D</td>
 
<td>underground village (cave, village)</td>
 
<td>village, underground</td>
 
</tr>
 
 
 
<tr>
 
<td>Vud</td>
 
<td>p</td>
 
<td>dwarven village</td>
 
<td>village, underground</td>
 
</tr>
 
 
 
<tr>
 
<td>Vwm</td>
 
<td>Z</td>
 
<td>mermen village (shallow water)</td>
 
<td>village, water</td>
 
</tr>
 
 
 
<tr>
 
<td>Vs</td>
 
<td>Y</td>
 
<td>swamp village (swamp, village)</td>
 
<td>village, swamp</td>
 
</tr>
 
 
 
<tr>
 
<td>Vsm</td>
 
<td></td>
 
<td>swamp merfolk village (swamp)</td>
 
<td>village, swamp</td>
 
</tr>
 
 
 
</table>
 
 
 
==== water ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Wo</td>
 
<td>s</td>
 
<td>deep water "water, ocean"</td>
 
<td>water, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Ww</td>
 
<td>c</td>
 
<td>shallow water, "water, wade-able"</td>
 
<td>water, common</td>
 
</tr>
 
 
 
<tr>
 
<td>Wwf</td>
 
<td>k</td>
 
<td>river ford "water wadeable, ford"</td>
 
<td>water</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Wwu</i></td>
 
<td></td>
 
<td>shallow underground water</td>
 
<td>water, underground</td>
 
</tr>
 
 
 
</table>
 
 
 
==== Impassable ====
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>Xm</td>
 
<td>&</td>
 
<td>impassable moutains</td>
 
<td>impassable, mountain</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Xrw</i></td>
 
<td></td>
 
<td>Impassable stone "rock" wall (interior)</td>
 
<td>impassable</td>
 
</tr>
 
 
 
<tr>
 
<td>Xu</td>
 
<td>W</td>
 
<td>cavewall</td>
 
<td>impassable, underground</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Xuc</i></td>
 
<td></td>
 
<td>cavewall, carved</td>
 
<td>impassable, underground</td>
 
</tr>
 
 
 
<tr>
 
<td><i>Xww</i></td>
 
<td></td>
 
<td>Impassable wooden wall (interior)</td>
 
<td>impassable</td>
 
</tr>
 
 
 
</table>
 
 
 
==== 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.
 
 
 
<table border="1"><tr>
 
<th>String</th>
 
<th>Old letter</th>
 
<th>Description</th>
 
<th>Theme</th>
 
</tr>
 
 
 
<tr>
 
<td>_f</td>
 
<td>~</td>
 
<td>fog</td>
 
<td>misc</td>
 
</tr>
 
 
 
<tr>
 
<td>_s</td>
 
<td> (space character)</td>
 
<td>void/shroud</td>
 
<td>misc</td>
 
</tr>
 
 
 
</table>
 
 
 
== Adding terrains ==
 
When adding terrains make sure the following files are also checked:
 
  
data/faction/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.
+
Since text file tiles are squares while game tiles are hexes, some tiles must be shifted.
 +
Tiles in even-numbered columns are shifted down 1/2 of a tile.
 +
For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:
  
data/abilities.cfg contains the definition of ''submerge'' and ''ambush'' so depending on the change these need to be updated.
+
usage=map
 +
border_size=1
 +
 +
Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
 +
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
 +
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
 +
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re
  
data/utils/utils.cfg containt the macro STARTING_VILLAGES which contains a list of village strings. This list doesn't support wildcards (yet).
 
 
== See Also ==
 
== See Also ==
 
* [[TerrainWML]]
 
* [[TerrainWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
* [http://www.idi.ntnu.no/~haskjold/wesnoth/map_letters.html Freim's List of Terrain Letters]
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Revision as of 12:27, 25 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;

Note: the old (1.2) terrain system is no longer documented here. If you have 1.2 maps you will need to convert them using wmllint.

Terrain strings

The following rules hold for terrain strings. Note most of these rules are not validated since it would slow down Wesnoth; not following these rules might break Wesnoth.

  • terrain strings are composed from one or more terrain codes of 2 to 4 characters each, separated by ^.
  • terrain codes start with a capital letter and the following letters are lower case
  • terrain strings can only contain letters, the symbols /|\ which are meant for directional items like bridges and the symbol ^
  • the underscore is used as a leader for internal terrain codes
  • the star '*' can be used for wildcards in some places where a terrain code is required
  • the symbol ^ indicates that a terrain is created with layers, for example Gs^Fp means Semi-dry Grass(Gs) with a Forest(Fp) overlay.

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.

Terrain Table

The list of terrains can be found at TerrainCodeTableWML. Since most overlays can be combined with most bases the list is not complete.

Adding terrains

When adding terrains make sure the following files are also checked:

data/multiplayer/factions/* contains favorite positions for the different factions, this is only used for the random map generator at the moment so it is not very important.

data/core/macros/abilities.cfg contains the definition of submerge and ambush so depending on the change these need to be updated.

Decoding the Terrain Codes

The initial letters of each terrain code have a standard meaning, though some are not obvious.

  • A = “Arctic” i.e. frozen
  • B = “Bridge”
  • C = “Castle”
  • D = “Desert”
  • E = "Embellishment"
  • F = “Forest”
  • G = “Grass” i.e. flat
  • H = “Hills”
  • I = "Interior" (possible future use)
  • J = testing
  • K = “Keep”
  • L
  • M = “Mountains”
  • N
  • O
  • P
  • Q = "Un-walkable"
  • R = “Road”, also used for “Rails”
  • S = “Swamp”
  • T = (Version 1.15.2 and later only) “Toadstool” i.e. fungus
  • U = “Underground”
  • V = “Village”
  • W = “Water”
  • X = "Impassable"
  • Y = Reserved for UMC
  • Z = Reserved for UMC
  • _ = "special system stuff"

Additional letters do not always follow the same meaning, but are as consistent as possible.

  • \, |, / = for indicating the direction of bridges
  • a =
  • b =
  • c = "city"
  • d = "dry or desert, deciduous"
  • e = "encampment"
  • f = "flowers, fall"
  • g
  • h = "human"
  • i = "ice"
  • j
  • k
  • l = "lava"
  • m = "mixed"
  • n
  • o = "orc"
  • p = "pine"
  • q
  • r
  • s = "simple"
  • t
  • u = "underground"
  • v = "elvish"
  • w
  • x = "chasm"
  • y = Reserved for UMC
  • z = Reserved for UMC

Terrain codes in map data

This is not the Matrix. You normally don't need to look at encoded maps. However, it can be beneficial and useful for more advanced users to understand the usage of terrain strings in raw map file.

The encoding for maps has a specific format in Wesnoth:

  • A map starts with a header with the following keys
    • usage, this should be 'map' for a map and 'mask' for an overlay mask
    • border_size, the size of the border, should be 1 for map and 0 for mask. When the border_size is 1 the map border is part of the map data, this means the user can define the border instead of the game taking a guess.
    • (Version 1.13.12 and later only) These keys are now deprecated and will be ignored if present. The blank line mentioned below is not required if these keys are absent.
  • Between the header and the data should be 1 empty line
  • A map data file consists of any number of lines, each with the same number of terrain codes.
  • Each string may be padded with spaces or tabs and must be separated with a comma, except for the last string on a line this one may not have a comma.
  • When the file is interpreted, each terrain code will be replaced by the terrain it refers to.
  • Empty lines are allowed before, after and between lines of characters, between lines is not advised.
  • Terrains may be prefixed with a number followed by one space, these indicate the starting position for side n.
  • (Version 1.13.12 and later only) In addition to side numbers, terrains may be prefixed by any number of strings (which should consist of alphanumeric characters only, including underscores). All names and side numbers must be delimited by spaces and are separated from the actual terrain code by an additional space.

Since text file tiles are squares while game tiles are hexes, some tiles must be shifted. Tiles in even-numbered columns are shifted down 1/2 of a tile. For example, to have a road of connected dirt ('Re') tiles, the map data would look like this:

usage=map
border_size=1

Re, Re, Gg, Gg, Gg, Gg, Gg, Gg
Gg, Gg, Re, Re, Gg, Gg, Gg, Gg
Gg, Gg, Gg, Gg, Re, Re, Gg, Gg
Gg, Gg, Gg, Gg, Gg, Gg, Re, Re

See Also