Custom Terrain Tutorial planning

[Alarantalara]

Judging by its use of single-letter terrain strings (multi-letter strings appeared in 1.3.x after mordante’s branch was merged in trunk), and that Ayin’s forum account was last used the day before the 1.0.2 release was tagged, it must have been written for 1.0 and earlier rather than 1.4.

You're absolutely correct: I was thinking of the slightly updated version on the wiki which updated the terrain strings and map format. I've corrected the reference.

Edit: And the reference is now removed entirely since the link is now dead.

[Alarantalara]

Last time, image tags looked like this:

Code: Select all

[image]
    name=myterrainimage.png # image in tile
[/image]

The name key supports much more than just a filename, however, and there are many more keys that affect the appearance of the image.

The bounding box
Images are drawn relative to a bounding box. The bounding box is the smallest rectangle that surrounds the area that the image may apply to. For an [image] contained inside a [tile], the bounding box is the 72x72 pixel box that contains the hex associated with that tile. For the multi-hex [image] tag that is directly within the [terrain_graphics] tag, this box is the smallest rectangle that includes the hex at relative location <0,0>, the hex with the greatest x value and the hex with the greatest y value for a location.

The name key
The name key determines which images are drawn and for how long they are drawn. As such the name key is actually a comma separated list of file paths with durations attached to them using colons. The full form looks like filename1.png:duration1,filename2.png:duration2,...
Durations are measured in milliseconds.
For instance, this is the name key for the animated brazier in core:

Code: Select all

name="../scenery/fire1.png:140,../scenery/fire2.png:140,
../scenery/fire3.png:140,../scenery/fire4.png:140,
../scenery/fire5.png:140,../scenery/fire6.png:140,
../scenery/fire7.png:140,../scenery/fire8.png:140"

Note that using quotes allows you to split extremely long values for the key across multiple lines, which can be very useful.

The name key supports all image path functions in the file path: ImagePathFunctionWML, but because of a bug in how they are applied to terrains, any that involve locations in an image (FL, CROP, BLIT, SCALE) have interesting results in versions of Wesnoth prior to 1.9.8. The others all work fine, and recolouring and palette switches are useful.

Here is an example from an unreleased campaign that uses a palette swap to create a pulsing image:

Code: Select all

[image]
    layer=-1
    name="circle.png,
          circle.png~PAL(981E0F>791609),
          circle.png~PAL(981E0F>5E1D14),
          circle.png~PAL(981E0F>823D33),
          circle.png~PAL(981E0F>CD7469),
          circle.png~PAL(981E0F>F4614E),
          circle.png~PAL(981E0F>DB2C15)"
[/image]

Note that the duration is unspecified as there are no colons in the name. When the duration is unspecified, it is assigned the value of 100 by default.

Image layering
The order images are drawn on the map is determined, in order of decreasing importance, by the layer key, the base key, the order of the images in the [terrain_graphics] tag, and the order of the [terrain_graphics] tags.

The layer key has the greatest effect on the order an image is drawn. It has an integer value between -1000 and 1000, with images at layer -1000 drawn first and those at 1000 drawn last. Images at layer 1 and higher are drawn in front of all units, while images at layer -1 and lower are drawn behind all units. For images at layer 0, the base key must be consulted to determine when they are drawn relative to units. If you don't specify a layer, the game assigns a layer of 0.

The base key is used to break ties if the layers are the same. It has a value of two integers separated by commas to represent a location on the map measured in pixels. <0,0> is the top-left corner of the bounding box. The first (x) value has no effect unless the tile has rotations (covered in a later tutorial). The second value, representing y, does have an effect. Like with layers, images with higher y values are drawn in front of images with lower y values. Units are have a y value of 54 for determining whether they are drawn in front of or behind terrain. If no base is specified, then the base is considered to be <36,36>.

For an [image] within a [tile] tag, this completely describes whether a unit will appear in front of or behind a terrain image. However, for images placed directly in the [terrain_graphics] tag, which may appear in multiple hexes, this becomes more complicated. These images are broken up into a separate image for each hex, with the y value recalculated to be relative to each hex. This is equivalent to drawing a horizontal line across the image and then splitting the hexes so that the image is drawn in front of units for which the line is below 54 pixels from the top of the hex and behind units for which the line is on or above it.

For a base set by the yellow line: dark hexes will be drawn behind a unit, light hexes in front

base_layering.jpg (8.11 KiB) Viewed 7671 times

Because of this absolute nature of in front/behind, units that extend outside of a single hex can often appear less than correct when drawn with multi-hex images that care about unit location. While this effect is most noticeable with the Fire Dragon, there are other, more common, examples, such as the Direwolf Rider, that also extend outside hex boundaries.

The fire dragon shows how extending outside a hex can cause problems with the binary in front/behind nature of terrain image pieces

unit_and_base.png (37.06 KiB) Viewed 7684 times

In addition, multi-hex images for which no base is specified are placed at <36,36> on every tile, which means they will appear in front of some pieces of multi-hex images and behind others if they are in the same layer. You can see an example of this effect in To Lands Unknown's Bridge of Light scenario.

The fog has no base, making the mountains appear above it on some hexes

multihex_overlap.png (54.2 KiB) Viewed 7684 times

Finally, if the layer and base both have the same values, the images are drawn in the order they appear in the file. Images from top-level [terrain_graphics] tags in add-ons are drawn before images from the core [terrain_graphics], which are drawn before [terrain_graphics] tags contained within a [scenario] tag.

If everything is being drawn by the same rule, then the type of the terrain, and the location of the tile on the map are used as final tie breakers. This will only matter if you use very large images in one rule that applies in many places and two of those places have the same y-coordinate. Usually, the images will be drawn so that images further to the right are drawn above those to the left, but exceptions can occur if the underlying terrain is different.

Image placement
While layering controls the order in which images are drawn, the center tag may be used to control where the image is drawn in multihex images. If a center is not specified, then the image is drawn so that its top-left corner is the top-left corner of the bounding box. If center is specified, then the image is drawn so that its center is located at the specified point. As with base, <0,0> is the top-left corner of the bounding box. Also, like base, the value for center must be a pair of integers separated by a comma.
Single hex images (those within a [tile] tag) do not accept the center attribute. Instead they assume that the image is exactly 72x72 pixels and place it in the top right corner of the hex. Since it is not possible to draw in other hexes with these images, manually locating the image in a 72x72 pixel canvas will always correctly place it in this case.

Animation control
In 1.8, all animations are synchronized so that they all start at the same time. In 1.9, animations start at a random time. In some cases, synchronization may be useful, in which case the random_start key can be set to "no", to force the animation to begin at the start.

Variants
In some cases, it may make sense to have the appearance of the terrain change depending on the time of day (e.g. to turn on lights in a building). For this, the [variant] tag within an image may be used. It repeats the name and random_start_time keys from the main image, and adds a new required key: tod. In 1.9 this allows a list of times of day, while a separate variant tag must be used for each time of day in 1.8. If a [variant] is present, then the name key contained directly inside the [image] will be used only when one of the variants does not match. No mainline terrains currently use this feature.

The following ids are the standard times of day in core: dawn, morning, afternoon, dusk, first_watch, second_watch, indoors, underground, deep_underground. Illuminated times (underground_illum, etc.), while present in 1.8 and 1.9 WML prior to 1.9.10, do not generate in game times and so will never be matched in a variant. In 1.9, a 24 hour schedule has been added; see macros/schedule.cfg for the time of day ids.

For fun, here is the image part of the code for a village that appears destroyed during the night, along the lines of the transforming army in Liberty. Layering and positioning are left out for clarity.

Code: Select all

[image]
	name=village/human.png
	[variant]
		tod=dusk,first_watch,second_watch
		name=village/human-cottage-ruin.png
	[/variant]
[/image]

[Alarantalara]

While specifying relative x and y coordinates for each hex in a terrain image is not difficult, it can generate excessively large tags and require a lot of copy/paste work when many hexes use the same tile rules. To solve this problem, there is a second method for specifying tiles: the map key.

The map key allows the creation of a physical map to represent the relative locations of types of tiles. Each tile type is represented by a number and then these numbers are used instead of x and y locations to locate the tiles.

Here is one of the waterfall tags from before converted to use numbers instead.

Original:

Code: Select all

[terrain_graphics]
    [tile]
        x=0
        y=0
    [/tile]
    [tile]
        x=0
        y=1
        type=Wwy,Woy
    [/tile]
    [tile]
        x=1
        y=0
        type=Q*
    [/tile]
    [tile]
        x=1
        y=1
        type=Qxu
        no_flag=waterfall-nw
    [/tile]
    [tile]
        x=0
        y=2
        type=Q*
    [/tile]
    [image]
        name=water/waterfall-nw-n-sw.png
    [/image]
[/terrain_graphics]

Code: Select all

[terrain_graphics]
    map="
*
, 2
1
, 3
2"
    [tile]
        pos=1
        type=Wwy,Woy
    [/tile]
    [tile]
        pos=2
        type=Q*
    [/tile]
    [tile]
        pos=3
        type=Qxu
        no_flag=waterfall-nw
    [/tile]
    [image]
        name=water/waterfall-nw-n-sw.png
    [/image]
[/terrain_graphics]

There are several things worth noting here.
1) The map tag covers multiple lines. As such, it must be quoted.
2) Each tile type is separated by a comma or a new line. Spaces may be used for readability.
3) * is a special code used to represent the common case that any terrain will match. It is equivalent to the tile tag that contains nothing but a location so that a multi-hex image will be drawn on it. As such, you should only use if you are also using a multi-hex image.
4) the pos key is used instead of the x and y keys. It provides a link between the map and the [tile].
5) A tile type may appear more than once in the map if it behaves the same way in all places. As with *, this helps avoid the need for large amounts of copying.
6) If you take the time to find the correspondence between the original and modified version, you will note that the map looks somewhat like a picture of the the hexes as seen in game.

This last point needs elaboration, as correctly arranging the values in the map is the most difficult part of the tag.

The map grid
Warning: the map here is not in the same format as the one used for the game maps despite some superficial similarities. If you are used to editing terrain maps and masks by hand, forget your knowledge of their layout when using this tag.

Each line in the terrain tag corresponds to a set of hexes that share the same vertical center. This means that for a given y value on a hex map, there are two lines in the [terrain_graphics] map. To help you identify them, you are allowed to put empty values as the first position of alternate lines. Blanks are not allowed anywhere else.

The map from the waterfall tag above thus looks like this on a hex map:

waterfall.png (55.45 KiB) Viewed 7654 times

The top left corner of this image also shows the point at which the [image] tag's top left corner lies.

Note This is not complete, but I thought I should put up what I have to make sure I don't forget about it.

[Theolain]

I seem to be a bit stupid....or at least inexperienced in knowing now to make these things work....no matter what i try i cant seem to make my own overlay.... I can get the code working for your example but i cant work out how to get it to use my own image....which is in add-ons\Test_Campaign\images\terrain

I have the code in my _main.cfg file... I think im missing somthing really obvious that has probably already been explained (tell me or move it if i should have posted in my own thread of stupid questions)

[Alarantalara]

I seem to be a bit stupid....or at least inexperienced in knowing now to make these things work....no matter what i try i cant seem to make my own overlay.... I can get the code working for your example but i cant work out how to get it to use my own image....which is in add-ons\Test_Campaign\images\terrain

I have the code in my _main.cfg file... I think im missing somthing really obvious that has probably already been explained (tell me or move it if i should have posted in my own thread of stupid questions)

Read the two notes after the first block of code in the first post (especially the one concerning binary paths). If they don't resolve your problem, send me a PM. We'll work it out there and I'll edit in the needed details into this thread.

[Simons Mith]

I've only skimmed this thread, so sorry if I missed it, but I would like to make a minor request.

As part of this tutorial, please cross-refer users to the /art/ information related to drawing terrain. That is:

position of light source
angle of view
perspective used
building scale
/item/ scale (e.g. for non-building terrain embellishments like archery targets, crates, barrels etc., insofar as this information is available)
colour restraints/palette restrictions (e.g. water palettes)
dominant wind direction (affects smoke, flags etc.)
water flow direction (all seems to be non-directional at present)
lighting and contrast issues (e.g. 'colour assuming the following light levels, and then let the game adjust the lighting accordingly if the terrain is used in caves')

I'm sure I've seen all that material specifically mentioned (except possibly wind and water) in posts by senior artists. Some's here, http://forums.wesnoth.org/viewtopic.php?f=9&t=30393 (Terrain Info & Links -- your one-stop sticky), but I'm sure there's more, and I don't remember the threads well enough to search for them.

[lvjtn]

hi guys,

i'm not a regular wesnoth player, just discovered the possibilities of the map editor. i want to use the map editor to create ww2 maps for open general (descendant of panzer general ii). though this turn-based strategy game uses 60x50 hexes, 72x72 tiles used for wesnoth can be good enough

i've made some progress and could create a few nice seamless tiles for flat, water, snow terrain types, and gradiant transparency works also well between these terrains, all possible 31 transitions are extremly useful!

https://sites.google.com/site/lvjtn9/we ... x31-tr.jpg (831x679 px)

now i'm working on overlay facilities. e.g. airfield instead of water lillies:

https://sites.google.com/site/lvjtn9/snow-af.jpg

unfortunatelly i haven't found any good explanation for different transition / overlay types, so i followed the good old "try and error" method and modified the terrain.cfg and terrain-graphics.cfg by fits and starts

ok, sorry for the long story, my real question is this: can i find a good description / manual anywhere to learn the differences between the similar macros used the aforementioned config files? or a user guide which explans how can i create a hierarchy of overlays (e.g. city over forest and railway, but airfiled over the city) and exclusions (e.g. 110x110 airfield can't overlap a mountain)

[Alarantalara]

ok, sorry for the long story, my real question is this: can i find a good description / manual anywhere to learn the differences between the similar macros used the aforementioned config files?

This thread likely comes the closest to what you want, though it doesn't cover all the macros. To a certain extent, this is a good thing. Apart from the base, overlay and transition macros, most of what remains is very specific to individual terrains, so less than generally useful.
This specific post covers most of the variations on the macros: http://forum.wesnoth.org/viewtopic.php? ... 01#p493881

or a user guide which explans how can i create a hierarchy of overlays (e.g. city over forest and railway, but airfiled over the city) and exclusions (e.g. 110x110 airfield can't overlap a mountain)

Just define them in the order from most specific to least specific. The macros set flags that prevent later ones from acting, so if you define terrain graphics with probability and state that it can't be placed over mountains, then it that's exactly what will happen. See the section on terrain matching here: http://forum.wesnoth.org/viewtopic.php? ... 01#p495299
Do note that if you need to limit images based on adjacent terrain, you are limited to either the somewhat restrictive NEW:FOREST macro, or writing your own [terrain_graphics] tag.

[lvjtn]

thank you, Alarantalara! you helped a lot

i saw initial "O" is not used, so i defined all terrains with a starting "O" (referring to "open general"), e.g. "polish grassland" = "Ogp", "eastern european snowed city" = "^Ocsw", etc. and put all graphics into a new folder: og_flat, og_facility, og_town, etc. so i overwroty only "/usr/share/games/wesnoth/1.10/data/core/terrain.cfg" and "/usr/share/games/wesnoth/1.10/data/core/terrain-graphics.cfg"

is it possible to create a completely new, alternate terrain.cfg and terrain-graphics.cfg in some $user folder and disable original terrains in map editor at the same time? i don't want to wesnoth-style tiles with open general-style tiles

and when i'll finish my project, can it be interested for wesnoth players? i create tiles from user made maps, there's no copyright issue

[Alarantalara]

is it possible to create a completely new, alternate terrain.cfg and terrain-graphics.cfg in some $user folder and disable original terrains in map editor at the same time? i don't want to wesnoth-style tiles with open general-style tiles

New terrain.cfg and terrain-graphics.cfg files can easily be created (and they don't even need those names). Disabling the original terrains is not possible—they are currently set up to be always present. You can and should place all the new terrain in a separate editor group, which will help show that these terrains are related and should be used together.

and when i'll finish my project, can it be interested for wesnoth players? i create tiles from user made maps, there's no copyright issue

Wesnoth players will be interested if units can interact properly with the map. This may be an issue for you as there are several assumptions about abilities and movement in the game. For instance, all terrains must alias themselves to one of the base terrains mentioned in this thread or units will be unable to move. Similarly, currently all forests must be overlays and start with F for ambush to work, "villages" must be overlays starting with V for concealment, places that grant income must be marked as villages (not necessarily the same as the villages for concealment), etc.

[doofus-01]

Not sure if I should be asking questions here, but I have a terrain-graphics issue, and it is related to the image layering mentioned several posts up.

Spoiler:

I'd like lower (southern) towers to be layered higher than towers at a more northern coordinate. Sometimes this is straightforward, but when the images are being placed by the same rule, the layering is difficult to understand. In the images below, towers are flagged as either "front", "left", or "right". The little cluster in the lower right corner of the images is one "front" and three "right" towers. So the "right" towers are all drawn from the same rules - is there any way to avoid the obvious glitches?

I thought maybe the "base" key would have something to do with it, and it does change things, but not in a way I understand. The actual values of base=<x,y> don't seem to matter, it only matters if it is specified at all or not.

base not specified

base=0,0

I think this is the relevant WML for the right towers

Code: Select all

[terrain_graphics]
    map="
*,* 
,*,*
*,1 
,*,*
*,*"
    [tile]
        pos=1
        type=Tphz
        has_flag=sand_tower_middle_right
        set_no_flag=sand_tower_middle_right_drawn
    [/tile]
    probability=100
    [image]
        name=sand_tower/tower-middle.png # this is a 288X288px image, though mostly empty
        center=140,144
        base=0,0
        layer=-65
    [/image]
[/terrain_graphics]

The whole thing can be found in the add-on "Trinity" at wesnoth-umc-dev.svn.sourceforge.net.

[doofus-01]

Well, I found a hack way to get around this: Just put another image over the parts that conflict. It doesn't require any changes in how flags are set, but it is very similar to just chopping the tower image up further so there is less overlap, which is what I had hoped to avoid. But at least this is just two extra images.

[tekelili]

Nice tutorial, I learned some usefull stuff

I have noticed a "typo" you could want to fix: Alias string of village is indicated as "Vi" instead correct "Vt" here

[Alarantalara]

Out of date again.

It was correct at the time of writing, but as of 1.11.7, all of the base terrains were changed to be *t and Vit became Vt in 1.11.9. I've updated the relevant section.

[tekelili]

I am having troubles to define a terrain image with heavy image path funtion use. I have images defined as macros that work perfectly with [item] but display incomplete and displaced elements, blit in image path function.

Code: Select all

#define IMG_SUPPLY_0
"misc/blank-hex.png~BLIT(items/straw-bale2.png~CROP(24,15,48,57))~BLIT(items/straw-bale1.png~CROP(0,9,72,63))" #enddef

[terrain_type]
    symbol_image=../{IMG_SUPPLY_0}
    editor_name= _"Supply"+" a"
    editor_group=supply_villages
    id=supply_village_a
    string=^Vxsa
    aliasof=_bas, Vt
    heals=8
    gives_income=true
[/terrain_type]
{OVERLAY *^Vxsa (../{IMG_SUPPLY_0})}

I am doing something wrong, image path function is not supported in [terrain_type], or is a bug I should report?