
Table of contents

 1. Introduction
 2. Collision map
 2. Luola level configuration file 
 4. Luola compact level file
 5. Using foreign levels
 6. Level making tips

1. Introduction
--------------------------------------------------------------------------------

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

The level settings file is the file that luola searches for during startup.
It must have ".lev" extension for Luola to recognize it. The settings file
contains paths to artwork and collisionmaps.

These three parts can be seperate files, or all packed into a single one.
When packed into a compact levelfile, the filename must end in ".compact.lev".

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.

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

2. Collision map
--------------------------------------------------------------------------------

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

Terrain explanations:
 0. Free space
	This is just empty space, you can fly thru it. Explosions don't affect
	the level artwork in this area. See also Tunnel and Walkway

 1. Destructable landscape
 	The most often used terrain, regular destructable landscape. Explosions
	will make holes in this that appear black in the level artwork

 3. Underwater destructable landscape
 	Otherwise the same as normal landscape, except it will turn into water
	when destroyed. Artwork fill be filled with the colour of water

 4. Water
 	Like free space, except more viscous. This color is used to when creating
	new water in the game, so it should be the same as in level artwork.

 5. Base
 	Ships will recharge when they touch this. Depeding on settings, bases
	can be indestructable or they can regenerate.

 6. Explosive
 	When shot at or burned, this terrain will explode into normal bullets.
	
 7. Explosive2
 	Like above, but will explode into grenades. Beware that even small areas
	of this terrain will produce huge explosions!

 8-11. Waterflows
 	These water terrains will affect ships and bullets that travel thru them.
	The current is so strong that the ship cannot fight it (except with Dart),
	so be carefull how you use it.

 12. Combustable terrain
 	This terrain will burn away. The fire is started by special firestarter
	particles that are generated from large explosions.

 13. Combustable terrain 2
 	Like above, except will turn into grey ash. Using this in combination
	with above, you can make houses that will leave ruins after burning.

 13. Snow
    A bit like normal terrain, except it will chip away and you can burrow
	into it a bit.

 14. Ice
 	Like snow, except underwater.
 	
 16. Base material
 	A special terrain type you can use to make support structures for bases.
	Is indestructable if bases are.

 17. Tunnel
 	A type of free space where explosions affect the artwork. You can use
	this to make thin tunnels that will clear the artwork when the surrounding
	material is destroyed, so it wont leave funny looking trails hanging in
	midair.

 18. Walkway
 	A type of destructable terrain that pilots can walk thru. You can use this
	to make escape routes for pilots or trees that appear to be in the
	background. (See the level making tips section)

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

collisionmap = *	- Collisionmap filename
artwork = *			- Artwork filename
name = *			- Name of the level (appears in the level selection box)
aspect = ?.?		- Aspect ratio
zoom = ?.?			- Level zoom
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.

4. 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!

5. Using foreign levels
------------------------------------------------------------------------------

Luola allows you to define the meaning of each colour in collisionmap palette
so you can use custom level formats. This makes it possible to use levels
from other caveflying games in Luola.

To use a foreign level you must:
 1. Convert the level to a standard image format
 2. Write a configuration file for it

The first step might be a bit difficult as the levels are usually in an
undocumented format, so a bit reverse engineering is required.
Luckily, a tool is provided with Luola to make importing levels easier.

The "importlev" program in tools/ subdirectory is a tool for importing
levels from many different formats. Currently V-Wing, Wings and TOU levels
are supported, but writing new importer modules is very easy.

Usage:

	importlev level1.lev
	This imports a level named level1.lev

	importlev --compact level1.lev
	This imports the level and generates a compact level file.
	You can extract the images from the level file with the ldat
	tool if you wish.


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

