Author: Ulf Lorenz
version: 0.1.7
Date: 2004-07-01

This document describes the format of a freelords save game. The idea is to 
store this information, so that later on you can easily write and implement a
converter for save games.


0.3.3 (more verbose army saving)

the army tags now include new data:
    <d_defense>: the defense value of the army
    <d_maxhp>: the maximum hp value of this unit

-------------------------------------------------------------------------------
0.3.2 (added events, removed d_buildings)

- the scenario tag now contains a new subtag named event. The event has some 
specific data and contains one or more reaction tags. The tags added are:

<event>
    <d_type>listed below</d_type>
    <d_active>whether the event is finished or not</d_active>
    <reaction>
        ...one or more reactions...
    </reaction>
</event>

- the events have the following additional data tags:
  EKILLALL:         none
  EPLAYERDEAD:      <d_player>: the id of the player
  ECITYCONQUERED:   <d_city>: the id of the city
  EPCITYCONQUERED:  <d_player>: the id of the conqueror
                    <d_city>: the id of the conquered city
  EARMYKILLED:      <d_army>: the id of the army we watch
  EROUND:           <d_round>: the round the event waits for
  EPROUND:          <d_round>: the round the event waits for
                    <d_player>: the player whose turn it waits for
  ERUINSEARCH:      <d_ruin>: the id of the ruin to be searched

- the reactions look like this:

<reaction>
    <d_type>see below</d_type>
       ...one or more additional tags...
</reaction>

Reaction types and their data tags are:
    RENDGAME:       none
    RMESSAGE:       <d_message>: The message string to be displayed
    RADDGOLD:       <d_player>: The player who gets the gold
                    <d_gold>: how much gold the player gets
   

- the <d_buildings> tag of the map tag was removed without replacement

-------------------------------------------------------------------------------
0.3.1a

- added boolean value "turnmode" to GameScenario tag (didn't change version
number, this is downwards compatible)

-------------------------------------------------------------------------------
0.3.1 (changed city production)

- the city production is no longer stored in the format "type1 type2 type3 type4",
but "armyset1 id1 armyset2 id2..." where armyset is the string of the armyset.

-------------------------------------------------------------------------------
0.3.0 (added tileset)

- the map tag now includes a tileset data tag

-------------------------------------------------------------------------------
0.2.7 (changed stacklist)

- stacklist is no longer a separate main tag, but instead it is a subtag of a
player, i.e. each player has his own stacklist of his own armies and saves
them together with the player himself
-------------------------------------------------------------------------------
0.2.6 (added hero class)

- added a tag <hero> which behaves the same like an <army> tag, but includes an 
additional data tag "d_name" of type string

-------------------------------------------------------------------------------
0.2.5 (added d_size)

- in <map> section, added the data tag "d_size", which stores the size in tiles
of the map

-------------------------------------------------------------------------------
0.2.4 (new "counter" tag)

- added a tag counter with one data tag called d_curID containing an integer

-------------------------------------------------------------------------------
0.2.3 (new action tag)

- added new action tag with data tags "d_type" (value: "ACTION_CITY_PILLAGE")
and city_id (id of pillaged city)

-------------------------------------------------------------------------------
0.2.2 (new data tags)

- all data tags now start with a "d_" before their name

-------------------------------------------------------------------------------
0.2.1 (version tag + conformity)

- a '<?xml version="1.0"?>' is now added at the front of a save file

- the first tag (and any other basic, i.e. not sub-, tags, but for now there is
only one, namely "freelords") now has a member called version. All other tags
no longer have a version information

-------------------------------------------------------------------------------
0.2.0 (some changes to the action tags)

action of type "ACTION_CITY_OCCUPY", "ACTION_CITY_RAZE",
    "ACTION_CITY_UPGRADE_DEFENSE", "ACTION_CITY_BUY_PRODUCTION",
    "ACTION_CITY_CHANGE_PRODUCTION"
    - member "city" renamed to "city_id"

-------------------------------------------------------------------------------
0.1.7 (first appearance of save games)

The format is xml style. The tags are displayed here as they appear in the
save game. The text in between the tags are comments. Each tag has a version 
number, i.e. a tag named <freelords> in reality looks like
<freelords version="0.1.7">. All version numbers here are 0.1.7. Exceptions are
data storing values, i.e. tags that don't mark a section but have data in
between. They are indicated by a "!d" in their tag. So e.g. if you have a
section like this:

<player>
    <!d id> id of the player </id>
    <!d name> name of the player </name>
    ...
</player>

This means that there is a tag <player version="0.1.7">. Inside are data tags.
They contain e.g. a tag "id" which doesn't have a version since it only contains
data and a data tag "name". The text in between is an explanation and will in 
reality look like "<name> Michael </name>" for a player called Michael.
Order does not matter, but due to a necessary limitation in the
parser all data has to stand before the first sub tag, i.e. if e.g. a ruin
contains a stack, the location, searched etc. tags have to appear before the
stack begins.



<freelords>
    <scenario>
        <!d name> name of the scenario  </name>
        <!d type> type of a scenario. The types stand in common/GameScenario.h.
                    They should be by now
                        1 for a scenario
                        2 for a single player game
                        3 for a multiplayer host
                        4 for a multiplayer client
                    (type GameScenario::GameType)
            </type>
        <turn> the current turn number of the scenario  </turn>
    </scenario>
    <map>
        <!d types>
            First, there is a newline sign at the end of the string.
            Following this is a long long row of numbers indicating the type of
            terrain. The saving goes [0,0],[1,0],[2,0],...[0,1],[1,1] etc., i.e.
            first column 0, then column 1 etc.
            The numbers for the terrain:
                0   grass
                1   water
                2   forest
                3   hills
                4   mountains
                5   swamp
            each column ends with a newline
        </types>
        <!d variations>
            Work exactly like the types field, but the variation number is
            stored here. Some tile types have more than one image, which one is
            saved in this tag
        <variations>
    </map>
    <playerlist>
        <!d size>   the size of the playerlist  </size>
        <!d active> the id of the active player </active>
        <player>
            <!d id> the id of the player    </id>
            <!d name>   the name of the player;
                        the neutral player has the name "Neutral"   </name>
            <!d color>  the rgb values for the player separated by spaces;
                        e.g. "255 0 152"                       </color>
            <!d armyset>   the name of the player's armyset    </armyset>
            <!d gold>      the gold owned by the player        </gold>
            <!d dead>      "true", if player is dead, "false"if not </dead>
            <!d type>   the type of the player
                        0   human player
                        1   ai player of type AI_Fast
                        2   ai player of type AI_Dummy
                        3   neutral player
                        </type>
            <action>
                The only tag equal to all action types is the tag "type".
                Everything else depends on the type of the action. The whole
                actionlist of a player comes here with as many tags as
                necessary. I'll write an action tag for each type here as a
                sample. BTW, the type is always a string.
            </action>
            
            <action>
                <!d type>ACTION_STACK_FIGHT</tag>
                <!d attacker>   the attacker id </attacker>
                <!d defender>   the defender id </defender>
                <!d a_damage>   a space-separated list of eight values
                                indicating the damage done to the attacker
                                stack. If a stack has <8 armies, the resulting
                                fields are filled with zeros
                                </a_damage>
                <!d d_damage>   the same for the defenders  </d_damage>
            </action>
            
            <action>
                <!d type>ACTION_STACK_SPLIT</type>
                <!d orig_army>  the id of the original stack </orig_army>
                <!d new_army>   the id of the freshly created stack  </new_army>
                <!d moved>      a space-separated list of the 8 figures.
                                They describe the id's of the armies which have
                                been added to stack new_army. If <8 armies
                                have moved, the rest of the fields are filled
                                with zeros
                                </moved>
            </action>

            <action>
                <!d type>ACTION_STACK_JOIN</type>
                <!d receiver>   the id of the army which survives the joining
                                </receiver>
                <!d joining>    the id of the army which is destroyd after the
                                joining
                                </joining>
            </action>

            <action>
                <!d type>ACTION_STACK_FIGHT_CITY</type>
                <!d attackers>  the space separated id's of the attackers
                                (at this time only 1)
                                </attackers>
                <!d defenders>  the same for he defenders (max 4)
                                </defenders>
                <!d att_damage> a space separated list of all damage received
                                by the attackers. The first 8 values are for the
                                armies of the first attacker, the next 8 values
                                for the second etc. Non-existing amies have the
                                value 0.
                                </att_damage>
                <!d def_damage> the same for the defenders  </def_damage>
            </action>

            <action>
                <!d type>ACTION_STACK_MOVED_ONE_STEP</type>
                <!d stack>  the id of the stack             </stack>
                <!d x>      x position of the destination   </x>
                <!d y>      y position of the destination   </y>
            </action>

            <action>
                <!d type>ACTION_CITY_OCCUPY</type>
                <!d city>   the id of the occupied city </city>
            </action>

            <action>
                <!d type>ACTION_CITY_RAZE</type>
                <!d city>   the id of the burnt down city   </city>
            </action>

            <action>
                <!d type>ACTION_STACK_SEARCH_RUIN</type>
                <!d ruin>       the id of the searched ruin     </ruin>
                <!d seeker>     the id of the searching stack   </seeker>
                <!d searched>   has the keeper been defeated and the ruin
                                successfully searched?
                                </searched>
                <!d seeker_damage>  space separated list of the damage of the
                                    exploring stack
                                    </seeker_damage>
                <!d keeper_damage>  the same for the ruin keeper
                                    </keeper_damage>
            </action>

            <action>
                <!d type>ACTION_STACK_VISIT_TEMPLE</type>
                <!d temple> the id of the visited temple    </temple>
                <!d stack>  the id of the visiting stack    </stack>
            </action>

            <action>
                <!d type>ACTION_CITY_UPGRADE_DEFENSE</type>
                <!d city> the id of the affected city   </city>
            </action>

            <action>
                <!d type>ACTION_CITY_BUY_PRODUCTION</type>
                <!d city>       the id of the affected city </city>
                <!d production> the number of the unit bought (first unit in the
                                armyset definition is 0, second 1 etc.)
                                </production>
            </action>

            <action>
                <!d type>ACTION_CITY_CHANGE_PRODUCTION</type>
                <!d city>       the id of the affected city     </city>
                <!d production> the slot number of the selected production
                                (<0 none, 0 first slot etc.)
                                </production>
            </action>

            <action>
                <!d type>ACTION_REWARD</type>
                <!d reward_type>    the type, e.g. gold, artifacts, experience..
                                    stored as number!
                                    </reward_type>
                <!d reward_subtype> further detailed things about the type;
                                    at the time of this, only gold (type 1,
                                    subtype 0) exists.
                                    </reward_subtype>
                <!d reward_amount>  the amount of the reward    </reward_amount>
                
        </player>

        ...more players...
        
    </playerlist>

    <citylist>
        <!d size>   the number of cities in this list   </size>

        <city>
            <!d id>     the id of the city              </id>
            <!d name>   the name of the city            </name>
            <!d x>      x position of the city          </x>
            <!d y>      y position of the city          </y>
            <!d owner>  id of the city's owning player  </owner>
            <!d duration>   how many turns before the current production is
                            finished, "-1" if no production is set
                            </duration>
            <!d armytype>   4 space separated values describing the army types
                            for the production slots 0-3. "-1" if the production
                            slot is empty
                            </armytype>
            <!d production> which production slot is currently selected?
                            "-1" if production is set to none
                            </production>
            <!d gold>       how much gold the city provides each turn   </gold>
            <!d burnt>      is the city burnt to ashes?     </burnt>
            <!d defense>    defense level of the city       </defense>
        </city>

        ...more cities...
    </citylist>

    <templelist>
        <!d size>   the number of temples   </size>

        <temple>
            <!d id>     the id of the temple        </id>
            <!d name>   the name of the temple      </name>
            <!d x>      x position of the temple    </x>
            <!d y>      y position of the temple    </y>
        </temple>

        ...more temples...
    </templelist>

    <ruinlist>
        <!d size>   the number of ruins    </size>

        <ruin>
            <!d id>         the id of the ruin              </id>
            <!d name>       the name of the ruin            </name>
            <!d x>          x position of the ruin          </x>
            <!d y>          y position of the ruin          </y>
            <!d searched>   has the uin been searched yet?  </searched>
            <stack>
                ....
                Here follows a complete description of the stack which guards
                the ruin. Since this is exactly the same as in the stacklist,
                look there to find out how the description goes. The armyset
                for these stacks is "default"
                ....
            </stack>
        </ruin>

        ...more ruins...
    </ruinlist>

    <stacklist>
        <!d size>   the size of the stacklist           </size>
        <!d active> the id of the current activestack   </active>

        <stack>
            <!d id>         the id of the stack         </id>
            <!d player>     the id of the stack's player, 0 means no player
                            (if the stack e.g guards a ruin)
                            </player>
            <!d x>          x position of the stack     </x>
            <!d y>          y position of the stack     </y>
            <!d defending>  is the stack defending? (defending stacks will be
                            ignored if the player clicks on "next stack")
                            </defending>
            
            <path>
                <!d size>   how many items does the path contain    </size>
                <!d x>      a space separated list of all x coordinates (in
                            order) of the path's items
                            </x>
                <!d y>      the same for the y coordinates          </y>
            </path>

            The following tags describe the armies the stack consists of. Order
            counts here, i.e. the first tag actually represents the first army
            in the stack.
            
            <army>
                <!d id>         the id of the army                  </id>
                <!d type>       the type of the army (0 means first army type of
                                the armyset, 1 second etc.)
                                </type>
                <!d hp>         how many hp the army has left       </hp>
                <!d moves>      how many moves the army has left    </moves>
                <!d strength>   the attack strength of the army     </strength>
                <!d xp>         the experience points of the army   </xp>
                <!d level>      the experience level of the army    </level>
                <!d blessed>    is the army already blessed?        </blessed>
            </army>

            ...more armies...
        </stack>

        ...more stacks...
    </stacklist>
</freelords>
