Latest revision as of 17:27, 3 September 2024

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.

oolitefont.plist

There is one of these tucked away inside Deepspace Ships oxp v.1.20. It is mostly full of nothing but numbers and is tied in with SimonB's New-font.png hiding inside the Textures folder.
It seems to work on my AppleMac (Oolite v.1.90), replacing edgepixel's Dangerous Square in my ManagedAddOns folder. (Cholmondely)

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 the list of world script event handlers.

Use

Its function is to attach more than one worldscript to an oxp. On startup, Oolite looks first if there is a "world-scripts.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 "world-scripts.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 the official release, and a growing number of test releases. In those times you could have both a "script.plist" and a "script.js" alongside each other in the Config 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.
*/

@@ Line 1: / Line 1: @@
+----
 =crosshairs.[[plist]]=
 == Structure ==
-The file is organized as a dictionary of crosshairs with the weapon name as its key. Each weapon crosshair itself consist of an array of line segments. Each line segment is represented by an array of 6 numbers.
+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.
+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
@@ Line 15: / Line 16: @@
   	(0.25, -0.75, 0.0,		0.75, -0.50, 0.0)
   );
-The crosshair.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]]
+The crosshairs.plist is not intended to be changed by an OXP. For custom crosshairs it is intended to add a <code>crosshair</code> 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. <code>oxpname_crosshairs1.plist</code>). Crosshairs may be included by a HUD definition, or switched in and out by [[Oolite_JavaScript_Reference:_PlayerShip#crosshairs|scripting]].
+----
 =descriptions.[[plist]]=
@@ Line 43: / Line 48: @@
 == 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]].
+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:
@@ Line 49: / Line 54: @@
   You have to pick up [parcelnumbers] parcels.
-Whenever Oolite reads in a scriptline, missiontext or description, it first looks for something between brackets. If is finds something it looks if it is a mission_variable. If yes, is 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.
+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 reeds in all descriptions.plist lines on startup in one big file. This means that you can use keywords from other OXP's or from Oolite itself. If there are some key's with duplicate names, it uses  the last. This means that you must use unique keywords.
+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 [[OXP Distribution#General|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,
+,  1,
+,  0,
+, -1,
+, -2,
+, -2,
+,  0,
+                 -1, -2,
+                 -2, -2,
+                 -2, -1,
+                 -1,  0,
+                 -2,  1,
+                 -2,  2,
+                 -1,  2,
+,  0,
+,  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==
@@ Line 70: / Line 110: @@
 ==Use==
-Its function is to select witch ships to show on the startup screen when a new commander is chosen.
+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==
@@ Line 85: / Line 128: @@
 ==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'' [[User:Mandoman|Mandoman]]'s many oxps.
+----
+=oolitefont.[[plist]]=
+There is one of these tucked away inside [[Deepspace Ships]] oxp v.1.20. It is mostly full of nothing but numbers and is tied in with SimonB's New-font.png hiding inside the Textures folder. <br>
+It seems to work on my AppleMac (Oolite v.1.90), replacing edgepixel's [[Font: Dangerous Square|Dangerous Square]] in my ManagedAddOns folder. ([[User:Cholmondely|Cholmondely]])
+----
 =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==
@@ Line 109: / Line 167: @@
 [[Media:pirate-victim-roles.zip|''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 th 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.
+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 testverion of the oxp: "foo". This oxp is intended for personal use only, don't spread."
+    "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 constant aware that he is using a test version of the oxp.
+Only useful for test versions to make the user constantly aware that he is using a test version of the oxp.
-=worldScripts.[[plist]]=
+----
+=world-scripts.[[plist]]=
 ==Structure==
@@ Line 133: / Line 195: @@
     "my_script3.plist"
   )
+==Content==
+To know what to put into such a world script, see [[Oolite_JavaScript_Reference:_World_script_event_handlers|the list of 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".
+Its function is to attach more than one worldscript to an oxp. On startup, Oolite looks first if there is a "world-scripts.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 "world-scripts.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:
+)    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 the official release, and a growing number of test releases. In those times you could have both a "script.plist" and a "script.js" alongside each other in the Config 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.<br>
+)    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. [https://bb.oolite.space/viewtopic.php?p=170774#p170774 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:
+<pre>
+/*	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.
+*/
+</pre>
 [[Category:Oolite scripting]]
+----
+=See also=
+* [[OXP howto]]

Difference between revisions of "Misc plists"

Latest revision as of 17:27, 3 September 2024

Contents

crosshairs.plist

Structure

descriptions.plist

Structure

Use

Example

demoships.plist

Structure

Use

illegal_goods.plist

Structure

Use

info.plist

oolitefont.plist

pirate-victim-roles.plist

Structure

Use

OXPMessages.plist

Structure

Use

world-scripts.plist

Structure

Content

Use

Note

whitelist.plist

Structure

Use

See also

Navigation menu

Views

Personal tools

Navigation

Search

Tools