Difference between revisions of "Scenarios.plist"

From Elite Wiki
m (category)
(Adjust page, add scenario restrictions from 1.81)
Line 10: Line 10:
 
  }
 
  }
  
==description==
+
==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.
 
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==
+
===file===
 
The filename of the scenario file, which should be placed in the <code>Scenarios</code> 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.
 
The filename of the scenario file, which should be placed in the <code>Scenarios</code> 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==
+
===model===
 
The data key of the model in <code>shipdata.plist</code> to be used for this scenario on the selection screen. This key must either:
 
The data key of the model in <code>shipdata.plist</code> to be used for this scenario on the selection screen. This key must either:
 
* exist in the core [[shipdata.plist]]
 
* exist in the core [[shipdata.plist]]
Line 23: Line 24:
 
It is optional - if omitted, no model will be shown.
 
It is optional - if omitted, no model will be shown.
  
==name==
+
===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.
 
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==
+
===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 [[Oolite_JavaScript_Reference:_Player#endScenario|player.endScenario]] at that point to end the game. The key here must exactly match the one used in the call to <code>player.endScenario()</code>.
 
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 [[Oolite_JavaScript_Reference:_Player#endScenario|player.endScenario]] at that point to end the game. The key here must exactly match the one used in the call to <code>player.endScenario()</code>.
  
 
This key is optional; if it is omitted, it will be impossible to end the game using that script function.
 
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
 +
* "'''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 <code>requires_oxps</code> list (but ''not'' ones only in <code>optional_oxps</code>) will be loaded. No others will be.
 +
* "'''tag:'''tagname". OXP groups. Any OXPs with that tag in the tag list in their [[manifest.plist]]s, and any OXPs in their <code>requires_oxps</code> list (but ''not'' ones only in <code>optional_oxps</code>) 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"
  
 
[[Category:Oolite]]
 
[[Category:Oolite]]
 
[[Category:Oolite scripting]]
 
[[Category:Oolite scripting]]

Revision as of 21:00, 10 August 2014

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
  • "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"