TerrainMacrosWML

Template:DevFeature1.9 This page is entirely base on the 1.9 macros, they are very close to the 1.8 macros, but no attempt has been done to document the difference

1 Flag Management
2 Layer Management
3 Precedence Management
4 Base Management
5 Macro naming convention
6 The TEST_COMPLETE macro
7 Image Builder macros
8 Base tile related macros
9 Overlay related macros
10 Keep related macros
11 Village related macros
12 Transition related macros
- 12.1 TRANSITION_BASE TERRAIN ADJACENT P=PROB=100 L=LAYER=-500 F=FLAG=transition B=BUILDER=IMAGE_SINGLE IMAGESTEM
- 12.2 DISABLE_BASE_TRANSITIONS TERRAINLIST
13 Terrain Specific
- 13.1 SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM
14 TO BE DOCUMENTED

Flag Management

This section lists the common flags used by macros and their high level signification

base: is set on all hex when the base tile is set.
overlay: is set on all hex that have something drawn on the hex itself (i.e not a transition) over the base terrain.
village: is set when a village is added on a tile.
transition-@R*: is set on a tile which has a transition on it's corresponding side set (i.e if there is a transition with the tile at its north, transition-n will be set) possible values: n,ne,nw,s,se,sw Also not that the macros handl it in a reciprocal way. in other word if a tile has transition-n set, it's northern neighbour should have transition-s set
angle_@R* : used for bridges, the bridge on this tile. The bridge has an "exit direction" in the @R direction indicated.
angleaway_@R* : used for bridges, the bridge does NOT have an exit on the given direction

Layer Management

-1000: default layer for base tiles
-80: overlays that should always be drawn under units (like rails etc...)
0: default layer for overlays and villages

Normal units are drawn above layer 0, except if the basey of the tile is > 56 in which case they are drawn below

1: used by the base tile of castles/keeps

Flying/moving units are always drawn over terrain

Precedence Management

TBSL

Base Management

TBSL

Macro naming convention

for some common types of tiles, we have a lot of variation of macros. To simplify, they follow a naming convention

Macro names

Type is the type of macros (like KEEP,OVERLAY etc...) we are using

TYPE_PLFB : puts an image on a tile
TYPE_RANDOM_LFB : puts an image from a random set on a tile
TYPE_RESTRICTED[23]_PLFB: puts an image on a tile if the tile has one [two or three] neighbours of a given type
TYPE_RESTRICTED[23]_RANDOM_PLFB: combination of above
TYPE_ROTATION_RESTRICTED[23]_PLFB: combination of above + the images will be named according to where the neighbours are
TYPE_ROTATION_RESTRICTED[23]_RANDOM_PLFB: combination of above

here _PLFB means any combination of _P _PL _PF etc... will also be correct macro names with the corresponding parameters

each section describing a type will explain what values for PLFB are used for the functions that don't have them as parameters

Macro Parameters

These macros always have the parameters in the same orders (not all macros have all parameters, see below

TERRAIN ADJACENT PROB LAYER FLAG BUILDER IMAGESTEM

TERRAIN : the type of terrain to put the image on
ADJACENT : only for restricted the type of neighbours to test for
PROB : only for _P The probability of the rules generated by the macros of being applied. See the discussion in TerrainGraphicsTutorial#Cumulative_Probabilities for complications
LAYER : only for _L The layer that will be used for the generated rules
FLAG : only for _F A flag to test and set on the tile
BUILDER : only for _B the builder macro that will be used to create the animations in the image= field of the generated terrain code. See the dicussion at the begining of the builder section
IMAGESTEM: the basename on which filenames will be based.

Image Names

_RANDOM_
- {{BUILDER} {IMAGESTEM} ()}
- {{BUILDER} {IMAGESTEM}2 ()}
- {{BUILDER} {IMAGESTEM}3 ()}
- etc up to 11
_ROTATION_
- 1 : {{BUILDER} {IMAGESTEM} (-@R0)} with @R0 being the orientation of the neighbouring tile
- 2 : {{BUILDER} {IMAGESTEM} (-@R0-@R1)} with @R0 and @R1 being the orientations of the neighbouring tiles
- 3 : {{BUILDER} {IMAGESTEM} (-@R0-@R1-@R2)} with @R0, @R1 and @R2 being the orientations of the neighbouring tiles
_RANDOM_ + _ROTATION_
- {{BUILDER} {IMAGESTEM}# (-@R#)} similar to above with all combinations

The TEST_COMPLETE macro

there is one more macro which exist for most families of macro

#define TYPE_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
   {TYPE_ROTATION_RESTRICTED3_RANDOM_LFB  ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1-@R2)}
   {TYPE_ROTATION_RESTRICTED2_RANDOM_LFB  ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0-@R1)}
   {TYPE_ROTATION_RESTRICTED_RANDOM_LFB   ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small (-@R0)}
   {TYPE_RESTRICTED_RANDOM_LFB            ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}-small ()}
   {TYPE_SINGLE_RANDOM_LFB                ({TERRAIN})               {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

This macro is a simpler way of handling the most common case of "use a smaller variation when next to some terrains"

If it has three neighbours, it will try IMAGESTEM-small#-R1-R2-R3
if it has two neighbour or the correct image wasn't found, it will try two-sided variations
if it has one neighbour or the correct image wasn't found, it will try one sided variations
if it has still not found anything, it will try IMAGESTEM-small
if it has no neighbour or still hasn't found anything, it will try based on IMAGESTEM

Image Builder macros

The problem

suppose we want to animate a transition with the following line

image=image1;image2;image3

Since it's a transition, we would like to write something like (simplified)

{TRANSITION_BASE <parameters> image1;image2;image3}

However, for a north transition, the macro would expand to something similar to

image=image1;image2;image3-n

Which is wrong, we want the prefix added to all images in the animation

image=image1-n;image2-n;image3-n

To get the result we want, we use macro indirection. In other word, we have a set of macros who take two parameters

#define BUILDER IMAGESTEM POSTFIX

Which are in charge of returning what should be on the right side of the image= So, with the following macro

#define MY_BUILDER IMAGESTEM POSTFIX
{IMAGESTEM}1{POSTFIX};{IMAGESTEM}2{POSTFIX};{IMAGESTEM}3{POSTFIX};

and the following code in the TRANSITION_BASE macro

image={{BUILDER} {IMAGESTEM} -n}

a call to

{TRANSITION_BASE_B <parameters> MY_BUILDER image}

would correctly expand.

Common parameters for all builders

All builders must have exactly the same parameters

IMAGESTEM : the base name of the image from which to build
POSTFIX : a postfix to add to all images

IMAGE_SINGLE IMAGESTEM POSTFIX

builds a single image image= line (i.e not animated) mainly used as default value for BUILDER parameter of meta-macros

ANIMATION_03 IMAGESTEM POSTFIX

builds a Three image animation, each image being displayed for 100 ms Images Used

IMAGESTEM-A01
IMAGESTEM-A02
IMAGESTEM-A03

ANIMATION_04 IMAGESTEM POSTFIX

builds a four image animation, each image being displayed for 100 ms Images Used

IMAGESTEM-A01
IMAGESTEM-A02
IMAGESTEM-A03
IMAGESTEM-A04

ANIMATION_10 IMAGESTEM POSTFIX

builds a ten image animation, each image being displayed for 100 ms Images Used

IMAGESTEM-A01
IMAGESTEM-A02
IMAGESTEM-A03
IMAGESTEM-A04
IMAGESTEM-A05
IMAGESTEM-A06
IMAGESTEM-A07
IMAGESTEM-A08
IMAGESTEM-A09
IMAGESTEM-A10

ANIMATION_15 IMAGESTEM POSTFIX

builds a fifteen image animation, each image being displayed for 100 ms Images Used

IMAGESTEM-A01
IMAGESTEM-A02
IMAGESTEM-A03
IMAGESTEM-A04
IMAGESTEM-A05
IMAGESTEM-A06
IMAGESTEM-A07
IMAGESTEM-A08
IMAGESTEM-A09
IMAGESTEM-A10
IMAGESTEM-A11
IMAGESTEM-A12
IMAGESTEM-A13
IMAGESTEM-A14
IMAGESTEM-A15

ANIMATION_04_140 IMAGESTEM POSTFIX

builds a four image animation, each image being displayed for 140 ms Images Used

IMAGESTEM-A01
IMAGESTEM-A02
IMAGESTEM-A03
IMAGESTEM-A04

ANIMATION_18_70 IMAGESTEM POSTFIX

builds a eighteen image animation, each image being displayed for 100 ms Images Used

IMAGESTEM-A01
IMAGESTEM-A02
IMAGESTEM-A03
IMAGESTEM-A04
IMAGESTEM-A05
IMAGESTEM-A06
IMAGESTEM-A07
IMAGESTEM-A08
IMAGESTEM-A09
IMAGESTEM-A10
IMAGESTEM-A11
IMAGESTEM-A12
IMAGESTEM-A13
IMAGESTEM-A14
IMAGESTEM-A15
IMAGESTEM-A16
IMAGESTEM-A17
IMAGESTEM-A18

Base tile related macros

Base terrains have all the combinations of macros as described in the naming convention section with the following definition

TYPE : the name for all macros starts with TERRAIN_BASE
PROB : 100
LAYER: -1000
FLAG': base
BUILDER: IMAGE_SINGLE

Overlay related macros

Overlays have all the combinations of macros as described in the naming convention section with the following definition

TYPE : the name for all macros starts with OVERLAY
PROB : 100
LAYER: 0
FLAG': overlay
BUILDER: IMAGE_SINGLE

Keep related macros

Keeps are base terrains (they use the same flag) but drawn on layer -1

Keeps have all the combinations of macros as described in the naming convention section with the following definition

TYPE : the name for all macros starts with KEEP_BASE
PROB : 100
LAYER: -1
FLAG': base
BUILDER: IMAGE_SINGLE

Village related macros

villages have all the combinations of macros as described in the naming convention section with the following definition

TYPE : the name for all macros starts with VILLAGE
PROB : 100
LAYER: 0
FLAG': village
BUILDER: IMAGE_SINGLE

Transition related macros

TRANSITION_BASE TERRAIN ADJACENT P=PROB=100 L=LAYER=-500 F=FLAG=transition B=BUILDER=IMAGE_SINGLE IMAGESTEM

This is the most basic form of transition, it will try to put a transition between the tile TERRAIN and ADJACENT

It will try to find the best matching image (with n,ne,se,s,sw,nw for @R flags)

i.e if your TERRAIN matches 2 ADJACENT tiles,

it will not match for 4 sided and 3 sided images
it will try 2 sided transitions with PROB (see also the FLAG discussion below)
if it doesn't match it will 1 sided transition similarly

Images Used

{{BUILDER} {IMAGESTEM} -@R0-@R1-@R2-@R3}
{{BUILDER} {IMAGESTEM} -@R0-@R1-@R2}
{{BUILDER} {IMAGESTEM} -@R0-@R1}
{{BUILDER} {IMAGESTEM} -@R0}

Flag Management

This macro checks flags according to the common transition policy, i.e it will check that both this tile and the ADJACENT neighbours don't have the transition-@R# flags before applying.

suppose our TERRAIN has two ADJACENT on north and north east

it will check the following flags before adding {{BUILDER} {IMAGESTEM} -n-ne}

TERRAIN has neither transition-n nor transition-ne set
the north ADJACENT doesn't have transition-s set
the north east ADJACENT doesn't have transition-sw set

if the conditions are met, it will apply the transition and set all the flags mentionned above

it will then try to apply {{BUILDER} {IMAGESTEM} -n} and check the following flags

TERRAIN has neither transition-n set
the north ADJACENT doesn't have transition-s set

(note that if the first rule applied, it will have set some flags and this rule will always fail) again, if it can apply, it will set the flags mentionned above

it will then try to apply {{BUILDER} {IMAGESTEM} -ne} and check the following flags

TERRAIN has neither transition-ne set
the north ADJACENT doesn't have transition-sw set

(note that if the first rule applied, it will have set some flags and this rule will always fail, however this rule could be applied with the second rule above since no flag contradict) again, if it can apply, it will set the flags mentionned above

DISABLE_BASE_TRANSITIONS TERRAINLIST

This macro will set all transition-@R* on the tile (n,ne,se,s,sw) thus preventing any other transition from being added

Flag Management will set all transition-@R* on the TERRAINLIST tiles

Terrain Specific

SIMPLE_FOREST_TERRAIN TERRAINLIST ADJACENT IMAGESTEM

will use an image IMAGESTEM-small# when next to adjacent and IMAGESTEM# anywhere else