User:Mog/TerrainReorg

Terrain macro overhaul

The terrain macros are currently a mess. There are lots of inconsitencies and often several different ways to do the same thing.

I found the following issues. Feel free to add/comment to the list.

Issues

• Inconsistent ordering of parameters

• Inconsistent naming of macros

• Two ways of naming rotations. Most terrains have (n,ne,se,s,sw,nw), i.e. rotations are named according to the edges of the hex. Castles/chasm/etc. have the rotations (ne,e,se,sw,w,nw) i.e. named for the corners of the hex.

Proposed changes

• Have a consistent naming scheme. E.g. all macros that have a flag parameter end with _F, macros with a probability parameter with _P, layer with _L. Ideally, these suffixes are ordered the same way as the coresponding parameters.

• Most macros have a similar structure, so i suggest the following parameter ordering:

MACRO_NAME IDS1 [,IDS2, [IDS3, ...]] [LAYER] [PROB] [FLAG] IMAGE

There may be macros where this scheme will not work, but for the majority it should.

• I suggest renaming the castle tiles to use the more common naming method. This means renaming a corner direction to two edge directions (e.g. ne-> n-ne, e->ne-se, etc.). This also makes clear if the hexes around the corner are ordered clockwise or counterclockwise (another current inconsitency btw.)

Macro-proposal

General

Parameter ordering

The general parameter ordering is:

MACRO TERRAIN [ADJACENT1 [ADJACENT2 [...]]] [PROB] [LAYER] [BASE] [FLAG] IMAGE

Explanation:

• TERRAIN: The "center tile" on which the majority of the terrain is drawn, or -- in the case of some transitions -- the terrain which is the center of the rotation
• ADJACENT1 ... ADJACENTn: Adjacent tiles, depends on the exact macro. If more than one, ordered clockwise around the center tile.
• PROB: Probability
• LAYER: Layer on which the terrain is drawn (higher layers cover lower ones)
• BASE: For overlay terrains, defines the z-ordering among terrains on the same layer
• FLAG: Macros usually make sure that each type of transition occurs only once per tile. Default flags are "transition" for base terrains and "overlay" for overlays. Override the default flag if you need more than one transition stacked on the same tile.
• IMAGE: The basename of the image. Will be appended with a suffix depending on the macro

As the parameter number of each macro is fixed, variants of each macro exist for various combinations of optional parameters. The scheme is as follows:

MACRO_P for macros taking PROB as a parameter
MACRO_L for macros taking LAYER as a parameter
MACRO_B for macros taking BASE as a parameter
MACRO_F for macros taking FLAG as a parameter

and combinations thereof.

e.g.

MACRO_PF takes PROB and FLAG parameters

For parameters that don't occur, default values are used as follows:

• PROB: 100
• LAYER: Depends on macro, but generally -500 for transitions, 0 for overlays
• BASE: Depends on macro, but doesn't need to be overridden except in the most unusual circumstances. So I don't create macro-alternatives which take BASE as parameter (except the most general _PLBF macro)
• FLAG: Depends on macro, "transition" for base transitions, "overlay" for overlays

Rotations

For edge-based transitions, the rotations are n,ne,se,s,sw,nw

For corner-based transitions, the rotations are tr,r,br,bl,l,tl (for top-right, right, bottom-right, etc...)

Rotations are always specified in clockwise orientation.

Basic macros

Low level macros that are as flexible as possible to do almost everything without extra macros.

Things that can't be done with them are complex multihex-terrains (like mountains) and crazy stuff like bridges.

Basic terrains

These are simple terrain definitions that don't depend on the neighbouring tiles.

TERRAIN_BASE TERRAIN [PROB] [LAYER] [FLAG] IMAGE

Sets IMAGE as base terrain for a tile with TERRAIN. IMAGE should be a 72x72 image, parts that overlap the hex are cut off.

• Default LAYER: -1000
• Default FLAG: "base"

OVERLAY TERRAIN [PROB] [LAYER] [FLAG] IMAGE

Sets IMAGE as an overlay for a tile with TERRAIN. IMAGE should be a 180x252 image, The center of the tile is at (90,144) in the image (NOTE: This is an annoying restriction. The center of the image should be the center of the tile, no matter the size. This needs some code changes and the existing images need to be cropped. I'll probably do this at another time.) The image can overlap the hex.

• Default LAYER: 0
• Default FLAG: "overlay"

Transitions

TRANSITION_BASE TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE

Creates a "flat" transition between tiles with TERRAIN and ADJACENT. Depending on the number of ADJACENT tiles around the base tile, IMAGE is suffixed with -@R0-@R1-@R2-@R3, -@R0-@R1-@R2, -@R0-@R1 or -@R0. If images with more sides don't exist, the transition will be drawn using images with fewer sides (e.g. a 4-sided transition can also be drawn with one 3-sided and one 1-sided, two 2-sided or four 1-sided images).

Flags on the tiles will be set so that only one transition will be drawn per edge. So a X-Y transition on the south side of the X-tile will prevent a later Y-X transition on the north side of the Y-tile (unless you set a different flag on one of the transitions).

• Default LAYER: -500
• Default FLAG: "transiton"

(This macro is actually a combination of four TRANSITION{n}_BASE macros. But I can't imagine a case where you would actually need those, so they should be treated as implementation details.)

TRANSITION3_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE
TRANSITION2_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE
TRANSITION1_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE

Places an overlay image on the tile TERRAIN if there are at least {3,2,1} tiles of ADJECENT next to each other around it.IMAGE is suffixed with -@R0-@R1-@R2, -@R0-@R1 or -@R0. The image is placed in the same manner as in the OVERLAY macro.

Flags on the center tile will be set so that only one overlay will be drawn. (unless you set a different flag).

• Default LAYER: 0
• Default FLAG: "overlay"

(I'm not really happy with that name as it is basically the opposite of the TRANSITION_BASE macro. It's used for e.g. forest to draw smaller overlays when adjacent to terrains like castles.)

ADJACENT3_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE
ADJACENT2_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE
ADJACENT1_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE

Places an overlay image on the tile TERRAIN if there are at least {3,2,1} tiles of ADJECENT around it. In contrast to the TRANSITIONn_OVERLAY macros, those don't need to be next to each other, and IMAGE does not get any direction suffixes. The image is placed in the same manner as in the OVERLAY macro.

Flags on the center tile will be set so that only one overlay will be drawn. (unless you set a different flag).

• Default LAYER: 0
• Default FLAG: "overlay"

(used for the same case as TRANSITIONn_OVERLAY, but without rotating the image.)

CORNER_OVERLAY TERRAIN ADJACENT1 ADJACENT2 [PROB] [LAYER] [FLAG] IMAGE

Defines a transition between three terrains TERRAIN, ADJACENT1 and ADJACENT2 (ordered clockwise around the corner). IMAGE is suffixed with -@R0 and should be a 126x180 image. The corner of the three tiles is at (72,108) in the image (NOTE: The same applies here as in OVERLAY. Except it is not nearly as annoying and it would require more work to change, so I'll most likely keep it as it is).

Flags on the tiles will be set so that only one transition will be drawn per corner. (unless you set a different flag on one of the transitions). This works similar to the way TRANSITION_BASE works, just with three tiles.

• Default LAYER: 0
• Default FLAG: "overlay"

(I'm thinking of a macro EDGE_OVERLAY TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE that would work like CORNER_OVERLAY but on two terrains only. It's easy to add but I only could think of quite hypothetical usecases)

Misc macros

DISABLE_TRANSITIONS TERRAIN [FLAG]

Sets the flags for this and all neighbouring tiles so that TRANSITION_BASE won't draw any transition on the edges of the center tile.

When setting a different flag, transitions will be disabled for all TRANSITION_BASE macros using that flag.

• Default FLAG: "transition"

Higher level macros

These are usually compound macros that combine frequently used patterns of low level macros.

A frequent restriction of these macros is usually, that they don't work well with probabilities. We could include some macros that try to place alternative images if they exist (at least for some common cases).

I don't know if all parameter combinations are necessary here. Probably not, but depending on practical use, I might include them.

SIMPLE_OVERLAY_TERRAIN TERRAIN RESTRICTING IMAGE

Draws forest-like overlays. Places the overlay in the following manner (always assuming the image variant exists, otherwise it will just go to the next case):

• If there are more than 2 RESTRICTING tiles around the center, place IMAGE-small
• If there are 2 RESTRICTING tiles next to each other, and IMAGE-@R0-@R1 exists, place it
• If there are 2 RESTRICTING tiles *not* next to each other, place IMAGE-small
• If there is 1 RESTRICTING arund the center, place IMAGE-@R0
• Else, place IMAGE

WALL_TRANSITION TERRAIN ADJACENT [PROB] [LAYER] [FLAG] IMAGE

Draws a castle-like transition between TERRAIN and ADJACENT tiles. Uses the images IMAGE-convex-@R0 and IMAGE-concave-@R0

WALL_TRANSITION_CORNER TERRAIN ADJACENT1 ADJACENT2 [PROB] [LAYER] [FLAG] IMAGE

Draws a castle-like transition between TERRAIN, ADJACENT1 and ADJACENT2 tiles. Uses the images IMAGE-cw-@R0 and IMAGE-ccw-@R0

You usually only want to do this if you have different WALL_TRANSITION macros for ADJACENT1 and ADJACENT2.

Convenience macros

Simple macros that usually just set some commonly used parameters for you

VILLAGE_P TERRAIN [PROB] IMAGE

Draws an overlay with the "village" flag set.