Author: Ulf Lorenz
Version: 0.3.7


Contents:
    1. Introduction
        1.1. About
        1.2. Missing functionality
    2. Starting map creation
        2.1. Creating a new map
        2.2. Loading/saving
    3. Editing the map
        3.1. Placing terrain and objects
        3.2. Modifying objects
            3.2.1. Cities
            3.2.2. Ruins and temples
            3.3.3. Stacks
    4. Some menu items
    5. Managing players
    6. Editing the scenario manually
    


1. Introduction


1.1. About

This document describes the map editor. The editor has been added in version
0.3.5 and is at the time of this writing rather incomplete and crude. I hope it
nevertheless makes some fun creating maps with it. If you encounter bugs or find
some feature would be very important, just drop a mail. It may also happen that
the document is not up to date, though it should be updated before releases.


1.2. Missing functionality

I have been coding the editor for three months now and have got a bit tired of
it. So I hope you don't mind if some functions are missing. They will be
implemented in the future versions. Until then, see section 7 for some hints how
you can do things that the editor does not support.

Missing general things are:

- temple and ruin reports are missing
- keyboard support is missing
- the layout and usability is sometimes horrible
- the event system is complicated (this is rooted in the event system and
  propably not subject to change)
  
Missing functionalities are:
  
- it is not possible to set the actual hitpoins of an army, just the maximum
  (all armies start healthy into the game); the same goes for movement points
- items can not be placed on the map
- heroes cannot be assigned initial quests
- it is not possible to move objects, just to delete them and create a new one
- version support, i.e. if the savegame version changes, you need to patch the
  scenario file manually



2. Starting map creation


2.1 Creating a new map

In the file menu, select "New Map". In the first dialog, the terrain set
(currently only default), the size and the fill style can be selected. The fill
style selects which terrain the map should be initially filled with. A special
fill style is "Random Map". It creates a random map with cities, temples, ruins
etc. The terrain distribution and the number of buildings can be selected in a
following dialog. However, the buildings have only default names.

As an alternative, you can load the file "random.map" in the FreeLords savegame
directory (usually $HOME/.freelords). This file already has the players set up,
names given to buildings and standard events set up. It is the last played
random game.


2.2. Loading/Saving

The file menu also contains items for loading and saving. Loading a map pops up
a dialog to select a map file. Note that these files must have an ending of
".map", else they are not displayed.

Selecting the item "Save" in the file menu saves the map under the last filename
(i.e. the file the map was loaded from or the last saved file). If the filename
does not exist, the functionality is the same as "Save As", which also pops up a
dialog for selecting the file name and directory for saving. Note that a prefix
of ".map" is automatically prepended unless you write it explicitely.



3. Editing the map


3.1. Placing terrain and objects

When you have loaded or created a new map, the first thing you propably want to 
do is modify the terrain and place some buildings/stacks. For this, you have
several button at the right-hand side of the editor.

With the terrain icons, you select which terrain you want to place. Beside them,
you have several other buttons for

- changing the terrain in a 1x1 area
- changing the terrain in a 3x3 area
- removing objects (the red cross); note that you are not queried if you really
  want to remove something, and be aware that stacks are always removed first!
- placing stacks, cities, ruins, temples

For most objects, some error handling is done, e.g. you won't be able to place
cities in water, the terrain is automatically altered to grass. Note that this
does not work for stacks, so ensure that stacks that are placed in water only
consist of water-moving units!


3.2. Modifying objects

In general, you can always modify an object by right-clicking on it. When
multiple objects are stacked (e.g. a stack on a ruin), you are asked what you
want to edit.

3.2.1. Cities

Right-Clicking on a city opens the city dialog. Most of it should be fairly
self-explaining, so I will just describe some concepts here.

The difference between basic and advanced productions is already detailed in
the manual (basic = default armyset; the same for all players, advanced =
player-specific armyset, removed when city is conquered).

What is worth a remark is the dropdown to select between "Untouched" and "Burnt
down". When a player occupies a city, he may choose to raze it, which burns the
city down (it is just a ruin then). Sometimes it may be interesting to have a
city razed initially. To do this, select "Burnt down".

3.2.2. Ruins and temples

In short, what you can change here is mainly the name. In the case of ruins, you
can also modify the occupant (which a hero has to fight when entering the ruin)
by clicking on the button "Keeper". The following dialog is identical with the
stack dialog.

3.2.3. Stacks

Right-clicking on a stack brings up this dialog. Again, I suppose the dialog is
mainly self-explaining.

When changing the ownership of a stack, make sure that it is consistent, i.e.
don't place a player's stack in a neutral city. After all, the purpose of map
creation is _not_ to stress the error routines of the game. :)

The properties of the stack's armies can be modified as well. The idea behind
this is that sometimes finetuning of the strength etc. is needed e.g. to
reflect a wounded or veteran army.



4. Some menu items

The other menu items not described elsewhere are:

- a find dialog; Enter the ID of the object you look for (the object may be a
  city, ruin, temple, stack or unit), press Return and the map should jump to
  the object's position.
- a stack and a city report; Click on one of the listed objects to jump to their
  positions

The other things (player and event management) are subject of their own
chapters.



5. Managing players

Select the item "Players" from the "Edit" menu to open up the dialog for player
management.

Clicking on "Prev" and "Next", you can scroll through all players. Using the two
dropdowns, select the armyset of this player and the type.
There are four types of players (as in the game): Human, Dummy AI (does nothing
at all), Fast AI (assembles stacks and attacks) and Clever AI (tries to protect
cities etc.).

The edit fields below should be fairly self-explaining, you can set the color,
name and starting gold of the player.

There is always a neutral player which you can (and should) not remove.
Furthermore, you can make players persistent (immortal, i.e. they don't die when
loosing all cities). In the special case that you select a fast AI, there are two
additional options you can choose. First, you can have the player join close
stacks to increase their strength. Second, you can make the AI maniac. In this
case, it will attack relatively blindly (nice for wandering monsters).

If you add a new player, you will be asked whether you want to append it at the
end or before the actual player to give you some control about this.



6. Editing the scenario manually

If you want to do some excentric things which are currently not implemented or
so, there are two possibilities.

The first one is to send a mail (preferably to our developer list). Since there
will be only a few people who create maps, we will propably be so glad to have
someone doing this (with the prospect of getting more maps for FreeLords), that
we will implement the issues relatively fast. Then you only need to wait for a
new release or cvs version and are ready.

However, sometimes you do not want to wait, or you e.g. need to upgrade the
scenario file to a new version. Then the only possibility is to edit the
scenario file manually. Don't be discouraged, it is easier than it sounds.

The mapfile uses a specific XML format. Just open it with a text editor and you
will propably be able to identify large parts of it. You should know three
things when editing it, though (apart from doing a backup copy !!!):

1. Each object in the game (the stack, cities etc.) stores all its data between
   two tags. So a player stores all his data between <player> and </player>.
   Within these tags, all the subobjects are also stored. A stack that consists
   of armies will then store the data like this:

   <stack>
        ...stack data...
        <army>
            ...data of first army...
        </army>
        <army>
            ...data of second army...
        </army>
        ...
    </stack>

   The actual data is stored between tags that start with "d_". E.g. let us
   look at some player tag:

    <player>
        <d_id>4</d_id>
        <d_name>Evil Bad Genius</d_name>
        ...
    </player>

   That's most you need to know to edit the things.

2. The meaning of all the tags is documented in the file Savefile in the
   documentation directory. 

3. When the version has changed, the version number is at the very first opening
   tag in the mapfile. By adjusting it to the new value, you can make the
   parser accept your map. However, be sure to read and apply the changes listed
   in the file Savefile for this new version number (or these numbers if you
   have skipped some), else the whole map may break apart.
   If you want to contribute the map to our game and are experiencing such a
   problem, we would also give some help with these problems.



That's it.
If you find it a bit unsatisfying that the manual ends here, remember: Open
Source lives from contribution, and the minimal contribution is some feedback
*HintHintHint* :)
