Oolite JavaScript Reference: 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 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 this._property

In 1.81 the scripts are extended slightly to modify how things may appear as well as whether they may appear.

allowAwardEquipment

This method was added in Oolite test release 1.77.

In order for this method to be called, the condition_script 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 ship.canAwardEquipment or 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 true would indicate that the equipment can be installed; returning a value of false 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 false, then a value of true is assumed and the equipment may be added or offered for sale (subject to other conditions, of course, like TL constraints)

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;
}

The standard condition script for the core game equipment allows equipment to be barred using the "oolite-barred-equipment" key in script_info. 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 script_info key may be applied to any ship, preventing those items being installed onto the ship. For example:

script_info = {
  "oolite-barred-equipment" = ("EQ_WEAPON_MILITARY_LASER");
}

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 condition_script property to use the standart "oolite-conditions.js" script, or add the following snippet to the allowAwardEquipment 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

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;
}

allowShowLibraryShip

This method was added in Oolite test release 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.allowShowLibraryShip = 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;
}

updateEquipmentPrice

This method was added in Oolite test release 1.81.

This method is called when the game engine needs to know the price of fitting equipment covered by this condition script. The method takes an equipment key and the current price as parameters, and must return a non-negative number for the actual price of the equipment.

this.updateEquipmentPrice = function(equipmentKey, currentPrice)
{
  // your code here
  return newPrice;
}

This method is called before equipment_price_factor is considered.

Links

• There is an extended bulletin board discussion with a couple of examples here (Scripter's Cove thread, 2022).

• Various equipment questions (2015) includes discussions of condition scripts with examples as well as notes on equipment sort order.

Examples

See Hiran's Index which includes all the scripts from the Expansions Manager's OXZs'

Markets

• Risk Based Economy OXP - overall: lower profits in safe systems, better profits in dangerous ones.
• Risky Business - major differences in prices in dangerous systems for just one or two commodities.
• Demand Driven Economy - severely curtails how much can be sold in a system, with F7 hints as to what systems actually want to import.
• Darkside Moonshine Distillery - price of new whiskey commodity depends on distance from distilleries
• SW Economy - introduces a 3rd economic pole (mining worlds) & 3 commodities; and economy size, TL & planet radius affect commodity production
• AristoShares - introduces shares paying regular dividends
• Javascript code for decaying Radioactives over time is currently here: Talk:Radioactives

Equipment & Shipyards

• Riredi OXP - ensures that Coluber ships are on sale in the Coluber station shipyard
• Weapon Laws - prevents weapons being sold in the safer political systems.
• Category:Missiles & Bombs - includes weapons doing peculiar things such as force-hyperjumping another ship, stunning it, creating a miniature black hole etc.
• Ship Configuration OXP - horrendously complex OXP adding 300 pieces of equipment (many variants on the vanilla equipment) including complexities such as heat sinks. There are 13 scripts controlling what goes on.
• Config for AddOns (Library OXP) allows the player to configure your OXP - for example units of measurement for MFDs or whether one needs to land on the planet to service one's ship (Planetfall2 OXP).

• See Category:Weapons OXPs & Category:Equipment OXPs for links to other wiki pages of lists or OXPs with ideas to copy (Aggressive weapons, defensive equipment, astrogatory, propulsive, mercantile, etc.).