Oolite JavaScript Reference: Condition scripts - Revision history

Phkb: Updating BB links

2024-02-29T02:18:38Z

Updating BB links

Alnivel: /* allowAwardEquipment */ Added how to add "oolite-barred-equipment" support for oxp equipment

2023-04-10T14:14:41Z

‎allowAwardEquipment: Added how to add "oolite-barred-equipment" support for oxp equipment

Massively Locked: uniform string format

2022-11-07T18:17:47Z

uniform string format

Massively Locked: replaced "function" (x7)

2022-10-29T14:59:24Z

replaced "function" (x7)

Massively Locked: /* allowShowLibraryShip */ uniform boolean format

2022-10-27T22:21:35Z

‎allowShowLibraryShip: uniform boolean format

Cholmondely: Added Links

2022-07-25T04:13:18Z

Added Links

Phkb: /* allowAwardEquipment */

2022-07-23T07:20:41Z

‎allowAwardEquipment

Phkb: /* allowAwardEquipment */

2022-07-23T07:12:19Z

‎allowAwardEquipment

Phkb: /* allowAwardEquipment */

2022-07-23T07:04:01Z

‎allowAwardEquipment

Cim: 1.81 update

2015-04-18T10:18:22Z

1.81 update

@@ Line 98: / Line 98: @@
 == Links ==
-There is an extended bulletin board discussion with a couple of examples [http://www.aegidian.org/bb/viewtopic.php?p=286037#p286037 here] (2022).
+There is an extended bulletin board discussion with a couple of examples [https://bb.oolite.space/viewtopic.php?p=286037#p286037 here] (2022).
 [[Category:Oolite JavaScript Reference]]

← Older revision		Revision as of 14:14, 10 April 2023
Line 33:		Line 33:

	On a station, this would prevent it selling military lasers. On a ship in 1.79 or later, this would also stop the ship fitting military lasers.		On a station, this would prevent it selling military lasers. On a ship in 1.79 or later, this would also stop the ship fitting military lasers.
		+
		+	If you want to allow your equipment to be barred in the same way, you can either set the <code>condition_script</code> property to use the standart <code>"oolite-conditions.js"</code> script, or add the following snippet to the <code>allowAwardEquipment</code> of your condition script:
		+	// OXP hook to allow stations to forbid specific equipment
		+	if(context == "purchase" && player.ship.dockedStation && player.ship.dockedStation.scriptInfo["oolite-barred-equipment"])
		+	{
		+	if (player.ship.dockedStation.scriptInfo["oolite-barred-equipment"].indexOf(equipment) != -1)
		+	{
		+	return false;
		+	};
		+
		+	// OXP hook to allow ships to forbid specific "available to all" equipment
		+	if(ship.scriptInfo && ship.scriptInfo["oolite-barred-equipment"] && ship.scriptInfo["oolite-barred-equipment"].indexOf(equipment) != -1)
		+	{
		+	return false;
		+	};

	=== allowOfferShip ===		=== allowOfferShip ===

@@ Line 14: / Line 14: @@
 <code>context</code> will be one of:
-* "newShip" - equipment for a ship in a station shipyard (F3 F3)
+* <code>"newShip"</code> - equipment for a ship in a station shipyard (F3 F3)
-* "npc" - awarding equipment to NPC on ship setup
+* <code>"npc"</code> - awarding equipment to NPC on ship setup
-* "purchase" - equipment for purchase on the F3 screen
+* <code>"purchase"</code> - equipment for purchase on the F3 screen
-* "scripted" - equipment added by JS or legacy scripts
+* <code>"scripted"</code> - equipment added by JS or legacy scripts
-(Context can in theory also be "loading", "damage" or "portable", but if you see one of these, it's a bug)
+(Context can in theory also be <code>"loading"</code>, <code>"damage"</code> or <code>"portable"</code>, but if you see one of these, it's a bug)
   this.allowAwardEquipment = function(eqKey, ship, context)
@@ Line 26: / Line 26: @@
+  }
-The standard condition script for the core game equipment allows equipment to be barred using the "<code>oolite-barred-equipment</code>" key in <code>script_info</code>. If this key contains an array of equipment keys, then those items of equipment will not be sold at this station. In 1.79 and later, this <code>script_info</code> key may be applied to any ship, preventing those items being installed onto the ship. For example:
+The standard condition script for the core game equipment allows equipment to be barred using the <code>"oolite-barred-equipment"</code> key in <code>script_info</code>. If this key contains an array of equipment keys, then those items of equipment will not be sold at this station. In 1.79 and later, this <code>script_info</code> key may be applied to any ship, preventing those items being installed onto the ship. For example:
   script_info = {

@@ Line 2: / Line 2: @@
 Condition scripts are used to set conditions on the appearance of ships and equipment beyond the basics possible in [[shipdata.plist]], [[shipyard.plist]], [[shiplibrary.plist]] and [[equipment.plist]]. They have a similar purpose to the "conditions" parameters in those plists, which use the legacy scripting engine, but have the full flexibility of the Javascript scripting engine. If both "conditions" and a condition script are specified for the same item, they will both be tested (but you should never need to do this).
-Conditions scripts may define any or all of the following functions. There is a single instance of each condition script regardless of how many ships and equipment items use it, so variables may be shared between calls in <code>this._property</code>
+Conditions scripts may define any or all of the following methods. There is a single instance of each condition script regardless of how many ships and equipment items use it, so variables may be shared between calls in <code>this._property</code>
 In 1.81 the scripts are extended slightly to modify ''how'' things may appear as well as whether they may appear.
@@ Line 9: / Line 9: @@
 {{oolite-method-added|1.77}}
-In order for this function to be called, the <code>condition_script</code> property of an equipment item (as declared in the [[Equipment.plist]] file) must be specified, it must declare the name of the Javascript file where the function exists, and the function must exist in the referenced JavaScript file. The function will only be called for the equipment items which reference the condition script.
+In order for this method to be called, the <code>condition_script</code> property of an equipment item (as declared in the [[Equipment.plist]] file) must be specified, it must declare the name of the Javascript file where the method exists, and the method must exist in the referenced JavaScript file. The method will only be called for the equipment items which reference the condition script.
-This method is called when the game engine needs to know whether a particular ship can have equipment fitted. In other words, it is asking whether to allow equipment to be awarded to a ship. This may be because the player is looking at possible upgrades at a station (on the F3 Equip Ship screen), or from a call to [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.canAwardEquipment]] or [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.awardEquipment]], or for other similar reasons. The equipment key and a reference to the ship entity are passed as parameters. You would use this function to control if, and under what conditions, a piece of equipment is offered for purchase and installation. Returning a value of <code>true</code> would indicate that the equipment can be installed; returning a value of <code>false</code> indicates the equipment can't be installed and so it won't appear on the F3 Equip Ship screen, and any of the JavaScript methods to add the equipment item would fail. If the method does not exist, or returns a value other than <code>false</code>, then a value of <code>true</code> is assumed and the equipment may be added or offered for sale (subject to other conditions, of course, like TL constraints)
+This method is called when the game engine needs to know whether a particular ship can have equipment fitted. In other words, it is asking whether to allow equipment to be awarded to a ship. This may be because the player is looking at possible upgrades at a station (on the F3 Equip Ship screen), or from a call to [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.canAwardEquipment]] or [[Oolite_JavaScript_Reference:_Ship#canAwardEquipment|ship.awardEquipment]], or for other similar reasons. The equipment key and a reference to the ship entity are passed as parameters. You would use this method to control if, and under what conditions, a piece of equipment is offered for purchase and installation. Returning a value of <code>true</code> would indicate that the equipment can be installed; returning a value of <code>false</code> indicates the equipment can't be installed and so it won't appear on the F3 Equip Ship screen, and any of the JavaScript methods to add the equipment item would fail. If the method does not exist, or returns a value other than <code>false</code>, then a value of <code>true</code> is assumed and the equipment may be added or offered for sale (subject to other conditions, of course, like TL constraints)
 <code>context</code> will be one of:
@@ Line 78: / Line 78: @@
+  }
-This function is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.
+This method is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.

@@ Line 48: / Line 48: @@
 {{oolite-method-added|1.81}}
-This method is called when the ship library is being shown in-game (rather than on the start screen) and determines whether the ship appears on the list for the player to view. If the method does not exist or returns a value which cannot be interpreted as a boolean it will be assumed to have returned true.
+This method is called when the ship library is being shown in-game (rather than on the start screen) and determines whether the ship appears on the list for the player to view. If the method does not exist or returns a value which cannot be interpreted as a boolean, it will be assumed to have returned <code>true</code>.
   this.allowShowLibraryShip = function(shipKey)

@@ Line 1: / Line 1: @@
-=Condition scripts=
+== Condition scripts ==
 Condition scripts are used to set conditions on the appearance of ships and equipment beyond the basics possible in [[shipdata.plist]], [[shipyard.plist]], [[shiplibrary.plist]] and [[equipment.plist]]. They have a similar purpose to the "conditions" parameters in those plists, which use the legacy scripting engine, but have the full flexibility of the Javascript scripting engine. If both "conditions" and a condition script are specified for the same item, they will both be tested (but you should never need to do this).
 Conditions scripts may define any or all of the following functions. There is a single instance of each condition script regardless of how many ships and equipment items use it, so variables may be shared between calls in <code>this._property</code>
-In 1.81 the scripts are extended slightly to modify how things may appear as well as whether they may appear.
+In 1.81 the scripts are extended slightly to modify ''how'' things may appear as well as whether they may appear.
-==allowAwardEquipment==
+=== allowAwardEquipment ===
 {{oolite-method-added|1.77}}
@@ Line 34: / Line 34: @@
 On a station, this would prevent it selling military lasers. On a ship in 1.79 or later, this would also stop the ship fitting military lasers.
-==allowOfferShip==
+=== allowOfferShip ===
 {{oolite-method-added|1.77}}
@@ Line 45: / Line 45: @@
+  }
-==allowShowLibraryShip==
+=== allowShowLibraryShip ===
 {{oolite-method-added|1.81}}
@@ Line 56: / Line 56: @@
+  }
-==allowSpawnShip==
+=== allowSpawnShip ===
 {{oolite-method-added|1.77}}
@@ Line 67: / Line 67: @@
+  }
-==updateEquipmentPrice==
+=== updateEquipmentPrice ===
 {{oolite-method-added|1.81}}
@@ Line 80: / Line 80: @@
 This function is called before [[Shipdata.plist#equipment_price_factor|equipment_price_factor]] is considered.
 [[Category:Oolite JavaScript Reference]]