Creating Freeciv scenarios
==========================

Overview:
---------
Freeciv scenario -files are essentially savegames with specific game
situation. The savegame format allows some things that are useful only
when the savegame in question is a scenario. There's a [scenario] section
with some parameters applicable to scenario saves only, and possibility
to include some lua script for scripting the scenario.
The deciding difference between regular savegames and scenario savegames
is that latter have is_scenario set to TRUE in [scenario] section.
Freeciv saves current game situation as a scenario file, with the full
[scenario] section, when one saves by the /scensave server command or
uses "Save Scenario" from the client Edit -menu.


Compatibility:
--------------
Freeciv can load savegames saved by older versions. How far back this
is supported depends on version. Scenario files are often not updated
to the latest savegame format version, but can be of such older version.
When editing such older format savegames, one needs to be consistent
with the format version. One cannot use features of the newer format
in older format savegame even though freeciv server can load both
older format and newer format.
This document describes the current format of the freeciv version it
comes with. Some things described here should not be used when
editing savegames with older format.


[scenario] section:
-------------------
Savegame [scenario] section can have following fields

- is_scenario
  Always TRUE in a scenario savegame

- name
  Name of the scenario

- authors
  Text listing authors of the scenario

- description
  Description of the scenario

- save_random
  Whether random number state is saved to the scenario

- players
  Whether player information is saved to the scenario, or is it map-only
  scenario

- startpos_nations
  Whether nations should use start positions defined in the scenario map

- prevent_new_cities
  Is founding new cities prevented in the scenario, locking it to cities
  present on the map

- lake_flooding
  Should ocean tiles connecting to a lake tile flood the lake tile.
  Default is TRUE, and it's discouraged to disable it in new scenarios.
  This possibility to disable flooding exist for supporting older
  scenario maps created before flooding feature came to being, and which
  would now work badly with the flooding enabled. New scenario maps
  should be designed from the beginning so that the lake flooding is
  not an issue.

- handmade
  Set to TRUE when savegame file is manually edited. This has no gameplay
  effect, but it indicates that scenario might have some properties that
  are not yet supported in the editor. When editing such a scenario in the
  editor, warning is shown that some properties might get lost

- allow_ai_type_fallback
  Is it ok to fallback to another player AI type if one defined in the
  scenario file is not available when scenario is loaded

- ruleset_locked
  Is the scenario locked to one specific ruleset. Default is TRUE

- ruleset_caps
  When scenario is not ruleset_locked, this capability string defines
  required capabilities of compatible rulesets

- datafile
  Luadata to load. See chapter 'Luadata' for details


[player<num>] section additions:
--------------------------------
When saved in scenario mode, player sections have additional field:

- autoselect_weight
  When a user (client) connects, and there are free players with autoselect_weight
  above zero, user gets automatically attached to one of those. The exact weight
  determines how likely each of them is to get automatically chosen.


Luadata:
--------
Some rulesets have a lua script that can parse special luadata file
to adjust their behavior. Such luadata file can be provided by the
ruleset itself, or by the scenario using the ruleset. This is controlled
by 'datafile' field in the scenario savegames [scenario] section.
- If the field is omitted, ruleset's own luadata is used, if present
- If field has value 'None' (case insensitive), luadata is not used
  at all, as if it was not present even in the ruleset
- Any other value of datafile is considered prefix part of a filename
  of form <prefix>.luadata to use as the luadata file. The file must
  be found from the freeciv's savegame path, usually from the same
  directory where the scenario savegame itself is.
