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";
	}

Overview

Scenario support has been significantly upgraded to let expansion authors make full use of it as their imaginations permit.

Expansion packs can now be restricted to only load in their own Scenarios, which means you can make much bigger changes than before without needing to worry about compatibility with other packs, and do things which just wouldn't have worked before.

• Make a mini-series of mission OXPs which wouldn't work if the player could bring their own ship and experience, or wander off mid-mission to go and trade for a bit.
• Set the player in the middle of a major war between powers with definite front lines, regions, and battles - can they still make a living as a trader, pirate or bounty hunter when there's a full-scale Thargoid invasion on, and hundreds of systems have already completely fallen to them.
• Completely rewrite the galaxies, ships, equipment and rules to make your own new space game with the Oolite engine.

(from "Features Introduced" in Oolite v.1.82 on Oolite.space's whatsnew/v1.82)

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 method.

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.
• "exc:plist". Core plist exclusion. This prevents the core Oolite plist with this filename being loaded when merging plists. For example, exc:world-scripts.plist will prevent any of the normal Oolite world-scripts being loaded unless they are listed in the OXPs world-scripts.plist. (Plists which cannot be overridden by OXP can not be excluded by this method, and neither can logcontrol.plist). Note that Oolite may require particular values to be set in the merged plist (e.g. trade-goods.plist must contain "alloys", "minerals" and "slaves" keys, to represent the cargo scooped up in hull debris, splinters, and escape pods respectively) - an OXP which excludes the core plist is responsible for ensuring that all essential values are redefined.

Restriction types other than default and strict mode may be combined by using ';' as a separator, e.g.

<key>scenario_restriction</key>
<string>id:oxp.oolite.myname.myoxp;exc:shipyard.plist;exc:role-categories.plist</string>

(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 in its manifest.plist, 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)

Links

• Cim on the aim of Scenarios.plists (2017)

Examples

Currently (2023) the only examples are SOTL Exploration & SOTL Altmap, both by Cim. They each require his Loader OXZ.