Difference between revisions of "Oolite JavaScript Reference: EquipmentInfo"
| (34 intermediate revisions by 6 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> | ||
'''<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: | ||
var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE"); | var missileInfo = EquipmentInfo.infoForKey("EQ_MISSILE"); | ||
| + | |||
| + | === 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>. | ||
== 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 | + | A short description of the equipment, as seen on the Outfitting (F3) 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 Outfitting (F3) and Status (F5) screens. Any valid [[Materials in Oolite#Colour specifiers|color specifier]] can be used. Setting a value of <code>null</code> 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> | + | 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</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</code> are ignored.<br> |
| + | 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> |
=== <code>equipmentKey</code> === | === <code>equipmentKey</code> === | ||
'''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 <code>"EQ_MISSILE"</code>. |
| + | |||
| + | === <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 28: | 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) | ||
| − | + | 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 Status (F5) screen (<code>visible</code> in [[equipment.plist]], default: <code>true</code>). | ||
=== <code>name</code> === | === <code>name</code> === | ||
'''name''' : String (read-only) | '''name''' : String (read-only) | ||
| − | The display name for the equipment described by this <code>EquipmentInfo</code> object. This string is localized. For EQ_MISSILE in English, this is "Missile". | + | The display name for the equipment described by this <code>EquipmentInfo</code> object. This string is localized. For EQ_MISSILE in English, this is <code>"Missile"</code>. |
=== <code>price</code> === | === <code>price</code> === | ||
'''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. | ||
| + | |||
| + | === <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 Outfitting (F3) screen. Starting with 1.77, this key will actually ensure that the equipment uses cargo space when installed. | ||
=== <code>requiresAnyEquipment</code> === | === <code>requiresAnyEquipment</code> === | ||
| Line 59: | Line 117: | ||
=== <code>requiresEmptyPylon</code> === | === <code>requiresEmptyPylon</code> === | ||
'''requiresEmptyPylon''' : Boolean (read-only) | '''requiresEmptyPylon''' : Boolean (read-only) | ||
| − | + | <code>true</code> for equipment that requires at least one pylon to have nothing on it. | |
'''See also:''' <code>[[#requiresMountedPylon|requiresMountedPylon]]</code> | '''See also:''' <code>[[#requiresMountedPylon|requiresMountedPylon]]</code> | ||
| Line 79: | Line 137: | ||
=== <code>requiresMountedPylon</code> === | === <code>requiresMountedPylon</code> === | ||
'''requiresMountedPylon''' : Boolean (read-only) | '''requiresMountedPylon''' : Boolean (read-only) | ||
| − | + | <code>true</code> for equipment that requires at least one pylon to have a store (missile, mine or equipment) on it. | |
'''See also:''' <code>[[#requiresEmptyPylon|requiresEmptyPylon]]</code> | '''See also:''' <code>[[#requiresEmptyPylon|requiresEmptyPylon]]</code> | ||
| Line 92: | Line 150: | ||
'''See also:''' <code>[[#requiresFullFuel|requiresFullFuel]]</code> | '''See also:''' <code>[[#requiresFullFuel|requiresFullFuel]]</code> | ||
| + | |||
| + | === <code>scriptInfo</code> === | ||
| + | '''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. | ||
| + | |||
| + | === <code>scriptName</code> === | ||
| + | '''scriptName''' : String (read-only) | ||
| + | The name of an attached script. | ||
=== <code>techLevel</code> === | === <code>techLevel</code> === | ||
| Line 97: | Line 163: | ||
The raw tech level required to purchase this item. Unlike <code>[[#effectiveTechLevel|effectiveTechLevel]]</code>, this does not take the special meaning of 99 and <code>TL_FOR_EQ_WHATEVER</code> mission variables into account. | The raw tech level required to purchase this item. Unlike <code>[[#effectiveTechLevel|effectiveTechLevel]]</code>, this does not take the special meaning of 99 and <code>TL_FOR_EQ_WHATEVER</code> mission variables into account. | ||
| − | '''See also: <code>[[#effectiveTechLevel|effectiveTechLevel]]</code> | + | '''See also:''' <code>[[#effectiveTechLevel|effectiveTechLevel]]</code> |
| + | |||
| + | === <code>weaponInfo</code> === | ||
| + | {{oolite-prop-added|1.91}} | ||
| + | '''weaponInfo''' : Object (read-only) | ||
| + | Provides access to the <code>weapon_info</code> section of the equipment item (if defined). | ||
| + | |||
| + | == Static properties == | ||
| + | === <code>allEquipment</code> === | ||
| + | allEquipment : Array (EquipmentInfos, read-only) | ||
| + | Returns a list of all known equipment types. | ||
== Static methods == | == Static methods == | ||
| Line 104: | Line 180: | ||
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 | + | [[Category:Oolite JavaScript Reference]] |
| + | |||
| + | ==See also== | ||
| + | * [[Equipment.plist]] | ||
Latest revision as of 00:27, 14 December 2023
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");
Contents
- 1 Equipment Expressions
- 2 Properties
- 2.1 calculatedPrice
- 2.2 canBeDamaged
- 2.3 canCarryMultiple
- 2.4 damageProbability
- 2.5 description
- 2.6 displayColor
- 2.7 effectiveTechLevel
- 2.8 equipmentKey
- 2.9 fastAffinityDefensive
- 2.10 fastAffinityOffensive
- 2.11 incompatibleEquipment
- 2.12 isAvailableToAll
- 2.13 isAvailableToNPCs
- 2.14 isAvailableToPlayer
- 2.15 isExternalStore
- 2.16 isPortableBetweenShips
- 2.17 isVisible
- 2.18 name
- 2.19 price
- 2.20 provides
- 2.21 requiredCargoSpace
- 2.22 requiresAnyEquipment
- 2.23 requiresCleanLegalRecord
- 2.24 requiresEmptyPylon
- 2.25 requiresEquipment
- 2.26 requiresFreePassengerBerth
- 2.27 requiresFullFuel
- 2.28 requiresMountedPylon
- 2.29 requiresNonCleanLegalRecord
- 2.30 requiresNonFullFuel
- 2.31 scriptInfo
- 2.32 scriptName
- 2.33 techLevel
- 2.34 weaponInfo
- 3 Static properties
- 4 Static methods
- 5 See also
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 Outfitting (F3) 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 Outfitting (F3) and Status (F5) screens. 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 Status (F5) 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 Outfitting (F3) screen. Starting with 1.77, this key will actually ensure 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
weaponInfo
This property was added in Oolite test release 1.91.
weaponInfo : Object (read-only)
Provides access to the weapon_info section of the equipment item (if defined).
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");
