Difference between revisions of "Oolite JavaScript Reference: Condition scripts"

From Elite Wiki
m (Condition scripts: Clarify interaction with legacy conditions)
(allowAwardEquipment: context parameter)
Line 11: Line 11:
 
This method is called when the game engine needs to know whether a particular ship can have equipment fitted. This may be because the player is looking at possible upgrades at a station, 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. If the method does not exist, or returns a value other than <code>false</code>, then the equipment may be added or offered for sale (subject to other conditions, of course)
 
This method is called when the game engine needs to know whether a particular ship can have equipment fitted. This may be because the player is looking at possible upgrades at a station, 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. If the method does not exist, or returns a value other than <code>false</code>, then the equipment may be added or offered for sale (subject to other conditions, of course)
   
this.allowAwardEquipment = function(eqKey, ship)
 
  +
<code>context</code> will be one of:
  +
* "newShip" - equipment for a ship in a station shipyard (F3 F3)
  +
* "npc" - awarding equipment to NPC on ship setup
  +
* "purchase" - equipment for purchase on the F3 screen
  +
* "scripted" - 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)
  +
  +
this.allowAwardEquipment = function(eqKey, ship, context)
 
{
 
{
 
// your code here
 
// your code here

Revision as of 17:40, 18 November 2012

NOTE: This page documents a feature planned for Oolite 1.77, which is potentially subject to significant change before then.

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 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 this._property

allowAwardEquipment

This method was added in Oolite test release 1.77.

This method is called when the game engine needs to know whether a particular ship can have equipment fitted. This may be because the player is looking at possible upgrades at a station, or from a call to ship.canAwardEquipment or ship.awardEquipment, or for other similar reasons. The equipment key and a reference to the ship entity are passed as parameters. If the method does not exist, or returns a value other than false, then the equipment may be added or offered for sale (subject to other conditions, of course)

context will be one of:

  • "newShip" - equipment for a ship in a station shipyard (F3 F3)
  • "npc" - awarding equipment to NPC on ship setup
  • "purchase" - equipment for purchase on the F3 screen
  • "scripted" - 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)

this.allowAwardEquipment = function(eqKey, ship, context)
{
  // your code here
  return bool;
}

allowOfferShip

This method was added in Oolite test release 1.77.

This method is called when the game engine is considering adding a ship managed by this condition script to a shipyard. If the method does not exist, or returns a value other than false, then the ship may appear for sale (or it may not, for a variety of other reasons). The ship key from shipyard.plist is passed as a parameter.

this.allowOfferShip = function(shipKey)
{
  // your code here
  return bool;
}

allowSpawnShip

This method was added in Oolite test release 1.77.

This method is called when the game engine is considering spawning a ship managed by this condition script. If the method does not exist, or returns a value other than false, then the ship may be spawned (or it may not, if another ship with the appropriate role is selected instead). The ship key from shipdata.plist is passed as a parameter.

this.allowSpawnShip = function(shipKey)
{
  // your code here
  return bool;
}