Version 1.1.6 supports two different level formats.
First is the luola's native format which uses seperate level artwork and collisionmap images.
The second one is a palette based format, with a customizeable palette.
You can use it to load levels from practicly any other cave flying game. (sample configurations are
provided for V-Wing and Wings)

Luola's native level format
----------------------------------------------------------------------------------------------

As of version 0.2.6, a level is composed of two files:
1) An image (can be any format recognized by SDL_image) that contains the actual level artwork
2) An image (can be any format recognized by SDL_image, but you should use ones that have lossles encompression) that contains the collision map.

The level artwork image should be named <your_level_name>.lev.<imageformat>
and the collision map <your_level_name>.coll.<imageformat>
The first level name part can be anything as long as it qualifies as a filename,
it will be displayed in the level selection dialog. Underscores are converted to spaces.
If the filename does not contain either .lev. or .coll., it will be ignored.

The terrain image file can be any picture, it is where you will be flying around. It should be as big as possible, still keeping in
mind the memory limitations. (Larger maps == More fun && More memory )

The collision map is a bit trickier. While the terrain file can be all freeform, the collision map must follow some rules:
  1) It must be exactly the same size as the terrain map
  2) It must have an indexed palette
  3) You should use lossless encompression (I dont remember if there is any lossy compresion for indexed images, but just to be on the safe side...)

The palette entries in the image mean the following:
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'.
The terrain 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
------------------------------------------------------------------------------

I implemented the V-Wing format so I could play my old favourite levels in my own game.
First you need some V-Wing levels. If you don't have V-Wing, you can still use this format if you don't like luola's
normal system.

Converting v-wing levels to PCX:
You need to convert the .lev file to a .pcx file before luola can read it.
Here is a simple script to do that (you can find the blank.pcx from the tools directory)

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

The builtin support for V-Wing levels was removed in Luola 1.1.6, because the new
Luola 8bit level format was implemented. See the "Using foreign levels" chapter for more info.
The V-Wing levels have an indexed palette of 256 colours.

Here is an excert from the V-Wing's level conversion tool documentation:

                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 the 'unmakelev' (found in the contrib/ directory)  tool
by Pauli Virtanen to convert Wings levels into a format Luola can read.
See the "Using foreign levels" chapter for more info.

Luola 8bit level format
------------------------------------------------------------------------------

This format is similiar to the V-Wing and Wings level formats.
Any palettezized image supported by SDL_image can be used.
Note that in most of the cases, you cannot use the luola collisionmap image format.
LCMAP format only uses 6 bits to store colour information which will probably not be enough.
(Although, if you set up a custom palette and have a very simple image you can use it.
But the compression might not be as good as with PNGs)
The filename must be <levelname>.8bit.<extension> .
This level format is rather special, because you can define the palette yourself.
If no palette is defined, the default one will be used.
This levelformat can also be used to suppport other games levels in luola.

The default palette:

Color name	First color	Last color	Total colours
Fly-thru	0		15		16
Tunnel		16		25		10
Walkway		26		31		6
Ground		32		149		118
Base		150		151		2
Base material	152		156		5
Indestructable	157		176		20
Underwater	177		191		15
Water		192		192		1
Water up	193		193		1
Water right	194		194		1
Water down	195		195		1
Water left	196		196		1
Explosive	197		199		3
Explosive2	200		202		3
Combustable	203		227		25
Combustable2	228		252		25
Snow		253		253		1
Ice		254		254		1

Note that color 0 should always be black.
If you have any improvements to this draft, please email me !

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

This is an extra file bundled with the other level files.
Level settings can be overridden here and specials and critters can be
manually placed.
The filename must end in .conf.lev in order for luola to recognize it.
There is also a binary version of the configuration file that
is used inside compact level files. The binary code entries are given below
Current draft of the format follows:

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

The file is divided into blocks.
Currently, these blocks are planned:
[main]		0x01	- This block sets general things like the name of the level and filenames.
[override]	0x02	- Level settings can be overridden here
[objects]	0x03	- Manually placed level objects
[kluolaedit]		- A special block used only by KLuolaEdit. Luola ignores this.
[palette]	0x04	- Custom palette for luola 8 bit level format
[icon]		0x05	- Icon for the level

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

Some words about the binary format
----------------------------------

The binary format is used only inside compact level files.
Therefore, some entries are excluded, such as the entire kluolaedit block.
This is because the compact levelfileformat is meant for level distribution,
you should keep the actual source files and edit those.
(You can of course publish the ASCII configuration file if you want)
The collisionmap and artwork filenames are not included because
in the compact level file, they are found under their predefined IDs.
The actual binary file is divided into blocks.
Each block follows the format of:

(Uint16) length of data
(Uint8) type
*freeform data*

The contents of the data depends on the type. It can be a
string or it can be a single byte value (as it is in most cases)
The toplevel blocks also use the same format.
The blocks are read recursively like this:

readDataFile(FILE file) {
  while(!eof) {
    len=read16bit(file);
    type=read8bit(file);
    switch(type) {
      /* Call the proper readSubBlock for this type */
      readBlock(len,type,file);
    }
  }
}
/* There should be a proper readBlock for all the toplevel blocks */
/* Based on the data, they might call their own readSubBlocks */
readBlock(Uint16 len,Uint8 type,FILE file) {
  Uint16 read=0,slen;
  Uint8 stype;
  while(read<len) {
    slen=read16bit(file);
    stype=read8bit(sfile);
    read+=3;
    switch(type) {
      /* Handle the data */
    }
  }
}

Some notes about the data values:
Typically, the values are the same as they were in the ASCII version,
except that they are stored as binary values so value 
myvalue = 1 is not stored as '1' in the binary mode, but as 0x01
Most values use only one byte. Should one byte be
insufficient, it will be noted below.
Strings are saved as they are.

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

0x01 modified = ????????????	- Last modification date yyyymmddhhmm
collisionmap = *.coll.*			- Collisionmap filename
artwork = *.lev.*				- Artwork filename
0x02 name = *					- Name of the level (appears in the level selection box)
0x03 type = {0x01 luola,0x02 luola_8bit,0x10 vwing,0x11 wings}	- Type of the levelfile
0x04 scalex = ?					- Horizontal scaling
0x05 scaley = ?					- Vertical scaling
0x06 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)

Binary notes:
modified:
(Uint16) year  (the year 65536 bug)
(Uint8) month
(Uint8) day of the month
(Uint8) hour
(Uint8) minute
The music filename is not stored in the compact level file.
Music files themselves are stored in the package and used if present.

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

0x01 critters_enabled = ?	- If set to 1, critters will always be enabled. (If the user has disabled
				  critters, even the manually placed ones won't appear)
0x02 bases_indestructable = ?	- If set to 1, bases will be indestructable

0x03 stars = ?			- Stars enabled/disabled
0x04 snowfall = ?			- Snowfall enabled/disabled
- The rest are numbers of automatically placed objects -
0x05 turrets = ?
0x06 jumpgates = ?		- Note: this is the number of jumpgate _pairs_
0x07 cows = ?
0x08 fish = ?
0x09 birds = ?
0x0a bats = ?

Note. In the binary file, these values are limited to 0-254.
This should be sufficient though, no level should have 254 jumpgates !

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

Object sub block:
type = {0x01 turret,0x02 jumpgate,0x03 cow,0x10 fish,0x11 bird,0x12 bat,0x20 ship}      - Type of the object
x = ?						- X and Y coordinates.
y = ? 						- These will be scaled according to the scalex and scaley values
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.

Binary notes:
x,y,id and link are stored as 4 bytes (Uint32).
All the values above are stored.
The subblock starts with an Uint16 telling the length of the block

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

In this block, you can create a custom palette for the
Luola 8 bit level format.
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)

default = ?		- The default colour to which unmapped colours will be mapped

[terrain]		- Start a terrain sub type block
  type = ?		- Type of the terrain (0..18, see the top of this file)
  begin = ?		- The palette entry from which this starts
  end = ?		- Last palette entry which will be mapped to this terraintype
[endsub]		- End terrain type sub block

Binary notes:
This entire block is a 256 byte array that contains the 'compiled' palette
translation map.

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.
The binary settings block contains the image in SBMP format.
Binary format:
Uint8     - Use colorkey ?
Uint32    - Colorkey
Uint8*len - SBMP data

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

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

"ARTWORK"	The level artwork file
"COLLISION"	The level collisionmap file
"SETTINGS"	The level settings file

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 Luola 8bit format.
Start out by creating a configuration file for the level you wish to use in
Luola. Set the level type to "luola_8bit".
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.
Tip. 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 the luola 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
------------------------------------------------------------------------------

Here are some tips that might help you in making your level.

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.

