Rendering description
Author: Ulf Lorenz, Ben Asselstine


0. About this document
1. Rendering
    1.1. Tles, Subtiles
    1.2. How rendering is done
2. Layout of a tileset
    2.1. The graphics file
    2.2. The description file
3. Other files


0. About this document

We have adopted the current rendering algorithm for quite a while now. However,
it may not be obvious to the average coder, leave alone graphic artists. Since
on the other hand a person that wants to create some tilesets should know a bit
about the rendering algorithm to create the tilesets in the correct fashion,
this document emerges.


1. Rendering

1.1. Tiles and their styles

The basic unit of a map in LordsAWar is a single tile. 
There are water tiles, grass tiles, swamp tiles, mountain tiles, hill types and forest tiles.
The look of a tile is called it's style.  The style of tile can be one of:
  lone, outertopleft, outertopcenter, outertopright, outerbottomleft, outerbottomcenter , outerbottomright, outermiddleleft, innermiddlecenter, outermiddleright, innertopleft, innertopright, innerbottomleft, innerbottomright, toplefttobottomrightdiagonal, bottomlefttotoprightdiagonal

The terms are easy to understand.

outertopleft transitions to grass towards the north and west.  For example:

+--------------------+
|                    |
|   grass            |
|                    |
|         +----------|
|         |          |
|         |          |
|         |   hill   |
|         |          |
|         |          |
+--------------------+

The idea behind the name is that this hill tile goes on the outer top left of a picture frame of hills.  E.g. imagine a picture frame made of hill tiles:


  +-----------------------------------------+
  |      grass                              |
  |   A---------------------------------+   |
  |   |                                 |   |
  |   |              hills              |   |
  |   |     B--------------------+      |   |
  |   |     |                    |      |   |
  |   |     |                    |      |   |
  |   |     |     grass          |      |   |
  |   |     |                    |      |   |
  |   |     |                    |      |   |
  |   |     |                    |      |   |
  |   |     +--------------------+      |   |
  |   |                                 |   |
  |   |                                 |   |
  |   +---------------------------------+   |
  |                                         |
  +-----------------------------------------+

To represent this picture with a series of tile styles, some of the tile 
styles will represent the outer corners of the hills (A), while other tile 
styles will represent the inner corners (B).

The outertopright style transitions to grass to the north and east.  It 
fits nicely with the outertopleft style:


+----outertopleft----++----outertopright---+
|                    ||                    |
|   grass            ||          grass     |
|                    ||                    |
|         +----------||-----------+        |
|         |          ||           |        |
|         |          ||           |        |
|         |    hill  ||   hill    |        |
|         |          ||           |        |
|         |          ||           |        |
+--------------------++--------------------+

innertopleft transitions to grass towards the south and east.  For example:

+----innertopleft----+
|                    |
|   hill             |
|                    |
|         +----------|
|         |          |
|         |          |
|         |  grass   |
|         |          |
|         |          |
+--------------------+

This tile takes care of the the inner top left transition.  For example (B) 
on the picture frame.


a lone tile transitions to grass on all sides.  For example:

+---------------------+
|                     |
|   +-------------+   |
|   |             |   |
|   |             |   |
|   |    hill     |   |
|   |             |   |
|   |             |   |
|   +-------------+   |
|          grass      |
+---------------------+


1.2. How rendering is done

The game engine automatically picks the styles that "go together".  For 
example it knows that an outertopright style goes with an outertopcenter 
style.  Some groupings of tiles are impossible to render well.  

Consider the picture frame again, where the frame itself is composed of a 
border 1 deep of hill tiles.  The styles would have to transition to grass 
on either side of each tile.  A lone tile is the only tile that can do 
this -- making the picture frame look repetitive and boring, made up 
entirely of lone tiles.  This is the reason why the game engine prefers 
2x2 clumps of tiles.

The game engine could be altered to allow for styles that can transition to 
grass on opposing sides, but it would only mean more tiles for the graphic 
artist to produce.  By limiting the artwork in this manner, it is hoped that
it will be a little bit easier to contribute artwork to lordsawar.

The game engine allows for alternate represenations for any tile style.
After the engine determines which tile style is right for a given tile on
the screen, it randomly selects an alternate variation of that tile style
from a pool of all available tile styles.  By adding many alternates the
scene can look more diverse and interesting.

If the preferred tile style is not available because the tileset does not
contain it, the game engine defaults to showing a lone tile.  This behaviour 
is what makes grass and swamp tiles look like they do, despite the fact that
they only contain lone tiles.


2. Layout of a tileset

In general, a tileset contains many tiles, and a tile contains many tilestyles.

2.1. The graphics files

Must be a PNG file.
Must contain only pictures for the kind of tile it belongs to.
Must be composed of a set of square tiles, all on the same row.
The dimensions of each tile is given as the d_tilesize value in the tileset.
The order of tiles in the file must match the order of the tilestyles in 
this tile.

2.2. The description file

Beside the graphics, each tileset also consist of an XML description file.  
For a working example, examine the default tileset description file in 
$tileset_dir/default/default.xml.

<?xml version=1.0>
<tileset>
    <d_name> The name of the tileset </d_name>
    <d_info> Additional info string </d_info>
    <d_tilesize> the number of pixels high and wide of a tile </d_tilesize>
    <tile>
        <d_name> Name of the tile type (used in the editor) </d_name>
        <d_moves> # of movement needed to cross this tile </d_moves>
        <d_type> terrain type.  See Tile.h for a list of tile types. </d_type>
        <smallmap>
          contains colour and patterning information for showing this
          tile in the smallmap.  Different patterns require a specific
          number of colours.  See Tile.h for a list of pattern types.
        </smallmap>
        <tilestyleset>
            <d_name>the basename of the PNG file in this directory that
                    contains the style images for this tile </d_name>
            <tilestyle>
                <d_id>a unique numeric Id for this tile style.  It must be
                    unique among all tilestyles in the tileset.
                    This Id will appear in the <styles> entity of the save
                    game file.</d_id>
                <d_type> the type of tile style.  See tilestyle.h for a list.
                </d_type>
            </tilestyle>
            ... more tilestyles ...
        </tilestyleset>

    </tile>
    <tile>
        ... more tiles ...
    </tile>
    ...
</tileset>


Note that the 'd_*'-tags always enclose actual data while the others just
give structure. Leading and trailing spaces are not removed, so the following
is wrong:
<d_red> 50 </d_red>

Instead use:
<d_red>50</d_red>

The description of the single tile styles has to be in the same order as they appear in the graphics file, else the images in the game will be wrong.


3. Other files

Though the graphics files and the description file are the most important, a
complete tileset takes several more files. These are:

- castle images 
- tower images
- selector images
- flag images
- road images
- fog images
- images for ruins, temples, signposts, ports, and bridges

These images are superimposed onto tile style images.

There is one castle image per player, and there are up to 8 players, plus 
one neutral player.
There is one tower image per player, and there are up to 8 players.  Neutral 
players never have towers.
There are 8 flag pictures because the maximum number of armies in a stack is 8.
There are 2 ruins, and 1 temple pictures.  The game will *not* automatically
use a second temple picture if it is added.
Fog is superimposed lastly, if hidden-map mode is turned on.



