Misc plists

crosshairs.plist

Structure

The file is organized as a dictionary of crosshairs with the weapon name as its key. The key 'OTHER' can be used for weapons not otherwise defined by the crosshairs dictionary. Each weapon crosshair itself consists of an array of line segments. Each line segment is represented by an array of 6 numbers. Example of a line segment:

(W1, X1, Y1,    W2, X2, Y2)

The line will start at X1,Y1 with a relative width W1 and ends at X2, Y2 with relative width W2. All coordinates must lie between -1 and +1, while the widths are between 0 and 1

Example:

WEAPON_NONE =
(
	(0.25, 0.75, 0.0,		0.75, 0.50, 0.0),
	(0.25, -0.75, 0.0,		0.75, -0.50, 0.0)
);

The crosshairs.plist is not intended to be changed by an OXP. For custom crosshairs it is intended to add a crosshair entry in the custom HUD definition itself. This will then override the default crosshairs for that HUD. (See hud.plist).

In 1.77 or later, custom crosshairs files may be defined. These have the same syntax as crosshairs.plist, but should have a different unique name (e.g. oxpname_crosshairs1.plist). Crosshairs may be included by a HUD definition, or switched in and out by scripting.

descriptions.plist

Structure

The file is organized as a dictionary with pairs of key and value (string or array). It has the same structure as the missiontext.plist and it also resides in the config folder inside the OXP.

Example XML:

<dict>
   <key>parcelnumbers</key>
   <array>
       <string>two</string>
       <string>three</string>
       <string>four</string>
       <string>five</string>
       <string>six</string>
   </array>
</dict>

Example OpenStep:

{
  parcelnumbers = ("two", "three", "four", "five", "six");
}

Use

Its use must be seen as a kind of variable. The key part is the variable name and the string part is the content of the variable. If you use an array of strings the variable will return a random choice of one of the strings. And this is the main use of the descriptions.plist: creation of text with variable content. See also string expansion. Note that for compatibility, the random number used to determine which choice to use from an array is only 1 byte long. Therefore if the array has more than 256 entries there will be some entries which can never be picked, and if it has a number of entries which is not a power of two the entries will not have equal chances of being picked (though if the number of entries is small, the difference in chances is not significant)

The text itself is invoked by using the key-word between square brackets, like:

You have to pick up [parcelnumbers] parcels.

Whenever Oolite reads in a scriptline, missiontext or description, it first looks for something between brackets. If it finds something it looks to see if it is a mission_variable. If yes, it replaces the name of the variable with its content. Then it looks in the descriptions.plist. If it finds a key, it replaces the name with the string content. If it is an array it picks at random one of the strings.

Be aware that Oolite reads in all descriptions.plist lines on startup in one big file. This means that you can use keywords from other OXPs or from Oolite itself. If there are some keys with duplicate names, it uses the last. This means that you must use unique keywords.

demoships.plist

Structure

The file is organized as an array. Every entry consists of a string, with the name of a ship. The shipname must correspond with a key inside the shipdata.plist. It resides in the config folder inside the OXP.

Example XML:

<array>
       <string>my_ship1</string>
       <string>my_ship2</string>
</array>

Example OpenStep:

(
  "my_ship1",
  "my_ship2"
)

Use

Its function is to select which ships to show on the startup screen when a new commander is chosen.

illegal_goods.plist

Note: The commodities.plist file is no longer used from Oolite 1.82 and following.

Structure

The file is organized as a dictionary. Every entry consists of a key and a number. The key says which goods are illegal, and the number how illegal the goods are.

Example OpenStep:

{
   Firearms = 1;
   Narcotics = 2;
   Slaves = 1;
}

Use

Better never use this as it might change the game to much.

pirate-victim-roles.plist

In 1.79 this is superseded by role-categories.plist and should no longer be used for new OXPs. Existing files will continue to have the effect documented below.

Structure

The file is organized as an array. Every entry consists of a string, with the name of a shiprole. This plist is introduced with Oolite version 1.70

Example XML:

<array>
       <string>my_shiprole1</string>
       <string>my_shiprole2</string>
</array>

Example OpenStep:

(
  "my_shiprole1",
  "my_shiprole2"
)

Use

Pirates use the function scanForNearestMerchantman and scanForRandomMerchantman. With pre 1.70 versions this function only finds ships with role trader and player. Starting with 1.70 these two functions finds all ships that are included in the pirate-victim-roles.plist. This makes it possible to add ships in their own role that are recognized by pirates as traders. Ship designers are encouraged to use this pirate-victim-roles.plist and add all private roles that should act trader like for better interaction with pirate groups.

Download a custom pirate-victim-roles.plist

OXPMessages.plist

Structure

The file is organized as an array of strings. When the plist is present, the content of the strings is written to the log on start-up and the player sees a message on the start-up screen that the oxp "foo" contains a message. This plist is introduced with Oolite version 1.74. It should be placed direct in the main directory level of the oxp, were also the 'requires.plist' is situated.

Example OpenStep:

(
  "This is a copy of my own testversion of the oxp: "foo". This oxp is intended for personal use only, don't spread."
)

Use

Only useful for test versions to make the user constantly aware that he is using a test version of the oxp.

world-scripts.plist

Structure

The file is organized as an array. Every entry consists of a string, with the name of a script. The name must correspond with a file inside the Scripts folder inside the OXP.

Example:

(
  "my_script1.js",
  "my_script2.js",
  "my_script3.plist"
)

Use

Its function is to attach more than one wordScript to an oxp. On startup, Oolite looks first if there is a worldScripts.plist file. When present the scripts inside are used as world scripts. These scripts can be both js script files or legacy script plist files. Even a mix is allowed. Only when the worldScripts.plist is not present, Oolite looks for a file with the name "script.js" in the Config folder. And when that is not present it looks for the file "script.plist".

whitelist.plist

Structure

The file is organized as a dictionary of keys with the values being themselves either arrays of strings or dictionaries of key-value pairs.

Use

The file is included with Oolite. OXPs are restricted from using legacy features that are not included in the whitelist. As of Oolite 1.89, the file starts with the following comment:

/*	Methods that may be used from old-style script actions or conditions.
	
	This plist cannot be extended or overriden by OXPs.
	
	action_methods				Commands permitted in world scripts.
	ai_methods					Commands permitted in AIs.
	ai_and_action_methods		Commands permitted in world scripts and AIs.
	query_methods				Values that may be queried in script conditions.
	action_method_aliases		Mappings from script commands (left) to internal names (right).
	ai_method_aliases			Mappings from AI commands (left) to internal names (right).
	query_method_aliases		Mappings from script queries (left) to internal names (right).
	shader_*_binding_methods	Values that may be queried through shader bindings.
	
	Most other types of legacy script - ship actions, character scripts,
	scriptActionOnTarget: - can use both action_methods and ai_methods. The exception is
	systeminfo scripts, which can't use ai_methods as they aren't run with a ship target.
*/

See also

• OXP howto