Scenarios.plist

The scenarios.plist file, from Oolite 1.79 onwards, lists the initial starting scenario files available to the player when starting a new commander.

It is a list of dictionaries with the following format:

	{
		"file" = "oolite-tutorial.oolite-save";
		"name" = "[oolite-scenario-tutorial-name]";
		"description" = "[oolite-scenario-tutorial-description]";
		"model" = "coriolis-station";
		"scenario" = "oolite-tutorial";
	}

Plist keys

description

A text description, which will be expanded with the usual description expansion rules, summarising the scenario in a few hundred characters. Optional but strongly recommended.

file

The filename of the scenario file, which should be placed in the Scenarios folder of the OXP. A scenario file is simply an Oolite save game: you will probably find the debug console extremely useful for setting up the scenario. In general when creating scenarios you should not have any OXPs installed other than those absolutely necessary for the OXP containing the scenario, to prevent unwanted mission variables and similar items from appearing in the scenario file.

model

The data key of the model in shipdata.plist to be used for this scenario on the selection screen. This key must either:

• exist in the core shipdata.plist
• exist in your OXP's shipdata.plist
• exist in the shipdata.plist of an OXP you explicitly require to be installed through the manifest.plist

It is optional - if omitted, no model will be shown.

name

The name of the scenario, expanded with the usual description expansion rules. This is the name which will be shown in the selection list.

scenario

This key sets up the name of the scenario. If you intend the scenario to be a completely self-contained event, with a definite ending, rather than simply an alternative start position or set up for the player, then you will probably want to call player.endScenario at that point to end the game. The key here must exactly match the one used in the call to player.endScenario().

This key is optional; if it is omitted, it will be impossible to end the game using that script function.

Special Scenario Features

OXP restrictions

In Oolite 1.81 onwards, scenarios may be restricted to include only particular OXPs. Since changing the OXP set while a game is loaded is impractical, this requires directly editing the save game file. Look for the key

<key>scenario_restriction</key>
<string></string>

Edit this to include the restriction you want - e.g.

<key>scenario_restriction</key>
<string>id:oxp.oolite.myname.myoxp</string>

and save the file.

The following restriction types are available:

• "" (Empty string). The default - all OXPs are available except those with the tag "oolite-scenario-only" in their tag list
• "strict". Strict mode - no OXPs are available
• "id:identifier". Single OXP. The OXP with that identifier in its manifest.plist, and any OXPs in its requires_oxps list (but not ones only in optional_oxps) will be loaded. No others will be.
• "tag:tagname". OXP groups. Any OXPs with that tag in the tag list in their manifest.plists, and any OXPs in their requires_oxps list (but not ones only in optional_oxps) will be loaded. No others will be.

(If A requires B, which itself requires C, then both B and C will be loaded if A is allowed)

The Oolite Tutorial has the restriction "tag:oolite-tutorial-compatible"

Scenario-only OXPs

Normally an OXP will always be loaded unless excluded by the scenario. For OXPs which make major changes, it may only be appropriate to load them in particular scenarios and not in normal play. This can be achieved by adding the tag "oolite-scenario-only" to the tag list, as well as the tag or identifier required by the scenario.

Note that the "start new game" screen itself operates in 'default' mode, so the OXP which defines the scenario cannot have the "oolite-scenario-only" tag, or require an OXP which does, or the scenario will never actually be visible. A small "loader" OXP which contains only the scenarios must be used. (The main scenario OXP probably should require the loader OXP to make sure that it gets installed)