Version 1.2.2 introduced some changes to the level system and it was
again significantly modified in 1.2.6

A Luola level is made up of three parts:
    1) The level artwork
    2) The collisionmap image
    3) Level settings file

These three parts can be seperate files, or all packed into a single one.
The level artwork file can also be used as the collisionmap, provided that
it is palette based and the colours are arranged properly. You can manually
specify the meaning of each color, so it is possible to use levels from
other caveflyers in Luola. Sample configuration files for V-Wing and Wings
levels are provided.

The level artwork is the part of the level the player sees.
The collisionmap specifies different terrain types such as free space, ground,
water, explosives etc. The image used as a collision map has following limitations:
  1) It must be exactly the same size as the level artwork
  2) It must have an indexed palette

By default, the collisionmap palette entries have the following meanings:
Color 0  - None (free space)
Color 1  - Destructable landscape
Color 2  - Underwater destructable landscape
Color 3  - Indestructable landscape
Color 4  - Water
Color 5  - Base
Color 6  - Explosive
Color 7  - Explosive2
Color 8  - Water, flows upwards
Color 9  - Water, flows to the right
Color 10 - Water, flows downwards
Color 11 - Water, flows to the left
Color 12 - Combustable terrain
Color 13 - Combustable terrain2
Color 14 - Snow
Color 15 - Ice
Color 16 - Base material
Color 17 - Tunnel
Color 18 - Walkway

The first color is just empty space, you can fly in it.
The underwater destructable landscapes turns into water when shot at, while
normal landscape turns to black space.  The color of the newly created water
comes from this palette, so use the same colour there as you used in the
artwork image. Combustable terrain can catch on fire, Combustable terrain2
is otherwise the same, except it turns into grey terrain after it has burned.
You can use it to create ruins.  Base material is a special material that is
either normal destructable or indestructable landscape, depending on if the
indestructable bases option is set. You can use as the material supporting the
base.  (If you use normal terrain to support the base and someone comes and
shoots it away, then you get a lonely looking floating base and if you use
indestructable terrrain to support the base and someone shoots the base away,
then the support looks lonely. This terraintype eliminates that problem)
The 'tunnel' terrain type is otherwise the same as 'free', but explosions
affect it. This allows you to make narrow tunnels with colour other than black
that explode away when the terrain next to it is shot at. Previously you had
to do this with 'free' terrain, which has the problems that after all the
terrain around the tunnel has been destroyed, you still have nasty looking
streaks going thru mid-air. Note that this terraintype works best with thin
tunnels. (See the demo level to see what I mean)
The 'walkway' terrain type is a bit similiar to 'tunnel'. Walkway acts otherwise
the same as normal destructable landscape, except that pilots and land critters
can walk thru it.  You can use it to create quick escape tunnels for pilots.
Ships cannot enter the walkway without first breaking it like normal terrain.
Note that you cannot use the rope inside this terrain!

V-Wing format
------------------------------------------------------------------------------

Because Luola supports custom terrain type palettes, you can use levels from
other games such as V-Wing. First, you must convert the level to a PCX image
file so Luola can open it. Luckily this is pretty simple to do, as the V-Wing
level files seem to be simply PCX images with a special header.
A quick and dirty way to convert it is to overwrite first 125 bytes of the file
with a PCX header. The following script will do it:

#!/bin/sh
cp $1.lev $1.pcx
dd if=blank.pcx of=$1.pcx ibs=1 count=125 conv=notrunc

You will find the script and blank.pcx in the tools/ subdirectory.

The next step is to write a configuration file that defines the custom palette.
See the sample level configuration file tools/vwing.lev
Here is an excert from the V-Wing's level conversion tool documentation that
documents the palette:

                V-Wing Color Chart
                ------------------

        1       Background color (will always be black)
        2-15    Reserved                                  (don't use)
        16      Water
        17      Waterfall (flow down)
        18      Water (flow right)
        19      Water (flow left)
        20-30   Fly through
        31      Reserved                                  (don't use)
        32-37   Font
        38      Reserved                                  (don't use)
        39      Ice (not in water)
        40-42   Explodes into Grenade Launcher shells
        43-44   Explodes like Plastic Explosive
        45      Plastic Explosive
        46      Birds
        47      Reserved                                  (don't use)
        48      Blood
        49      Clay
        50      Base
        51      Ash
        52      Snow
        53-55   Reserved for fire                         (don't use)
        56      Bubbles
***     57-149  Normal colors                                 ***
        150     Doesn't burn                              
        151-174 Burns away
        175     Burns for ever                            (don't use)
        176-199 Burns to ash
        200     Indestructible, doesn't damage Ghostship  (don't use)
        201     Underwater ash
        202     Underwater clay
        203     Ice
        204-219 When destroyed, turns into water
        220     Indestructible, doesn't damage Ghostship  (don't use)
        221-243 Indestructible
        244     Turret muzzle (firing)
        245     Turret barrel and body
        246     Turret muzzle
        247     Turret body (sides)
        248-256 Indestructible


Wings format
------------------------------------------------------------------------------

You can use Wings levels the same way as V-Wing levels. The 'unmakelev' utility
by Pauli Virtanen (found in contrib/ directory) will convert a Wings level into
a BMP picture.
See the sample level configuration file tools/wings.lev
See the "Using foreign levels" chapter for more info.

Luola level configuration file
------------------------------------------------------------------------------

The level configuration file is required for Luola to recognize its levels.
The configuration file must have at least a [main] block.
Values that must be set there are at least:
 * collmap and/or artwork
 * name

Level configuration files must have the file extension .lev for Luola to
recognize them.

A line starting with '#' is a comment line.

The file is divided into following blocks:
[main]		- This block sets general things like the name of the level and filenames.
[override]	- Level settings can be overridden here
[objects]	- Manually placed level objects
[palette]	- Custom palette for luola 8 bit level format
[icon]		- Icon for the level

All unrecognized blocks are skipped.
A block must end with [end]
All subblocks must end with [endsub]

Main block
----------

modified = ????????????	- Last modification date yyyymmddhhmm (currently unused)
collisionmap = *.coll.*	- Collisionmap filename
artwork = *.lev.*		- Artwork filename
name = *				- Name of the level (appears in the level selection box)
scalex = ?				- Horizontal scaling
scaley = ?				- Vertical scaling
smoothscale = ?			- If set to 0, smooth scaling will be disabled even if available
music = *.???			- Set to the name of the background music file for this
							level (multiple entries allowed)

Override block
--------------

critters = ?				- Force critters to be enabled/disabled
bases_indestructable = ?	- If set to 1, bases will be indestructable

stars = ?					- Stars enabled/disabled
snowfall = ?				- Snowfall enabled/disabled
--The rest are numbers of automatically placed objects--
turrets = ?
jumpgates = ?				- Note: this is the number of jumpgate _pairs_
cows = ?
fish = ?
birds = ?
bats = ?

Objects block
-------------
This block contains sub blocks that start with [object] and end with [endsub]

Object sub block:
type = {turret,jumpgate,cow,fish,bird,bat,ship}	- Type of the object
x = ?											- X and Y coordinates.
y = ?
ceiling_attach = {1,0}							- When set to 1, the object
												is aligned by its top border
value = ?										- A special value of the object.
						  When used by a turret: 0=normal,1=grenade,2=missile
						  When used by a bat: 0=awake, 1=asleep
						  When used by a ship: 0 gray, 1-4 coloured
id = ?						- A temporary ID for the object. Used only by jumpgates.
link = ?					- ID of the objects link. Used only by jumpgates.

The id and link values are used by jumpgates to find their pairs.
Both jumpgates must have their ids and links set up accordingly.
The id can be any number, it is used only while searching for the jumpgates pair.

Note about the coordinates.
The coordinates are aligned so that x is the left border of the object
and y is the _lower_border_. This is so that the objects can be aligned properly
regardless of their size.
Some objects like ceiling attached turrets and bats benefit more if the object
is aligned by its upper border. In these cases, set ceiling_attach to 1.
If level is scaled, the coordinates are automatically scaled as well.

Palette block
-------------

In this block, you can create a custom palette for the level.
If no palette is specified, the default palette as specified
in the beginning of this document is used. Any terrain types
not defined here will be disabled. Colours that are not mapped
anywhere will be mapped to the default terrain. (Default is 0
if not set here)

<colour range> = <type>

Colour range can be a single number (eg. 0) or a two numbers (eg. 0-10).
Type can be one of following:
free,ground,underwater,indestructable,water,base,explosive,explosive2,
waterup,waterright,waterdown,waterleft,combustable,combustable2,snow,
ice,basemat,tunnel,walkway.

Example:
0-10 = free
11-20 = ground
21 = base

Level icon
----------

The level icon is just an XPM image you put in the level configuration file.
Remember that the XPM image's first line must be "/* XPM */", otherwise
SDL_image won't recognize it.

Luola compact level file
------------------------------------------------------------------------------

The compact levelfile format uses the Luola datafile to
store its files.
The compact level files must end in ".compact.lev"
Files are stored under the following IDs:

"ARTWORK"	The level artwork file
"COLLISION"	The level collisionmap file
"SETTINGS"	The level settings file
"SOURCE"	Level settings file in ASCII format (optional)

The settings file must always be present.
Should the artwork entry be excluded, the artwork is loaded from the collisionmap.
Note that the collisionmap must be present!

Using foreign levels
------------------------------------------------------------------------------

Luola 1.1.6 introduced the new 8bit level format.
Thus, hardcoded support for V-Wing and Wings levels was dropped as unneseccary
bloat. This is because, all other palette based levelformats can now be
described with a custom palette.
Start out by creating a configuration file for the level you wish to use in
Luola.  Then you must define the palette translation map for the palette
format the level uses. See the level configuration file chapter on how to do
this.  There are sample configuration files for V-Wing and Wings levels under
the tools/ subdirectory you can use to define your levels.
Depending on the palette format and the level, you might be able to change the
level's palette so it would take advantage of certain extra features of Luola's
engine. For example, in the "Citadel of Yogu" V-Wing level, you could change the
coloured tunnel backgrounds to use the TER_TUNNEL terrain type instead of
TER_FREE.

Level making tips
------------------------------------------------------------------------------

Dithered colourslides
---------------------

In my levels, large areas with a colour slide (like ground or large buildings)
are often dithered. This gives a nice retroish effect that looks pretty
good in Luola.

First create the area and fill it with the colourslide.
You can then use the airbrush tool of your image editor and make the gradient
seem a bit more random and natural.
Now use the selection tools to select the area which you wish to dither.
If you are using gimp, you can use the dither filter (Filters->Noise->Ditherize)
to do the actual ditherization. (Gimp perl extension is required)
If a dither tool is not available, then copy the selection to clipboard,
paste it on a new image and convert that image to 8bit format.
Then copy the new now ditherized image (assuming dithering was turned on)
to clipboard and paste it back to your level.

Stars in caves
--------------

Luola has the feature to display stationary stars behind the level.
Here is a neat trick to make the stars invisible in some areas,
it is useful for example in underground caverns.
It is a subtle effect, but a nice one.

To do it, simply fill the area where you don't want stars to appear
with an _almost_ black colour.
Luola draws the star if the pixel underneath is of type TER_FREE and its
red,green and blue values are smaller than 5.
So, you could fill the area with for example 0x050505

Base material
-------------

Luola has a special terrain type called 'Base material'.
This terrain behaves either as normal destructable terrain or
indestructable terrain depending on whether or not the 'Bases
are destructable' option is set. You can use it to create the
terrain supporting a base. For example, say you have a gas station
floating in space. On the station, there is a base. If bases are
destructable, it is no problem if someone comes up and blasts the
thing to oblivion. However, if bases are indestructable, you have a
floating grey strip hanging in midair. Looks rather silly doesn't it?
This is where base material comes in. Make the important parts of the
gas station out of it and the problem is solved!

Explosive terrain
-----------------

Luola has two explosive terraintypes.
The difference between the two is that TER_EXPLOSIVE2 explodes into grenades
while TER_EXPLOSIVE explodes into normal bullets. Even very small areas of
explosive2 can create a huge explosion so use it with care ! Then there is also
the problem that luola has 4 different sizes for the hole created by an explosion.
The smaller the hole, the bigger the explosion of course (more bullets are
created). So you should use only small areas of explosive terrain, and try to
arrange the explosives so that they work well with all holesizes.

Trees
-----

Trees are nice.
Typically when creating a tree, you use two different terraintypes.
Normal burning terrain for the leaves and terrain that burns into ash for
the trunk and branches.
How about when there are critters in the levels ?
If the tree is small, it looks silly if a cow walks straight over it.
Here is a simple trick that allows ground critters (and pilots)
to walk through the trees making it look as if they are walking in front of them.
In the collisionmap, create a thin line (1 pixel in height) of Walkway terrain that
cuts the tree right next to the ground. Ground critters can then walk thru this
line. Walkway turns gray when it is burned, so it is completely invisible to the
player.

