Difference between revisions of "Oolite JavaScript Reference: EquipmentInfo"

From Elite Wiki
(Added Equipment Expressions section.)
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>Object</code></small><br />
  
<small>'''Prototype:''' <code>Object</code></small><br />
−  
  +
<small>'''Subtypes:''' none</small>
−
{{Oolite-class-added|1.72}}
  
   
 
'''<code>EquipmentInfo</code>''' objects provide information about a type of equipment. To acquire an <code>EquipmentInfo</code> object, use the <code>[[#infoForKey|infoForKey]]()</code> method, as in:
  
'''<code>EquipmentInfo</code>''' objects provide information about a type of equipment. To acquire an <code>EquipmentInfo</code> object, use the <code>[[#infoForKey|infoForKey]]()</code> method, as in:
Line 8: Line 7:
 
=== Equipment Expressions ===
  
=== Equipment Expressions ===
 
Many methods can take either an <code>EquipmentInfo</code> or an equipment key. For instance, <code>ship.hasEquipment("EQ_ECM")</code> is equivalent to <code>ship.hasEquipment(EquipmentInfo.infoForKey("EQ_ECM"))</code>. In specifications, this is represented by arguments typed <code>equipmentInfoExpression</code>.
  
Many methods can take either an <code>EquipmentInfo</code> or an equipment key. For instance, <code>ship.hasEquipment("EQ_ECM")</code> is equivalent to <code>ship.hasEquipment(EquipmentInfo.infoForKey("EQ_ECM"))</code>. In specifications, this is represented by arguments typed <code>equipmentInfoExpression</code>.
−  
−
Prior to Oolite 1.74, such methods would only accept equipment keys.
  
   
 
== Properties ==
  
== Properties ==
  +
=== <code>calculatedPrice</code> ===
  +
{{oolite-prop-added|1.89}}
  +
'''calculatedPrice''' : Number (read-only nonnegative integer)
  +
If an equipment item utilises the <code>[[Oolite JavaScript Reference: Condition scripts#updateEquipmentPrice|updateEquipmentPrice()]]</code> condition script, this will be the price as calculated by that script. If no condition script is in use, the value returned will be the same as the <code>[[#price|price]]</code> property. Divide this by ten for the real value in credits.
  +
  +
=== <code>canBeDamaged</code> ===
  +
'''canBeDamaged''' : Boolean (read-only)
  +
<code>true</code> if the equipment type can be damaged (either in combat or using <code>[[Oolite JavaScript Reference: Ship#setEquipmentStatus|Ship.setEquipmentStatus()]]</code>), <code>false</code> otherwise. Currently, this is hard-coded: trumbles, passenger berths, cargo bays and external stores are invulnerable.
  +
  +
=== <code>canCarryMultiple</code> ===
  +
'''canCarryMultiple''' : Boolean (read-only)
  +
<code>true</code> if multiple instances of the equipment type can be used at once, <code>false</code> otherwise. Currently, this is hard-coded to trumbles, passenger berths and external stores.
  +
  +
=== <code>damageProbability</code> ===
  +
{{oolite-prop-added|1.77}}
  +
'''damageProbability''' : Number (read-only nonnegative)
  +
The relative probability of this item of equipment being damaged, as specified by the <code>damage_probability</code> key in [[equipment.plist]]. This is always zero for mines and missiles, and defaults to one for other equipment. The chance of a particular piece of equipment being damaged is its damageProbability divided by the total damageProbability of all remaining undamaged equipment.
  +
 
=== <code>description</code> ===
  
=== <code>description</code> ===
 
'''description''' : String (read-only)
  
'''description''' : String (read-only)
 
A short description of the equipment, as seen on the Ship Outfitting screen.
  
A short description of the equipment, as seen on the Ship Outfitting screen.
  +
  +
=== <code>displayColor</code> ===
  +
{{oolite-prop-added|1.85}}
  +
'''displayColor''' : Color (read/write)
  +
Gets and sets the color to be used for this item on the F3 Equip Ship screen, as well as the F5 Status screen. Any valid color specifier can be used. Setting a value of null will reset the color to use the default.
   
 
=== <code>effectiveTechLevel</code> ===
  
=== <code>effectiveTechLevel</code> ===
 
'''effectiveTechLevel''' : Number (read/write nonnegative integer)
  
'''effectiveTechLevel''' : Number (read/write nonnegative integer)
 
The effective tech level required to purchase this item. Unlike <code>[[#techLevel|techLevel]]</code>, this takes the special meaning of 99 and <code>TL_FOR_EQ_WHATEVER</code> mission variables into account. If the raw tech level is 99, changing the value of <code>[[#effectiveTechLevel|effectiveTechLevel]]</code> is equivalent to setting the appropriate <code>TL_FOR_EQ_WHATEVER</code> mission variable. If the raw tech level is not 99, changes to <code>[[#effectiveTechLevel|effectiveTechLevel]]</code> are ignored.<br>
  
The effective tech level required to purchase this item. Unlike <code>[[#techLevel|techLevel]]</code>, this takes the special meaning of 99 and <code>TL_FOR_EQ_WHATEVER</code> mission variables into account. If the raw tech level is 99, changing the value of <code>[[#effectiveTechLevel|effectiveTechLevel]]</code> is equivalent to setting the appropriate <code>TL_FOR_EQ_WHATEVER</code> mission variable. If the raw tech level is not 99, changes to <code>[[#effectiveTechLevel|effectiveTechLevel]]</code> are ignored.<br>
−
Starting with 1.74: Setting "effectiveTechLevel = null", will remove the corresponding <code>TL_FOR_EQ_WHATEVER</code> mission variable.
 +
Setting <code>effectiveTechLevel</code> to <code>null</code>, will remove the corresponding <code>TL_FOR_EQ_WHATEVER</code> mission variable.
   
 
'''See also: <code>[[#techLevel|techLevel]]</code>
  
'''See also: <code>[[#techLevel|techLevel]]</code>
Line 26: Line 46:
 
'''equipmentKey''' : String (read-only)
  
'''equipmentKey''' : String (read-only)
 
The equipment key for the equipment described by this <code>EquipmentInfo</code> object. For EQ_MISSILE, this is "EQ_MISSILE".
  
The equipment key for the equipment described by this <code>EquipmentInfo</code> object. For EQ_MISSILE, this is "EQ_MISSILE".
  +
  +
=== <code>fastAffinityDefensive</code> ===
  +
{{oolite-prop-added|1.79}}
  +
'''fastAffinityDefensive''' : Boolean (read-only)
  +
If this is <code>true</code>, the equipment will be preferentially assigned to the "fast activation (defensive)" key for primable equipment. This is always <code>false</code> for non-primable equipment.
  +
  +
=== <code>fastAffinityOffensive</code> ===
  +
{{oolite-prop-added|1.79}}
  +
'''fastAffinityOffensive''' : Boolean (read-only)
  +
If this is <code>true</code>, the equipment will be preferentially assigned to the "fast activation (offensive)" key for primable equipment. This is always <code>false</code> for non-primable equipment.
   
 
=== <code>incompatibleEquipment</code> ===
  
=== <code>incompatibleEquipment</code> ===
Line 35: Line 65:
 
=== <code>isAvailableToAll</code> ===
  
=== <code>isAvailableToAll</code> ===
 
'''isAvailableToAll''' : Boolean (read-only)
  
'''isAvailableToAll''' : Boolean (read-only)
  +
<code>true</code> if the equipment type can be used with any ship, regardless of its shipyard settings. It only has effect on player ships. npc ships always can have it, unless they are explicit excluded with the <code>isAvailableToNPCs</code> key.
  +
  +
=== <code>isAvailableToNPCs</code> ===
  +
'''isAvailableToNPCs''' : Boolean (read-only)
  +
<code>true</code> if the equipment type can be used by non-player ships (<code>available_to_NPCs</code> in [[equipment.plist]], default <code>true</code>).
  +
  +
=== <code>isAvailableToPlayer</code> ===
  +
'''isAvailableToPlayer''' : Boolean (read-only)
  +
<code>true</code> if the equipment type can be used by player ships (<code>available_to_player</code> in [[equipment.plist]], default <code>true</code>).
   
 
=== <code>isExternalStore</code> ===
  
=== <code>isExternalStore</code> ===
 
'''isExternalStore''' : Boolean (read-only)
  
'''isExternalStore''' : Boolean (read-only)
−
True for _MISSILE and _MINE equipment types.
  
  +
The value of the <code>is_external_store</code> equipment.plist key, if specified; otherwise, <code>true</code> for _MISSILE and _MINE equipment types, and <code>false</code> for others.
   
 
=== <code>isPortableBetweenShips</code> ===
  
=== <code>isPortableBetweenShips</code> ===
 
'''isPortableBetweenShips''' : Boolean (read-only)
  
'''isPortableBetweenShips''' : Boolean (read-only)
  +
<code>true</code> if equipment of this type is kept when buying a new ship.
  +
  +
=== <code>isVisible</code> ===
  +
'''isVisible''' : Boolean (read-only)
  +
<code>true</code> if the equipment type is visible on the ship info screen (<code>visible</code> in [[equipment.plist]], default: <code>true</code>).
   
 
=== <code>name</code> ===
  
=== <code>name</code> ===
Line 50: Line 94:
 
'''price''' : Number (read-only nonnegative integer)
  
'''price''' : Number (read-only nonnegative integer)
 
This is the value as used in the equipment.plist. Divide this by ten for the real value in credits.
  
This is the value as used in the equipment.plist. Divide this by ten for the real value in credits.
  +
  +
=== <code>provides</code> ===
  +
{{oolite-prop-added|1.81}}
  +
'''provides''' : Array (read-only)
  +
Returns an array of equipment keys which define the function(s) this equipment is providing to the ship, as defined in the <code>provides</code> element in [[equipment.plist]].
   
 
=== <code>requiredCargoSpace</code> ===
  
=== <code>requiredCargoSpace</code> ===
 
'''requiredCargoSpace''' : Number (read-only nonnegative integer)
  
'''requiredCargoSpace''' : Number (read-only nonnegative integer)
  +
Until Oolite 1.76 this was only used to decide '''if''' an item could be displayed on the equipment screen. Starting with Oolite 1.77, this key will actually make that the equipment uses cargo space when installed.
   
 
=== <code>requiresAnyEquipment</code> ===
  
=== <code>requiresAnyEquipment</code> ===
Line 102: Line 152:
   
 
=== <code>scriptInfo</code> ===
  
=== <code>scriptInfo</code> ===
−
{{Oolite-prop-future|1.74}}
  
 
'''scriptInfo''' : Object (read-only)
  
'''scriptInfo''' : Object (read-only)
 
The contents of the <code>script_info</code> key in the equipments’s ''[[equipment.plist]]'' entry, if any. This may be any [[property list]] object, but the reccomended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.
  
The contents of the <code>script_info</code> key in the equipments’s ''[[equipment.plist]]'' entry, if any. This may be any [[property list]] object, but the reccomended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.
  +
  +
=== <code>scriptName</code> ===
  +
'''scriptName''' : String (read-only)
  +
The name of an attached script.
   
 
=== <code>techLevel</code> ===
  
=== <code>techLevel</code> ===
Line 111: Line 164:
   
 
'''See also: <code>[[#effectiveTechLevel|effectiveTechLevel]]</code>
  
'''See also: <code>[[#effectiveTechLevel|effectiveTechLevel]]</code>
  +
  +
== Static properties ==
  +
=== <code>allEquipment</code> ===
  +
allEquipment : Array (EquipmentInfos, read-only)
  +
Returns a list of all known equipment types.
   
 
== Static methods ==
  
== Static methods ==
Line 117: Line 175:
 
Returns the equipment info object for a given type of equipment, or <code>null</code> for an unrecognised key. Example: <code>var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE");</code>
  
Returns the equipment info object for a given type of equipment, or <code>null</code> for an unrecognised key. Example: <code>var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE");</code>
   
−
[[Category:Oolite scripting]]
 +
[[Category:Oolite JavaScript Reference]]
  +
  +
==See also==
  +
* [[Equipment.plist]]

Latest revision as of 23:50, 1 May 2019

Prototype: Object
Subtypes: none

EquipmentInfo objects provide information about a type of equipment. To acquire an EquipmentInfo object, use the infoForKey() method, as in: 

var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE");

Equipment Expressions

Many methods can take either an EquipmentInfo or an equipment key. For instance, ship.hasEquipment("EQ_ECM") is equivalent to ship.hasEquipment(EquipmentInfo.infoForKey("EQ_ECM")). In specifications, this is represented by arguments typed equipmentInfoExpression.

Properties

calculatedPrice

This property was added in Oolite test release 1.89. 

calculatedPrice : Number (read-only nonnegative integer)

If an equipment item utilises the updateEquipmentPrice() condition script, this will be the price as calculated by that script. If no condition script is in use, the value returned will be the same as the price property. Divide this by ten for the real value in credits.

canBeDamaged

canBeDamaged : Boolean (read-only)

true if the equipment type can be damaged (either in combat or using Ship.setEquipmentStatus()), false otherwise. Currently, this is hard-coded: trumbles, passenger berths, cargo bays and external stores are invulnerable.

canCarryMultiple

canCarryMultiple : Boolean (read-only)

true if multiple instances of the equipment type can be used at once, false otherwise. Currently, this is hard-coded to trumbles, passenger berths and external stores.

damageProbability

This property was added in Oolite test release 1.77. 

damageProbability : Number (read-only nonnegative)

The relative probability of this item of equipment being damaged, as specified by the damage_probability key in equipment.plist. This is always zero for mines and missiles, and defaults to one for other equipment. The chance of a particular piece of equipment being damaged is its damageProbability divided by the total damageProbability of all remaining undamaged equipment.

description

description : String (read-only)

A short description of the equipment, as seen on the Ship Outfitting screen.

displayColor

This property was added in Oolite test release 1.85. 

displayColor : Color (read/write)

Gets and sets the color to be used for this item on the F3 Equip Ship screen, as well as the F5 Status screen. Any valid color specifier can be used. Setting a value of null will reset the color to use the default.

effectiveTechLevel

effectiveTechLevel : Number (read/write nonnegative integer)

The effective tech level required to purchase this item. Unlike techLevel, this takes the special meaning of 99 and TL_FOR_EQ_WHATEVER mission variables into account. If the raw tech level is 99, changing the value of effectiveTechLevel is equivalent to setting the appropriate TL_FOR_EQ_WHATEVER mission variable. If the raw tech level is not 99, changes to effectiveTechLevel are ignored.
Setting effectiveTechLevel to null, will remove the corresponding TL_FOR_EQ_WHATEVER mission variable.

See also: techLevel

equipmentKey

equipmentKey : String (read-only)

The equipment key for the equipment described by this EquipmentInfo object. For EQ_MISSILE, this is "EQ_MISSILE".

fastAffinityDefensive

This property was added in Oolite test release 1.79. 

fastAffinityDefensive : Boolean (read-only)

If this is true, the equipment will be preferentially assigned to the "fast activation (defensive)" key for primable equipment. This is always false for non-primable equipment.

fastAffinityOffensive

This property was added in Oolite test release 1.79. 

fastAffinityOffensive : Boolean (read-only)

If this is true, the equipment will be preferentially assigned to the "fast activation (offensive)" key for primable equipment. This is always false for non-primable equipment.

incompatibleEquipment

incompatibleEquipment : Array (read-only)

An array of equipment keys (in arbitrary order). In order to be installed, no item in this array may already be installed.

See also: requiresAnyEquipment, requiresEquipment

isAvailableToAll

isAvailableToAll : Boolean (read-only)

true if the equipment type can be used with any ship, regardless of its shipyard settings. It only has effect on player ships. npc ships always can have it, unless they are explicit excluded with the isAvailableToNPCs key.

isAvailableToNPCs

isAvailableToNPCs : Boolean (read-only)

true if the equipment type can be used by non-player ships (available_to_NPCs in equipment.plist, default true).

isAvailableToPlayer

isAvailableToPlayer : Boolean (read-only)

true if the equipment type can be used by player ships (available_to_player in equipment.plist, default true).

isExternalStore

isExternalStore : Boolean (read-only)

The value of the is_external_store equipment.plist key, if specified; otherwise, true for _MISSILE and _MINE equipment types, and false for others.

isPortableBetweenShips

isPortableBetweenShips : Boolean (read-only)

true if equipment of this type is kept when buying a new ship.

isVisible

isVisible : Boolean (read-only)

true if the equipment type is visible on the ship info screen (visible in equipment.plist, default: true).

name

name : String (read-only)

The display name for the equipment described by this EquipmentInfo object. This string is localized. For EQ_MISSILE in English, this is "Missile".

price

price : Number (read-only nonnegative integer)

This is the value as used in the equipment.plist. Divide this by ten for the real value in credits.

provides

This property was added in Oolite test release 1.81. 

provides : Array (read-only)

Returns an array of equipment keys which define the function(s) this equipment is providing to the ship, as defined in the provides element in equipment.plist.

requiredCargoSpace

requiredCargoSpace : Number (read-only nonnegative integer)

Until Oolite 1.76 this was only used to decide if an item could be displayed on the equipment screen. Starting with Oolite 1.77, this key will actually make that the equipment uses cargo space when installed.

requiresAnyEquipment

requiresAnyEquipment : Array (read-only)

An array of equipment keys (in arbitrary order). In order to be installed, at least one item in this array must already be installed.

See also: incompatibleEquipment, requiresEquipment

requiresCleanLegalRecord

requiresCleanLegalRecord : Boolean (read-only)

See also: requiresNonCleanLegalRecord

requiresEmptyPylon

requiresEmptyPylon : Boolean (read-only)

True for equipment that requires at least one pylon to have nothing on it.

See also: requiresMountedPylon

requiresEquipment

requiresEquipment : Array (read-only)

An array of equipment keys (in arbitrary order). In order to be installed, all items in this array must already be installed.

See also: incompatibleEquipment, requiresAnyEquipment

requiresFreePassengerBerth

requiresFreePassengerBerth : Boolean (read-only)

requiresFullFuel

requiresFullFuel : Boolean (read-only)

See also: requiresNonFullFuel

requiresMountedPylon

requiresMountedPylon : Boolean (read-only)

True for equipment that requires at least one pylon to have a store (missile, mine or equipment) on it.

See also: requiresEmptyPylon

requiresNonCleanLegalRecord

requiresNonCleanLegalRecord : Boolean (read-only)

See also: requiresCleanLegalRecord

requiresNonFullFuel

requiresNonFullFuel : Boolean (read-only)

See also: requiresFullFuel

scriptInfo

scriptInfo : Object (read-only)

The contents of the script_info key in the equipments’s equipment.plist entry, if any. This may be any property list object, but the reccomended approach is to use a dictionary whose keys have a unique prefix (such as you should be using for file names, ship names etc.). A property list dictionary is converted to a JavaScript object with properties corresponding to the dictionary’s keys. All other property list types used with Oolite have directly corresponding JavaScript types.

scriptName

scriptName : String (read-only)

The name of an attached script.

techLevel

techLevel : Number (read-only nonnegative integer)

The raw tech level required to purchase this item. Unlike effectiveTechLevel, this does not take the special meaning of 99 and TL_FOR_EQ_WHATEVER mission variables into account.

See also: effectiveTechLevel

Static properties

allEquipment

allEquipment : Array (EquipmentInfos, read-only)

Returns a list of all known equipment types.

Static methods

infoForKey

function infoForKey(equipmentKey : String) : EquipmentInfo

Returns the equipment info object for a given type of equipment, or null for an unrecognised key. Example: var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE");

See also

Retrieved from "http://backup.witchspacewiki.org/index.php?title=Oolite_JavaScript_Reference:_EquipmentInfo&oldid=58005"