Author: Ulf Lorenz
Version: 0.3
Date: 2003-12-20


This document wants to describe some internals of the freelords source code in
a (hopefully) organized fashion. It is aimed at people interested in and willing
to contribute to a (quoting Michael): fantastic game. The problem is that
although the source code is always the last instance when it comes to
understanding how something works, someone completely new to the project may
want to have a small guide to understand what each class is for and how several
concepts work.


Table of Contents:

0. Introduction
1. Startup
    1.1. The program flow till the splash screen
    1.2. Starting a game
    1.3. Loading a game
2. The user interface in the actual game
    2.1. The game screen
    2.2. The 
3. Loading/saving
    3.1. The xmlhelper class
    3.2. Saving a game
    3.3. Loading a game
4. several Game lists and objects
5. Player derivation scheme
6. Army handling
    6.1. Armyset_Army
    6.2. Armysets
    6.3. Armies and stacks
7. Configuration


0. Introduction

First of all, I want to ask you to mail me any corrections, suggestions,
misunderstandings ... whatever you have to comment. As you may know, although
Open Source lives from contributions, they are quite rare.

This document may be outdated. As version number, I have taken the one which
this document is based on so you can easily see how outdated this document is.


1. Startup

1.1. The program flow till the splash screen

When you start up freelords, the most important things to happen are (in the
correct order):

- the configuration is loaded
- command line options are processed
- the application is initialized
- the splash screen is started up

The configuration file (see the section about Configuration for details) is
called freelordsrc and first searched in /etc, then in the user's home directory
(in this case it is called .freelordsrc). Under Windows, the config file is
assumed to be in the current directory.

For the command line options see the file main.cpp, they are (hopefully)
self-explaining, else look what is done with them during parsing.

For the initialization, a PGApplication class is created and initialized with
the resolution, the title etc.

The splash class is described in splash.cpp/splash.h. It mainly consists of a
background image, some buttons for starting or loading a game or quit the
application. The splash screen also has the responsibility for the game start
up to the point where the actual game screen is displayed. See the next
subsections for further explanations.

1.2 Starting a game

When you start a game, it happens in three steps:

- A dialog pops up for setting some game options
- a new map is created (if no loaded map is selected)
- This new map is loaded (as in loading a game)

The dialog description can be found in GamePreferencesDialog.cpp/.h. It mainly
contains many buttons and sliders for setting game options and some code to get
the settings. The player specifics are to be found in player_preferences.cpp/.h,
which also contain various widgets and some get-functions.

The creation of the map is supervised by the CreateScenario class. What happens
is: the Splash class loads the settings from the GamePreferencesDialog into the
CreateScenario class. Then it has the CreateScenario class start the map
creation. Finally, this class dumps a scenario description file (basically, and
currently even exactly, a savegame which starts at turn 0). The CreateScenario
class uses the various global lists (playerlist, stacklist etc.) during the
creation process, but clears them when it is finished. This may change in the
future (e.g. Andrea doesn't see a point in clearing all filled lists and reload
them later on, so there could come some patch in this way).

Finally, the Splash class loads the dumped scenario in the same manner as it
would load a game and starts the game. There is a slight difference between
starting and loading a game because different functions are called (e.g. when
starting a game, each player is offered a hero), but apart from the way the
actual game is started, the loading part is the same.

1.3. Loading a game

Well, I just see that there is not much to say here. The splash screen starts up
a PGFileDialog to query the file to load and then loads it (see the section 3
about loading a game).


...To be continued
