Misc plists

From Elite Wiki
Revision as of 16:47, 30 November 2013 by Cim (talk | contribs) (Use: Warn against too-large arrays)

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)

Here is X1,Y1 the starting point of the line segment and W1 its relative width. And X2, Y2 is than the endpoint with W2 the relative with at the end. 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 than 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). These 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

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.

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

See also