TerrainGraphicsReference

Rule structure synopsis

 +--------------------------+
 | Rule                     |
 |  +--------------------+  |
 |  | Constraint         |  |
 |  |                    |  |
 |  | * offset           |  |
 |  | * typestring       |  |
 |  | * has_flags        |  |
 |  | * set_flags        |  |
 |  | * no_flags         |  |
 |  |                    |  |
 |  |  +--------------+  |  |
 |  |  | Image        |  |  |
 |  |  +--------------+  |  |
 |  |  | Image        |  |  |
 |  |  | ...          |  |  |
 |  |  +--------------+  |  |
 |  +--------------------+  |
 |  | Constraint         |  |
 |  | ...                |  |
 |  +--------------------+  |
 |                          |
 | * position               |
 | * probability            |
 | * precedence             |
 |                          |
 |  +--------------+        | 
 |  | Image        |        |
 |  +--------------+        |
 |  | Image        |        |
 |  | ...          |        |
 |  +--------------+        |
 +--------------------------+

Rule matching algorithm

Each rule will be tested against each hex of the map. For a rule to match on a given hex (let name this hex H), the following conditions have to be met:

Some random, 1 to 100 number must be inferior to the rule "probability"
If the rule has a position set, it may only match on this very location.
All constraints of the rule must match.

For a constraint of the rule to match, the following conditions have to be met:

The hex corresponding to this constraint must have a type which matches the constraint's typestring:
- We define the "hex corresponding to this constraint" as the hex, on the map, whose location is the hex H + ofs, ofs being the offset of the constraint.
- The hex matches the constraint's typestring if any of those is true:
  - The typestring contains the metacharacter "*".
  - The typestring does not start with the character "!", and the hex's terrain character is included in the typestring.
  - The typestring starts with the character "!", and the hex's terrain character is *not* included in the typestring.
The hex corresponding to this constraint must not have any flag in the constraint's "no_flag" list.
The hex corresponding to this contraint must have all the flags present in the constraint's "has_flag" list.

WML Reference

[terrain_graphics]

The [terrain_graphics] tag represents a terrain graphics rule. It may contain the following child tags:

[image]: when an image is defined in a [terrain_graphics] tag, it defines a multi-hex image which will be applied over all tiles of the rule.
[tile]: adds one (or several) constraints to the rule.

Additionally, the [terrain_graphics] tag may have the following elements:

x and y: format: <number>
Specifies the coordinates at which this rule can match. A rule which has x-y coordinates may only match at this position in the map, and nowhere else.
probability: format: <number>
A number from 0 to 100. Means that this rule will only match, when all other conditions are met, if a random number from 0 to 100 is inferior to the probability value. Obviously, 0 means this rule will never match, and 100 means this rule will always match if all other conditions are met.
precedence: format: <number>
An optional tag which allows to specify in which order rules are to be tested. Generally, rules are tested in the order they are defined. However, rules with a lower precedence will always de tested before rules with higher precedence.
map: format: see below
A string, generally a multi-line one, graphically representing the constraints of this rule. Maps are a shorthand notation to defining several constraints using the [tile] element. Those have a special structure; see below (`Map Format`).
set_flag: Defining a set_flag element in a rule is identical to defining it on each constraint of this rule.
has_flag: Defining a has_flag element in a rule is identical to defining it on each constraint of this rule.
no_flag: Defining a no_flag element in a rule is identical to defining it on each constraint of this rule.
rotations: format: <r0>,<r1>,<r2>,<r3>,<r4>,<r5>
r0 to r5 being (usually short) strings.
Specifies that this [terrain_graphics] element does not define an actual rule, but will serve as a template for creating up to 6 rotated rules.
Template rules are defined like normal rules, except that flags and image filenames may contain template strings of the form @Rn, n being a number from 0 to 5.
A template rule will generate 6 rules, which are similar to the template, except that:

The map of constraints of this rule will be rotated by an angle, of 0 to 5 pi / 6 On the rule which is rotated to 0rad, the template strings @R0, @R1, @R2, @R3, @R4, @R5, will be replaced by the corresponding r0, r1, r2, r3, r4, r5 variables given in the rotations= element. On the rule which is rotated to pi/3 rad, the template strings @R0, @R1, @R2 etc. will be replaced by the corresponding r1, r2, r3, r4, r5, r0 (note the shift in indices). On the rule rotated 2pi/3, those will be replaced by r2, r3, r4, r5, r0, r1 and so on.

[tile]

The [tile] element, in a [terrain_graphics] rule, adds one (or more) new constraints to a rule. It may contain the following child tags:

[image]: Defining an [image] element inside of a [tile] element will define a single-hex image which will only be applied to the tile the constraint applies to.

Additionally, the [tile] tag may contain the following elements:

x and y: format: <number>
Specify the offset of the constraint.
loc: format: <number>, <number>
An alternative notation for specifying the offset of the constraint.
pos: format: <number>
Specifies that this [tile] tag does not define a single constraint, but instead, acts as a template for all constraints defined, on the map, with an anchor of the same number (See `Map format`_.)
Only meaningful if the [terrain_graphics] parent tag contains a map element.
type: format: <string>
Defines the typestring for this constraint. This value represents a list of characters. For the constraint to match, the corresponding terrain tile's type must be one of those characters.
This string may contain the metacharacter "*" meaning "all terrains", and the metacharacter "!", meaning "all terrains except those present in the list."
set_flag: format: <flag> [ "," <flag> ] +
Specifies that, if the rule which contains this constraint matches, the given flags will be applied to the corresponding terrain tile.
has_flag: format: <flag> [ "," <flag> ] +
Specifies that this constraint will only match if the corresponding terrain tile already has all the given flags.
no_flag: format: <flag> [ "," <flag> ] +
Specifies that this constraint will only match if the corresponding terrain tile does *not* have any of the given flags.

[image]

The [image] element, in the [terrain_graphics] element, or in a [tile] elements, specify an image which will be added on the terrain, if the corresponding rule does match.

It may contain the following child tags:

[variant]: A time-of-day specific variant of the image.

Images may contain the following elements:

name: format: <timed_image> [ "," <timed_image> ] +
<timed_image> = <image_name> [ ":" <timing> ]
If the name only contains one timed_image, it will be used as a base to build the filename of the image corresponding to this [image] tag, with "images/terrain/" prepended, and ".png" appended.
If the name contains several timed_images, it will correspond to an animated image, each timed_image being a frame of the animation. For each frame of the animation the <image_name> part corresponds to the base of the filename, which will be built as shown above, and the <timing> part will correspond to the duration, in milliseconds, of this frame.
position: format: "horizontal" | "vertical"
The type of layering this image will use. If set to "horizontal", it will use a layer-based stack model. If set to vertical, images will be assumed to have an (x,y) position on the screen, and will be layered according to their coordinates.
layer: format: <number>
Only meaningful if the position tag was set to horizontal. Images with an horizontal position will be drawn, lower layer to upper layer, without taking their position into account.
base: format: <number> "," <number>
Only meaningful if the position tag was set to vertical. Specifies the coordinates of the "base" of the image, which is, the imaginary pixel at which the image reaches the "floor", relative either to the top-left corner of the rule, or to the top-left corner of the constraint hex, depending on whether the image applies to a rule, or to a constraint.

[variant]

[variant] tags represent a time-of-day-specific version of an image. Variants may contain the following elements:

tod: format: <string>
The identifier of the time-of-day this variant applies to. When the turn's top is equal to this, the "name" element of this variant will replace the "name" element of the parent image.
name: format: <timed_image> [ "," <timed_image> ] +
<timed_image> = <image_name> [ ":" <timing> ]
The image string, which will replace the "name" element of the parent image on the right time-of-day.