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.

Example

First adding categories to the Ship Library/View Ship specifications screen; then adding a missile icon; and finally adding mission text: this is the entire descriptions.plist

{
	"oolite-ship-library-category-black_mamba"		= "Black Mamba";
	"oolite-ship-library-category-plural-black_mamba"	= "Black Mambas";

"EQ_X_SWORD_MISSILE" =
         (
                 2,  2,
	         2,  1,                                 
                 1,  0,
		 2, -1,	
                 2, -2,                             
                 1, -2,
                 0,  0,
                -1, -2,
                -2, -2,
                -2, -1,
                -1,  0,
                -2,  1,
                -2,  2,
                -1,  2,
                 0,  0,
                 1,  2       
	);
   "XS_MI_STAGE_245" = "The Murderer is at Digebiti.";
   "XS_MI_STAGE_G7_1" = "Just in time, Commander. I could use a little help here!";
}

---

demoships.plist

In 1.79 and following this is superseded by Shiplibrary.plist and should no longer be used for OXPs. It was used to project the ship on the new commander screen at game start. Its replacement adds the ship/station etc to the ship information on the "View Ship Library" page when Oolite starts up (and to the "View ship specifications" page on the docked F4 screen)

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. It has been superseded by the Trade-goods.plist

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.

---

info.plist

This does not actually seem to do anything other than give the human being reading it some information! Galactic Navy OXP has one, as do inter alia Mandoman's many oxps.

---

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 directly in the main directory level of the oxp where the 'requires.plist' is also situated.

Example OpenStep:

(
  "This is a copy of my own test version 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"
)

Content

To know what to put into such a world script, see Oolite_JavaScript_Reference:_World_script_event_handlers

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

Note

There are two ways of storing a JS worldscript:

1) Old: You can name it "script.js" and put it into the Config folder. That's what cim did in his Galactic Misjump OXP. It's a leftover of "legacy" plist scripting, where the script had to be named "script.plist" and reside in the Config folder. This way was especially useful in the time when we had Oolite 1.65 as official release, and the growing number of test releases. In those times you could have both a "script.plist" and a "script.js" alongside each other in the Confic folder. Oolite 1.65 would use the plist script, and the later versions would ignore the plist and use the JS script instead. This functionality is not particularly useful anymore, but it still exists.
2) New: You can name it whatever you want (but perhaps not "script.js") and put it into the Script folder. Then you have to create another plist in the Config folder named "world-scripts.plist" and write the name of your script into that plist. This method has the advantage that you can have more than one worldscript in an OXP, which is of course not possible with the first method, because there can only be one file named "script.js" in a Config folder. Commander McLane (2012)

---

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