TerrainMacrosWML

From The Battle for Wesnoth Wiki

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
  • overlay-connect-@R* : used for bridges, the bridge on this tile. The bridge "actually has" an "exit direction" in the @R direction indicated.
  • overlay-away-@R* : used for bridges, the bridge does NOT have an exit on the given direction, but would be expected to...


A note about overlay-@R and overlay-away-@R flags

Suppose we have a n->s bridge hex who's ne neighbour is a ne->sw bridge. This mean that the n->s is actually a turn in the bridge that should use a graphic depicting a s->ne corner.

In that case the tile will have overlay-s and overlay-ne set (the directions where the bridge actually exits) and overlay-away-n (the direction where the bridge would exit according to terrain codes, but doesnt because of overall layout)

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.
  • 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

Generic Functions

transitions have most of the macros as described in the naming convention section with the following definition

  • TYPE : the name for all macros starts with TRANSITION
  • PROB : 100
  • LAYER: -500
  • FLAG: transition-@<side>
  • BUILDER: IMAGE_SINGLE


However, unlike all previous type of macros, they are related to a side instead of the whole hex. Thus the following rules

  • There are no ROTATION macros. Since they are always side related.
  • All images are named as if they were ROTATION macros since they are all side related
  • There is no SINGLE variation since it doesn't make sense to have it (a side is always relative to two hex)
  • The flags are set and tested on a side related basis. i.e there can be more than one transition per tile, if they don't cover the same direction
  • for RESTRICTED2 and RESTRICTED3, we only check for neighbouring hex of the ADJACENT type. This makes more sense for borders
  • the COMPLETE variant looks as follows


#define BORDER_COMPLETE_LFB TERRAIN ADJACENT LAYER FLAG BUILDER IMAGESTEM
   {BORDER_RESTRICTED3_RANDOM_LFB  ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
   {BORDER_RESTRICTED2_RANDOM_LFB  ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
   {BORDER_RESTRICTED_RANDOM_LFB   ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
   {BORDER_RESTRICTED_RANDOM_LFB   ({TERRAIN})  ({ADJACENT}) {LAYER} {FLAG} {BUILDER} {IMAGESTEM}}
#enddef

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

DISABLE_BASE_TRANSITIONS_F TERRAINLIST FLAG

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

Flag Management will set all <FLAG>-@R* on the TERRAINLIST tiles

Track Type macros

These macros handle anything that is layed in a connected way over multiple tiles (typically bridges and tiles)

the TRACK macro

TRACK_LF <NWSEterrain> <NSterrain> <NESWterrain> <basename

This macro will add the base terrain on the three terrains corresponding to the three directions.This macro will awlays take random variations, and defaults to layer -80 with flag=overlay

The images used are named

  • base#-ns.png : non-connected on a north-south orientation,
  • base#-nesw.png : non connected on a north-east south-west orientation
  • base#-senw.png : non connected on a south-east north-west orientation
  • base#-<connections> : tile used when the bridge is connected on the corresponding sides (separated by '-', ordered clockwise starting with north)

NOTE: the engine will use the straight tile when it doesn't find any fitting tile

NOTE: if some connection tiles don't seem to be used properly, please post a screenshot from the editor with terrain names enabled and contact boucman

NOTE you will notice that there is no builder. Builders are incompatible with bridges (in other word,the IMAGE_SINGLE builder is hardwired)

Transition related macros

Bridges are tricky because you usually don't want the same transitions depending if the bridge ends on a given edge or not.

The following macros help

TRACK_BORDER_RESTRICTED_PLF <terrain> <adjacent> <IMAGE>

Will match only if terrain is a bridge, on the side matching adjacent, and if the bridge does have a connection or ending on the given side.

Note that adjacent can be a bridge too, but this macro won't check that adjacent exits on the corresponding side

the image will be drawn on the <terrain> hex with the orientation appended to it

TRACK_BORDER_RESTRICTED_RANDOM_LF similar, with random variations

See Also

Retrieved from "https://wiki.wesnoth.org/index.php?title=TerrainMacrosWML&oldid=71124"
This page was last edited on 7 May 2023, at 17:44.