Difference between revisions of "Oolite JavaScript Reference: PlayerShip"
(→hudHidden) |
|||
(81 intermediate revisions by 4 users not shown) | |||
Line 7: | Line 7: | ||
== Properties == | == Properties == | ||
+ | === <code>activeMissile</code> === | ||
+ | {{oolite-prop-added|1.89}} | ||
+ | '''activeMissile''' : Number (read-only integer) | ||
+ | Index in the [[Oolite_JavaScript_Reference:_Ship#missiles|<code>missiles</code>]] array of the currently selected missile. | ||
+ | |||
=== <code>aftShield</code> === | === <code>aftShield</code> === | ||
'''aftShield''' : Number (read/write, nonnegative) | '''aftShield''' : Number (read/write, nonnegative) | ||
Line 19: | Line 24: | ||
'''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code> | '''See also''': <code>[[#aftShield|aftShield]]</code>, <code>[[#forwardShieldRechargeRate|forwardShieldRechargeRate]]</code>, <code>[[#maxAftShield|maxAftShield]]</code> | ||
− | === <code> | + | === <code>chartHighlightMode</code> === |
− | + | {{oolite-prop-added|1.87}} | |
− | |||
− | + | '''chartHighlightMode''' : String (read/write) | |
− | ''' | + | Gets/sets the type of highlight being shown on the galactic chart. Can be any one of the following: |
− | + | * <code>"OOLRC_MODE_SUNCOLOR"</code> | |
+ | * <code>"OOLRC_MODE_ECONOMY"</code> | ||
+ | * <code>"OOLRC_MODE_GOVERNMENT"</code> | ||
+ | * <code>"OOLRC_MODE_TECHLEVEL"</code> | ||
=== <code>compassMode</code> === | === <code>compassMode</code> === | ||
− | '''compassMode''' : String (read-only) | + | '''compassMode''' : String (read-only in 1.84 and earlier, read/write in 1.85 and later) |
− | + | Gets/sets the current compass mode, which can be any one of the following: | |
− | * COMPASS_MODE_BASIC | + | * <code>"COMPASS_MODE_BASIC"</code> |
− | * COMPASS_MODE_PLANET | + | * <code>"COMPASS_MODE_PLANET"</code> |
− | * COMPASS_MODE_STATION | + | * <code>"COMPASS_MODE_STATION"</code> |
− | * COMPASS_MODE_SUN | + | * <code>"COMPASS_MODE_SUN"</code> |
− | * COMPASS_MODE_TARGET | + | * <code>"COMPASS_MODE_TARGET"</code> |
− | * COMPASS_MODE_BEACONS | + | * <code>"COMPASS_MODE_BEACONS"</code> |
=== <code>compassTarget</code> === | === <code>compassTarget</code> === | ||
− | '''compassTarget''' : Entity(read-only) | + | '''compassTarget''' : Entity(read-only in 1.84 and earlier, read/write in 1.85 and later) |
− | + | Gets/sets the entity currently targeted by the compass. When setting this value, the entity must be valid, and have a compass beacon. | |
+ | |||
+ | === <code>compassType</code> === | ||
+ | '''compassType''' : String (read-only in 1.84 and earlier, read/write in 1.85 and later) | ||
+ | Gets/sets the current space compass type, which can be one of the following: | ||
+ | * <code>"OO_COMPASSTYPE_BASIC"</code> | ||
+ | * <code>"OO_COMPASSTYPE_ADVANCED"</code> | ||
=== <code>crosshairs</code> === | === <code>crosshairs</code> === | ||
Line 53: | Line 66: | ||
A shortcut property to whichever of [[Oolite_JavaScript_Reference:_Ship#aftWeapon|aftWeapon]], [[Oolite_JavaScript_Reference:_Ship#forwardWeapon|forwardWeapon]], [[Oolite_JavaScript_Reference:_Ship#portWeapon|portWeapon]] or [[Oolite_JavaScript_Reference:_Ship#starboardWeapon|starboardWeapon]] is the currently active player weapon. | A shortcut property to whichever of [[Oolite_JavaScript_Reference:_Ship#aftWeapon|aftWeapon]], [[Oolite_JavaScript_Reference:_Ship#forwardWeapon|forwardWeapon]], [[Oolite_JavaScript_Reference:_Ship#portWeapon|portWeapon]] or [[Oolite_JavaScript_Reference:_Ship#starboardWeapon|starboardWeapon]] is the currently active player weapon. | ||
− | If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null | + | If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be <code>null</code> and attempting to write to it will give an error. |
=== <code>cursorCoordinates</code> === | === <code>cursorCoordinates</code> === | ||
Line 66: | Line 79: | ||
=== <code>docked</code> === | === <code>docked</code> === | ||
'''docked''' : Boolean (read-only) | '''docked''' : Boolean (read-only) | ||
− | + | <code>true</code> if the player is docked with a station or carrier. | |
=== <code>dockedStation</code> === | === <code>dockedStation</code> === | ||
'''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only) | '''dockedStation''' : [[Oolite JavaScript Reference: Station|Station]] (read-only) | ||
The station with which the player is currently docked. | The station with which the player is currently docked. | ||
+ | |||
+ | === <code>extraCargo</code> === | ||
+ | {{Oolite-prop-added|1.79}} | ||
+ | '''extraCargo''' : Number (read-only integer) | ||
+ | The amount the <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code> increases when a [[Cargo Bay Expansion]] is installed. The corresponding ''shipdata.plist'' key is <code>[[Shipdata.plist#extra_cargo|extra_cargo]]</code>. Note that although this property can be used to check non-player ships, it only contains the value for the player ship. | ||
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, | ||
+ | <code>[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]]</code> | ||
=== <code>fastEquipmentA</code> === | === <code>fastEquipmentA</code> === | ||
− | {{oolite-prop-added|1. | + | {{oolite-prop-added|1.79}} |
− | '''fastEquipmentA''' : | + | '''fastEquipmentA''' : String (read/write) |
Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity defensive slot (default key: 0). | Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity defensive slot (default key: 0). | ||
=== <code>fastEquipmentB</code> === | === <code>fastEquipmentB</code> === | ||
− | {{oolite-prop-added|1. | + | {{oolite-prop-added|1.79}} |
− | '''fastEquipmentB''' : | + | '''fastEquipmentB''' : String (read/write) |
Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity offensive slot (default key: TAB). | Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity offensive slot (default key: TAB). | ||
Line 137: | Line 158: | ||
Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines. | Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines. | ||
− | If <code>hudHidden</code> is true this will also be true | + | If <code>hudHidden</code> is <code>true</code>, this will also be <code>true</code> even if the HUD would not normally allow a big GUI. |
=== <code>hudHidden</code> === | === <code>hudHidden</code> === | ||
'''hudHidden''' : Boolean (read/write) | '''hudHidden''' : Boolean (read/write) | ||
Whether the HUD should be visible. | Whether the HUD should be visible. | ||
+ | Care should be taken when making the HUD invisible with this property. While invisible, any comms messages or console messages will not be seen by the player until the HUD is made visible again. | ||
=== <code>hyperspaceSpinTime</code> === | === <code>hyperspaceSpinTime</code> === | ||
{{oolite-prop-added|1.77}} | {{oolite-prop-added|1.77}} | ||
+ | |||
'''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81) | '''hyperspaceSpinTime''' : Number (read-only, read/write in 1.81) | ||
The length of the ship's hyperspace countdown. | The length of the ship's hyperspace countdown. | ||
Line 151: | Line 174: | ||
=== <code>infoSystem</code> === | === <code>infoSystem</code> === | ||
+ | {{oolite-prop-added|1.83}} | ||
− | |||
'''infoSystem''' : Number (read/write) | '''infoSystem''' : Number (read/write) | ||
The ID of the system shown in the system (F7) screen. | The ID of the system shown in the system (F7) screen. | ||
Line 158: | Line 181: | ||
=== <code>injectorsEngaged</code> === | === <code>injectorsEngaged</code> === | ||
{{Oolite-prop-added|1.81}} | {{Oolite-prop-added|1.81}} | ||
+ | |||
'''injectorsEngaged''' : Boolean(read-only) | '''injectorsEngaged''' : Boolean(read-only) | ||
− | Is the player ship currently using fuel injection. | + | Is the player ship currently using [[Witch Fuel Injectors|fuel injection]]. |
=== <code>manifest</code> === | === <code>manifest</code> === | ||
'''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write) | '''manifest''' : [[Oolite JavaScript Reference: Manifest|Manifest]] (read/write) | ||
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own. | The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class [[Oolite JavaScript Reference: Manifest|Manifest]] of its own. | ||
+ | |||
+ | '''Example:''' | ||
+ | // addressed as a property of playerShip | ||
+ | player.ship.manifest.food = 5 | ||
+ | // addressed as a class of its own | ||
+ | manifest.food = 5 | ||
+ | |||
+ | '''See also''': <code>[[#extraCargo|extraCargo]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[#addCargoEntity|addCargoEntity()]]</code>, <code>[[Oolite JavaScript Reference: Ship#dumpCargo|dumpCargo()]]</code>, <code>[[#removeAllCargo|removeAllCargo()]]</code> | ||
+ | |||
+ | === <code>massLockable</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | '''massLockable''' : Boolean (read/write) | ||
+ | Indicates whether the player ship can be mass-locked. | ||
=== <code>maxAftShield</code> === | === <code>maxAftShield</code> === | ||
Line 179: | Line 216: | ||
=== <code>missilesOnline</code> === | === <code>missilesOnline</code> === | ||
{{Oolite-prop-added|1.77}} | {{Oolite-prop-added|1.77}} | ||
+ | |||
'''missilesOnline''' : Boolean (read-only) | '''missilesOnline''' : Boolean (read-only) | ||
− | + | <code>true</code> if the ship's targeting system is currently in missile targeting mode, <code>false</code> if it is currently in identification mode. | |
+ | |||
+ | === <code>messageGuiTextColor</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | |||
+ | '''messageGuiTextColor''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write) | ||
+ | Gets/sets the color used by the message GUI component of the HUD to display text messages. | ||
+ | |||
+ | === <code>messageGuiTextCommsColor</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | |||
+ | '''messageGuiTextCommsColor''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write) | ||
+ | Gets/sets the color used by the message GUI component of the HUD to display comms messages. | ||
=== <code>multiFunctionDisplayList</code> === | === <code>multiFunctionDisplayList</code> === | ||
{{Oolite-prop-added|1.81}} | {{Oolite-prop-added|1.81}} | ||
+ | |||
'''multiFunctionDisplayList''' : Array (read-only, strings) | '''multiFunctionDisplayList''' : Array (read-only, strings) | ||
The IDs of the currently active multi-function displays | The IDs of the currently active multi-function displays | ||
Line 192: | Line 243: | ||
=== <code>multiFunctionDisplays</code> === | === <code>multiFunctionDisplays</code> === | ||
{{Oolite-prop-added|1.79}} | {{Oolite-prop-added|1.79}} | ||
+ | |||
'''multiFunctionDisplays''' : Number (read-only, integer) | '''multiFunctionDisplays''' : Number (read-only, integer) | ||
The number of multi-function displays available on the current HUD. | The number of multi-function displays available on the current HUD. | ||
+ | |||
+ | === <code>nextSystem</code> === | ||
+ | {{Oolite-prop-added|1.85}} | ||
+ | |||
+ | '''nextSystem''' : Integer (read-only) | ||
+ | The ID of the next hyperspace system, if the player has a multi-step course plotted on the galactic chart. | ||
+ | |||
+ | '''See also''': <code>[[#targetSystem|targetSystem]]()</code> | ||
+ | |||
+ | === <code>previousSystem</code> === | ||
+ | {{oolite-prop-added|1.91}} | ||
+ | |||
+ | '''previousSystem''' : Integer (read-only) | ||
+ | The ID of the system the player most recently hyperspaced from. | ||
=== <code>price</code> === | === <code>price</code> === | ||
{{Oolite-prop-added|1.77}} | {{Oolite-prop-added|1.77}} | ||
+ | |||
'''price''' : Number (read-only, positive integer in decicredits) | '''price''' : Number (read-only, positive integer in decicredits) | ||
The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state. | The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state. | ||
+ | |||
+ | === <code>primedEquipment</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | |||
+ | '''primedEquipment''' : String (read/write) | ||
+ | Gets/sets the equipment key of current primed equipment item. When setting, the change will happen silently (i.e., there will be no console message informing the player of the change). | ||
+ | |||
+ | '''See also''': <code>[[#setPrimedEquipment|setPrimedEquipment()]]</code> | ||
=== <code>renovationCost</code> === | === <code>renovationCost</code> === | ||
{{Oolite-prop-added|1.79}} | {{Oolite-prop-added|1.79}} | ||
+ | |||
'''renovationCost''' : Number (read-only, positive integer in decicredits) | '''renovationCost''' : Number (read-only, positive integer in decicredits) | ||
The current price in decicredits to service the ship. Depending on the [[#serviceLevel|serviceLevel]] it may not be possible to actually purchase renovation at this time. | The current price in decicredits to service the ship. Depending on the [[#serviceLevel|serviceLevel]] it may not be possible to actually purchase renovation at this time. | ||
Line 207: | Line 283: | ||
=== <code>renovationMultiplier</code> === | === <code>renovationMultiplier</code> === | ||
{{Oolite-prop-added|1.79}} | {{Oolite-prop-added|1.79}} | ||
+ | |||
'''renovationMultiplier''' : Number (read-only, positive) | '''renovationMultiplier''' : Number (read-only, positive) | ||
The multiplier applied to the base cost of renovation (<code>renovationCost</code> already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in [[Shipyard.plist#renovation_multiplier|shipyard.plist]] | The multiplier applied to the base cost of renovation (<code>renovationCost</code> already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in [[Shipyard.plist#renovation_multiplier|shipyard.plist]] | ||
+ | |||
+ | === <code>reticleColorTarget</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | |||
+ | '''reticleColorTarget''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write) | ||
+ | Gets/sets the color used to highlight a target on the HUD. | ||
+ | |||
+ | '''See also''': <code>[[#reticleColorTargetSensitive|reticleColorTargetSensitive()]]</code> | ||
+ | |||
+ | === <code>reticleColorTargetSenstive</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | |||
+ | '''reticleColorTargetSensitive''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write) | ||
+ | Gets/sets the color used to highlight a target on the HUD when it is lined up (the <code>reticleTargetSensitive</code> property must be <code>true</code>). | ||
+ | |||
+ | '''See also''': <code>[[#reticleColorTarget|reticleColorTarget()]]</code>, <code>[[#reticleTargetSenstive|reticleTargetSensitive]]</code> | ||
+ | |||
+ | === <code>reticleColorWormhole</code> === | ||
+ | {{oolite-prop-added|1.85}} | ||
+ | |||
+ | '''reticleColorWormhole''' : [[Materials in Oolite#Colour specifiers|Color specifier]] (read/write) | ||
+ | Gets/sets the color used to highlight a wormhole on the HUD. | ||
=== <code>reticleTargetSensitive</code> === | === <code>reticleTargetSensitive</code> === | ||
'''reticleTargetSensitive''' : Boolean (read/write) | '''reticleTargetSensitive''' : Boolean (read/write) | ||
− | If true | + | If <code>true</code> and the [[Scanner Targeting Enhancement]] is installed, the selected target reticle will turn red when the target is in the player’s sights. This is equivalent to the <code>[[Hud.plist#reticle_target_sensitive|reticle_target_sensitive]]</code> key in HUD plists. |
=== <code>routeMode</code> === | === <code>routeMode</code> === | ||
Line 218: | Line 317: | ||
'''routeMode''' : String (read-only) | '''routeMode''' : String (read-only) | ||
Gives the current mode of the [[Advanced Navigational Array]]. Three possible values | Gives the current mode of the [[Advanced Navigational Array]]. Three possible values | ||
− | * "OPTIMIZED_BY_NONE": off, or not fitted | + | * <code>"OPTIMIZED_BY_NONE"</code>: off, or not fitted |
− | * "OPTIMIZED_BY_JUMPS": shortest route | + | * <code>"OPTIMIZED_BY_JUMPS"</code>: shortest route |
− | * "OPTIMIZED_BY_TIME": quickest route | + | * <code>"OPTIMIZED_BY_TIME"</code>: quickest route |
=== <code>scannerNonLinear</code> === | === <code>scannerNonLinear</code> === | ||
Line 232: | Line 331: | ||
=== <code>scoopOverride</code> === | === <code>scoopOverride</code> === | ||
'''scoopOverride''' : Boolean (read/write) | '''scoopOverride''' : Boolean (read/write) | ||
− | If <code>true</code> | + | If <code>true</code> and the player has a [[Fuel Scoops|fuel scoop]], the fuel scoop effect will run even if not close to a sun or scooping cargo. |
=== <code>serviceLevel</code> === | === <code>serviceLevel</code> === | ||
Line 241: | Line 340: | ||
=== <code>specialCargo</code> === | === <code>specialCargo</code> === | ||
'''specialCargo''' : String (read-only) | '''specialCargo''' : String (read-only) | ||
− | The special cargo the player is carrying, if any; otherwise <code>null</code>. | + | The special cargo the player is carrying, if any; otherwise <code>null</code>. This will not be listed in the manifest. |
− | '''See also''': <code>[[#useSpecialCargo|useSpecialCargo]]()</code> | + | '''See also''': <code>[[#useSpecialCargo|useSpecialCargo()]]</code>, <code>[[#removeAllCargo|removeAllCargo()]]</code> |
=== <code>targetSystem</code> === | === <code>targetSystem</code> === | ||
'''targetSystem''' : Integer (read-only, sometimes read/write in 1.77) | '''targetSystem''' : Integer (read-only, sometimes read/write in 1.77) | ||
− | The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked. | + | The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked. The target system is the final destination system if the player has a multi-jump course plotted on the galactic chart. |
+ | |||
+ | '''See also''': <code>[[#nextSystem|nextSystem]]()</code> | ||
=== <code>torusEngaged</code> === | === <code>torusEngaged</code> === | ||
{{Oolite-prop-added|1.81}} | {{Oolite-prop-added|1.81}} | ||
'''torusEngaged''' : Boolean(read-only) | '''torusEngaged''' : Boolean(read-only) | ||
− | Is the player ship currently using torus drive | + | Is the player ship currently using [[Torus Drive|torus drive]]. |
=== <code>viewDirection</code> === | === <code>viewDirection</code> === | ||
Line 274: | Line 375: | ||
{{oolite-method-added|1.85}} | {{oolite-method-added|1.85}} | ||
function '''addCargoEntity'''(cargo : ShipEntity [, processEvents : Boolean [, processMessages : Boolean]]) : Boolean | function '''addCargoEntity'''(cargo : ShipEntity [, processEvents : Boolean [, processMessages : Boolean]]) : Boolean | ||
− | Adds a cargo | + | Adds a cargo entity directly to the player's cargo hold. This can be performed only under the following conditions: the player's ship is in space with enough [[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|free cargo capacity]], the cargo item passed to the method must be a valid ship entity and able to be [[Fuel Scoops|scooped]]. Will return <code>true</code> if the cargo item was successfully added to the player ship, otherwise <code>false</code>. |
+ | |||
+ | The optional <code>processEvents</code> parameter controls whether or not standard scooping events (<code>[[Oolite JavaScript Reference: Ship script event handlers#shipWasScooped|shipWasScooped]]</code> and <code>[[Oolite JavaScript Reference: World script event handlers#shipScoopedOther|shipScoopedOther]]</code>) will be performed when the ship is added. The default is <code>false</code>. | ||
− | The optional <code> | + | The optional <code>processMessages</code> parameter controls whether or not any of the standard scooping messages (eg. "1t Computers") will be displayed. The default is <code>false</code>. |
− | + | '''See also''': <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[#manifest|manifest]]</code> | |
=== <code>addParcel</code> === | === <code>addParcel</code> === | ||
Line 287: | Line 390: | ||
Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid. | Returns <code>false</code> when there is already a parcel with that name or the arrival time is invalid. | ||
− | The <code>advance</code> and <code>risk</code> parameters were added in Oolite 1.79. <code>advance</code> is purely advisory and describes any up-front payment given for the parcel. <code>risk</code> can be 0, 1 or 2 | + | The <code>advance</code> and <code>risk</code> parameters were added in Oolite 1.79. <code>advance</code> is purely advisory and describes any up-front payment given for the parcel. <code>risk</code> can be <code>0</code>, <code>1</code> or <code>2</code>: the higher the number, the more likely that assassins will try to kill the player carrying this parcel. |
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#parcelCount|parcelCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#removeParcel|removeParcel()]]</code> | ||
=== <code>addPassenger</code> === | === <code>addPassenger</code> === | ||
Line 302: | Line 407: | ||
'''N.B.''' Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance ''was'', without actually making it. | '''N.B.''' Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance ''was'', without actually making it. | ||
− | The risk parameter was added in Oolite 1.79. <code>risk</code> can be 0, 1 or 2 | + | The risk parameter was added in Oolite 1.79. <code>risk</code> can be <code>0</code>, <code>1</code> or <code>2</code>: the higher the number, the more likely that assassins will try to kill the player carrying this passenger. |
+ | |||
+ | '''See also''': <code>[[Passenger Berth]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengerCapacity|passengerCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengerCount|passengerCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#removePassenger|removePassenger()]]</code> | ||
=== <code>awardContract</code> === | === <code>awardContract</code> === | ||
Line 316: | Line 423: | ||
'''N.B.''' Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment ''was'', without actually making it. | '''N.B.''' Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment ''was'', without actually making it. | ||
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#removeContract|removeContract()]]</code> | ||
=== <code>awardEquipmentToCurrentPylon</code> === | === <code>awardEquipmentToCurrentPylon</code> === | ||
Line 324: | Line 433: | ||
'''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code> | '''See also:''' <code>[[Oolite JavaScript Reference: Ship#awardEquipment|Ship.awardEquipment()]]</code> | ||
+ | |||
+ | === <code>beginGalacticHyperspaceCountdown</code> === | ||
+ | {{oolite-method-added|1.91}} | ||
+ | function '''beginGalacticHyperspaceCountdown'''( [ length : Number ] ) : Boolean | ||
+ | This method begins the galactic witchspace sequence for the player ship. It returns <code>true</code> if the sequence is started successfully, and <code>false</code> otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used. | ||
+ | |||
+ | '''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]], [[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code> | ||
=== <code>beginHyperspaceCountdown</code> === | === <code>beginHyperspaceCountdown</code> === | ||
{{oolite-method-added|1.77}} | {{oolite-method-added|1.77}} | ||
− | function beginHyperspaceCountdown( [ length : Number ] ) : Boolean | + | function '''beginHyperspaceCountdown'''( [ length : Number ] ) : Boolean |
− | This | + | This method begins the witchspace sequence for the player ship. It returns <code>true</code> if the sequence is started successfully, and <code>false</code> otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used. |
'''See also:''' <code>[[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code> | '''See also:''' <code>[[#cancelHyperspaceCountdown|cancelHyperspaceCountdown]]</code> | ||
Line 335: | Line 451: | ||
{{oolite-method-added|1.85}} | {{oolite-method-added|1.85}} | ||
function '''cancelDockingRequest'''(station : Station) | function '''cancelDockingRequest'''(station : Station) | ||
− | Tells the station to cancel a previous request for docking. If the player isn't currently waiting for clearance, or doesn't already have clearance, this | + | Tells the station to cancel a previous request for docking. If the player isn't currently waiting for clearance, or doesn't already have clearance, this method will do nothing |
'''See also:''' <code>[[#requestDockingClearance|requestDockingClearance]]</code> | '''See also:''' <code>[[#requestDockingClearance|requestDockingClearance]]</code> | ||
Line 341: | Line 457: | ||
=== <code>cancelHyperspaceCountdown</code> === | === <code>cancelHyperspaceCountdown</code> === | ||
{{oolite-method-added|1.77}} | {{oolite-method-added|1.77}} | ||
− | function cancelHyperspaceCountdown() : Boolean | + | function '''cancelHyperspaceCountdown'''() : Boolean |
− | This | + | This method cancels the witchspace sequence for the player ship. It returns <code>true</code> if there was an ongoing sequence to cancel, and <code>false</code> otherwise. |
'''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]]</code> | '''See also:''' <code>[[#beginHyperspaceCountdown|beginHyperspaceCountdown]]</code> | ||
=== <code>disengageAutopilot</code> === | === <code>disengageAutopilot</code> === | ||
− | function disengageAutopilot() | + | function '''disengageAutopilot'''() |
Disenable autopilot. | Disenable autopilot. | ||
Line 353: | Line 469: | ||
=== <code>engageAutopilotToStation</code> === | === <code>engageAutopilotToStation</code> === | ||
− | function engageAutopilotToStation(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean | + | function '''engageAutopilotToStation'''(station : [[Oolite JavaScript Reference: Station|Station]]) : Boolean |
Engage autopilot, set to dock with the specified station. | Engage autopilot, set to dock with the specified station. | ||
Line 360: | Line 476: | ||
=== <code>hideHUDSelector</code> === | === <code>hideHUDSelector</code> === | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
− | function hideHUDSelector(selector : String) | + | function '''hideHUDSelector'''(selector : String) |
− | Hide all dials using the specified selector on the HUD display. For example | + | Hide all dials using the specified [[Hud.plist#selector|selector]] on the HUD display. For example |
player.ship.hideHUDSelector("drawScanner:"); | player.ship.hideHUDSelector("drawScanner:"); | ||
Line 373: | Line 489: | ||
=== <code>removeAllCargo</code> === | === <code>removeAllCargo</code> === | ||
function '''removeAllCargo'''() | function '''removeAllCargo'''() | ||
− | Removes all cargo from the ship’s cargo bay that are measured in tons. Does not affect | + | Removes all cargo from the ship’s cargo bay that are measured in tons (including [[#specialCargo|special cargo]]). Does not affect gold, platinum or gem stones. Can only be used while docked. |
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#cargoSpaceCapacity|cargoSpaceCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceUsed|cargoSpaceUsed]]</code>, <code>[[Oolite JavaScript Reference: Ship#cargoSpaceAvailable|cargoSpaceAvailable]]</code>, <code>[[Oolite JavaScript Reference: Ship#dumpCargo|dumpCargo()]]</code>, <code>[[#manifest|manifest]]</code> | ||
=== <code>removeContract</code> === | === <code>removeContract</code> === | ||
function '''removeContract'''(commodity : String, destination : Number) | function '''removeContract'''(commodity : String, destination : Number) | ||
Remove the cargo contract matching that commodity and destination. | Remove the cargo contract matching that commodity and destination. | ||
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#contracts|contracts]]</code>, <code>[[#awardContract|awardContract()]]</code> | ||
=== <code>removeParcel</code> === | === <code>removeParcel</code> === | ||
Line 383: | Line 503: | ||
function '''removeParcel'''(name : String) | function '''removeParcel'''(name : String) | ||
Remove a named parcel. | Remove a named parcel. | ||
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#parcelCount|parcelCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#parcels|parcels]]</code>, <code>[[#addParcel|addParcel()]]</code> | ||
=== <code>removePassenger</code> === | === <code>removePassenger</code> === | ||
function '''removePassenger'''(name : String) | function '''removePassenger'''(name : String) | ||
Remove a named passenger. | Remove a named passenger. | ||
+ | |||
+ | '''See also''': <code>[[Oolite JavaScript Reference: Ship#passengerCapacity|passengerCapacity]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengerCount|passengerCount]]</code>, <code>[[Oolite JavaScript Reference: Ship#passengers|passengers]]</code>, <code>[[#addPassenger|addPassenger()]]</code> | ||
=== <code>requestDockingClearance</code> === | === <code>requestDockingClearance</code> === | ||
{{oolite-method-added|1.85}} | {{oolite-method-added|1.85}} | ||
function '''requestDockingClearance'''(station : Station) | function '''requestDockingClearance'''(station : Station) | ||
− | Sends the station a request to dock. If the station has already granted docking clearance, or is currently processing a previous request, this | + | Sends the station a request to dock. If the station has already granted docking clearance, or is currently processing a previous request, this method will do nothing. |
'''See also:''' <code>[[#cancelDockingRequest|cancelDockingRequest]]</code> | '''See also:''' <code>[[#cancelDockingRequest|cancelDockingRequest]]</code> | ||
Line 400: | Line 524: | ||
Resets the custom view back to the last-used setting defined in [[shipdata.plist]] | Resets the custom view back to the last-used setting defined in [[shipdata.plist]] | ||
− | This | + | This method gives an error if used when the custom view camera is not selected. |
=== <code>resetScannerZoom</code> === | === <code>resetScannerZoom</code> === | ||
Line 414: | Line 538: | ||
The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved. | The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved. | ||
− | This | + | This method gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in [[shipdata.plist]], which will be switched back to the next time 'v' is pressed, or when [[#resetCustomView|resetCustomView]] is called. |
+ | |||
+ | '''Note''': [https://bb.oolite.space/viewtopic.php?p=176272#p176272 Cim's explanation] with example. (2012) | ||
=== <code>setCustomHUDDial</code> === | === <code>setCustomHUDDial</code> === | ||
Line 424: | Line 550: | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean | function '''setMultiFunctionDisplay'''(index : Number, key : String) : Boolean | ||
− | Sets the multi-function display with the specified number to display the given multi-function display <code>key</code> set earlier with [[#setMultiFunctionText|setMultiFunctionText()]]. Multi-function displays are numbered from 0 to [[#multiFunctionDisplays|multiFunctionDisplays]]-1. If the index given is outside this range, the first unused multi-function display will be used, or the | + | Sets the multi-function display with the specified number to display the given multi-function display <code>key</code> set earlier with [[#setMultiFunctionText|setMultiFunctionText()]]. Multi-function displays are numbered from 0 to [[#multiFunctionDisplays|multiFunctionDisplays]]-1. If the index given is outside this range, the first unused multi-function display will be used, or the method will return <code>false</code> if all are currently in use. |
Example: | Example: | ||
// picks first unused one | // picks first unused one | ||
player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd"); | player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd"); | ||
− | As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this | + | As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this method to override a specific display except in emergencies, as this is likely to annoy the player. |
=== <code>setMultiFunctionText</code> === | === <code>setMultiFunctionText</code> === | ||
Line 440: | Line 566: | ||
=== <code>setPrimedEquipment</code> === | === <code>setPrimedEquipment</code> === | ||
{{oolite-method-added|1.85}} | {{oolite-method-added|1.85}} | ||
− | function '''setPrimedEquipment'''(equipmentKey : String) | + | function '''setPrimedEquipment'''(equipmentKey : String [, showMessage : Boolean]) |
Sets the current primed equipment to the specified equipment key. | Sets the current primed equipment to the specified equipment key. | ||
− | Returns true if the | + | Returns <code>true</code> if the method was successful. If equipment key is not found, primed equipment will be set to "None". |
+ | |||
+ | If the showMessage parameter is left out or set to <code>true</code>, a console message will be displayed informing the player of the change in primed equipment. Setting showMessage to <code>false</code> will make the change silently. | ||
+ | |||
+ | '''See also''': <code>[[#primedEquipment|primedEquipment]]</code> | ||
=== <code>showHUDSelector</code> === | === <code>showHUDSelector</code> === | ||
{{oolite-method-added|1.79}} | {{oolite-method-added|1.79}} | ||
− | function showHUDSelector(selector : String) | + | function '''showHUDSelector'''(selector : String) |
− | Show all dials using the specified selector on the HUD display if they were previously hidden. For example | + | Show all dials using the specified [[Hud.plist#selector|selector]] on the HUD display if they were previously hidden. For example |
player.ship.showHUDSelector("drawScanner:"); | player.ship.showHUDSelector("drawScanner:"); | ||
Line 456: | Line 586: | ||
=== <code>takeInternalDamage</code> === | === <code>takeInternalDamage</code> === | ||
{{oolite-method-added|1.77}} | {{oolite-method-added|1.77}} | ||
− | function '''takeInternalDamage'''() | + | function '''takeInternalDamage'''() : Boolean |
− | Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this | + | Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this method uses the same algorithm to determine the damage taken, which can be: |
* damage to cargo | * damage to cargo | ||
* damage to equipment (according to the damage_probability) | * damage to equipment (according to the damage_probability) | ||
* reduction in [[#serviceLevel|service level]] | * reduction in [[#serviceLevel|service level]] | ||
* no damage | * no damage | ||
− | The | + | The method will return <code>false</code> if "no damage" was selected, or <code>true</code> otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment. |
=== <code>useSpecialCargo</code> === | === <code>useSpecialCargo</code> === | ||
function '''useSpecialCargo'''(description : String) | function '''useSpecialCargo'''(description : String) | ||
− | Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed. | + | Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed. Any current cargo (except for g- and kg-based cargo) will be discarded. Use [[#removeAllCargo|removeAllCargo()]] to remove the special cargo. |
'''See also''': <code>[[#specialCargo|specialCargo]]</code> | '''See also''': <code>[[#specialCargo|specialCargo]]</code> | ||
[[Category:Oolite JavaScript Reference]] | [[Category:Oolite JavaScript Reference]] |
Latest revision as of 22:35, 7 March 2024
Prototype: Ship
Subtypes: none
The PlayerShip
class is an Entity
representing the player’s ship. The PlayerShip
has all the properties and methods of a Ship
, and several others. There is always exactly one PlayerShip object in existence, which can be accessed through player.ship
.
Like any entity, the player ship can become invalid – specifically, when the player dies or ejects. Unlike other entities, the player ship can become valid again (after ejecting and being rescued). This is a technicality and it’s not guaranteed to work this way in future.
Contents
- 1 Properties
- 1.1 activeMissile
- 1.2 aftShield
- 1.3 aftShieldRechargeRate
- 1.4 chartHighlightMode
- 1.5 compassMode
- 1.6 compassTarget
- 1.7 compassType
- 1.8 crosshairs
- 1.9 currentWeapon
- 1.10 cursorCoordinates
- 1.11 cursorCoordinatesInLY
- 1.12 docked
- 1.13 dockedStation
- 1.14 extraCargo
- 1.15 fastEquipmentA
- 1.16 fastEquipmentB
- 1.17 forwardShield
- 1.18 forwardShieldRechargeRate
- 1.19 fuelLeakRate
- 1.20 galacticHyperspaceBehaviour
- 1.21 galacticHyperspaceFixedCoords
- 1.22 galacticHyperspaceFixedCoordsInLY
- 1.23 galaxyCoordinates
- 1.24 galaxyCoordinatesInLY
- 1.25 hud
- 1.26 hudAllowsBigGui
- 1.27 hudHidden
- 1.28 hyperspaceSpinTime
- 1.29 infoSystem
- 1.30 injectorsEngaged
- 1.31 manifest
- 1.32 massLockable
- 1.33 maxAftShield
- 1.34 maxForwardShield
- 1.35 missilesOnline
- 1.36 messageGuiTextColor
- 1.37 messageGuiTextCommsColor
- 1.38 multiFunctionDisplayList
- 1.39 multiFunctionDisplays
- 1.40 nextSystem
- 1.41 previousSystem
- 1.42 price
- 1.43 primedEquipment
- 1.44 renovationCost
- 1.45 renovationMultiplier
- 1.46 reticleColorTarget
- 1.47 reticleColorTargetSenstive
- 1.48 reticleColorWormhole
- 1.49 reticleTargetSensitive
- 1.50 routeMode
- 1.51 scannerNonLinear
- 1.52 scannerUltraZoom
- 1.53 scoopOverride
- 1.54 serviceLevel
- 1.55 specialCargo
- 1.56 targetSystem
- 1.57 torusEngaged
- 1.58 viewDirection
- 1.59 viewPosition*
- 1.60 weaponsOnline
- 2 Methods
- 2.1 addCargoEntity
- 2.2 addParcel
- 2.3 addPassenger
- 2.4 awardContract
- 2.5 awardEquipmentToCurrentPylon
- 2.6 beginGalacticHyperspaceCountdown
- 2.7 beginHyperspaceCountdown
- 2.8 cancelDockingRequest
- 2.9 cancelHyperspaceCountdown
- 2.10 disengageAutopilot
- 2.11 engageAutopilotToStation
- 2.12 hideHUDSelector
- 2.13 launch
- 2.14 removeAllCargo
- 2.15 removeContract
- 2.16 removeParcel
- 2.17 removePassenger
- 2.18 requestDockingClearance
- 2.19 resetCustomView
- 2.20 resetScannerZoom
- 2.21 setCustomView
- 2.22 setCustomHUDDial
- 2.23 setMultiFunctionDisplay
- 2.24 setMultiFunctionText
- 2.25 setPrimedEquipment
- 2.26 showHUDSelector
- 2.27 takeInternalDamage
- 2.28 useSpecialCargo
Properties
activeMissile
This property was added in Oolite test release 1.89.
activeMissile : Number (read-only integer)
Index in the missiles
array of the currently selected missile.
aftShield
aftShield : Number (read/write, nonnegative)
The current aft shield level, ranging from 0 to maxAftShield
.
See also: aftShieldRechargeRate
, forwardShield
, maxAftShield
aftShieldRechargeRate
aftShieldRechargeRate : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The rate at which the aft shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as forwardShieldRechargeRate
, but this is not the case from 1.81.
See also: aftShield
, forwardShieldRechargeRate
, maxAftShield
chartHighlightMode
This property was added in Oolite test release 1.87.
chartHighlightMode : String (read/write)
Gets/sets the type of highlight being shown on the galactic chart. Can be any one of the following:
"OOLRC_MODE_SUNCOLOR"
"OOLRC_MODE_ECONOMY"
"OOLRC_MODE_GOVERNMENT"
"OOLRC_MODE_TECHLEVEL"
compassMode
compassMode : String (read-only in 1.84 and earlier, read/write in 1.85 and later)
Gets/sets the current compass mode, which can be any one of the following:
"COMPASS_MODE_BASIC"
"COMPASS_MODE_PLANET"
"COMPASS_MODE_STATION"
"COMPASS_MODE_SUN"
"COMPASS_MODE_TARGET"
"COMPASS_MODE_BEACONS"
compassTarget
compassTarget : Entity(read-only in 1.84 and earlier, read/write in 1.85 and later)
Gets/sets the entity currently targeted by the compass. When setting this value, the entity must be valid, and have a compass beacon.
compassType
compassType : String (read-only in 1.84 and earlier, read/write in 1.85 and later)
Gets/sets the current space compass type, which can be one of the following:
"OO_COMPASSTYPE_BASIC"
"OO_COMPASSTYPE_ADVANCED"
crosshairs
This property was added in Oolite test release 1.77.
crosshairs : String (read/write)
The name of the crosshairs.plist defining the ship’s weapon crosshairs. HUDs can define crosshairs separately. This value will be null
if the HUD built-in crosshairs are in use, and setting it to null
will revert to the default HUD crosshairs.
If the HUD is changed, the old value of this property will be discarded, and the HUD's default crosshairs will be used.
currentWeapon
This property was added in Oolite test release 1.77.
currentWeapon : EquipmentInfo (read/write)
A shortcut property to whichever of aftWeapon, forwardWeapon, portWeapon or starboardWeapon is the currently active player weapon.
If the player is on a screen with no active weapon (e.g. docked, or viewing the status screens) then this will always be null
and attempting to write to it will give an error.
cursorCoordinates
cursorCoordinates : Vector3D (read-only)
Discouraged in favour of cursorCoordinatesInLY
.
The current x and y cursor coordinates on the long range screen in the internal coordinate system. The z
coordinate is always 0.
cursorCoordinatesInLY
cursorCoordinatesInLY : Vector3D (read-only)
The current x and y cursor coordinates on the long range screen, in light years. The z
coordinate is always 0.
docked
docked : Boolean (read-only)
true
if the player is docked with a station or carrier.
dockedStation
dockedStation : Station (read-only)
The station with which the player is currently docked.
extraCargo
This property was added in Oolite test release 1.79.
extraCargo : Number (read-only integer)
The amount the cargoSpaceCapacity
increases when a Cargo Bay Expansion is installed. The corresponding shipdata.plist key is extra_cargo
. Note that although this property can be used to check non-player ships, it only contains the value for the player ship.
See also: cargoSpaceUsed
,
cargoSpaceAvailable
fastEquipmentA
This property was added in Oolite test release 1.79.
fastEquipmentA : String (read/write)
Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity defensive slot (default key: 0).
fastEquipmentB
This property was added in Oolite test release 1.79.
fastEquipmentB : String (read/write)
Gets/sets the equipment key of primable equipment item currently assigned to the fast affinity offensive slot (default key: TAB).
forwardShield
forwardShield : Number (read/write, nonnegative)
The current forward shield level, ranging from 0 to maxForwardShield
.
See also: aftShield
, forwardShieldRechargeRate
, maxForwardShield
forwardShieldRechargeRate
forwardShieldRechargeRate : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The rate at which the forward shield recharges (assuming enough energy is available). This is affected by equipment – currently, the Military Shield Enhancement. In 1.80 and earlier always the same as aftShieldRechargeRate
, but this is no longer the case in 1.81
See also: aftShieldRechargeRate
, forwardShield
, maxForwardShield
fuelLeakRate
fuelLeakRate : Number (read/write)
The rate at which the player is losing fuel, in tenths of a LY per second. May not be negative. Reset to 0 when fuel is empty.
galacticHyperspaceBehaviour
galacticHyperspaceBehaviour : String (read/write)
A string indicating what the effect of a galactic hyperspace jump will be. The available options are:
"BEHAVIOUR_STANDARD"
: the player arrives in the closest system to the starting point that is part of the main group of stars. Small groups (as seen in galaxy 6, among others) can’t be reached."BEHAVIOUR_ALL_SYSTEMS_REACHABLE"
: The player arrives at the closest system to the starting point, even if it is in a small group. Important: this can leave the player stranded, unless there are missions providing the possibility of escape!"BEHAVIOUR_FIXED_COORDINATES"
: The player arrives at the system closest togalacticHyperspaceFixedCoordsInLY
.
See also: galacticHyperspaceFixedCoordsInLY
galacticHyperspaceFixedCoords
galacticHyperspaceFixedCoords : Vector3D (read/write)
Discouraged in favour of galacticHyperspaceFixedCoordsInLY
.
Like galacticHyperspaceFixedCoordsInLY
, but in the internal coordinate system.
galacticHyperspaceFixedCoordsInLY
galacticHyperspaceFixedCoordsInLY : Vector3D (read/write)
The destination coordinates when galacticHyperspaceBehaviour
mode is "GALACTIC_HYPERSPACE_BEHAVIOUR_FIXED_COORDINATES"
. The coordinate system corresponds to galaxyCoordinatesInLY
. Currently, when assigning a value its x
and y
coordinates will be rounded to integer internal coordinates, and the z
coordinate will be rejected.
See also: galacticHyperspaceBehaviour
galaxyCoordinates
galaxyCoordinates : Vector3D (read-only)
Discouraged in favour of galaxyCoordinatesInLY
.
The player’s location in galactic space, in the internal coordinate system. The z
coordinate is always 0.
galaxyCoordinatesInLY
galaxyCoordinatesInLY : Vector3D (read-only)
The player’s location in galactic space, in light years (measured from the top left of the map). The z
coordinate is always 0.
hud
hud : String (read/write)
The name of the HUD plists defining the ship’s head up display.
hudAllowsBigGui
This property was added in Oolite test release 1.83.
hudAllowsBigGui : Boolean (read-only)
Whether the HUD allows a "big GUI" or not. Most useful for determining whether mission screens will have 21 or 27 lines.
If hudHidden
is true
, this will also be true
even if the HUD would not normally allow a big GUI.
hudHidden
hudHidden : Boolean (read/write)
Whether the HUD should be visible. Care should be taken when making the HUD invisible with this property. While invisible, any comms messages or console messages will not be seen by the player until the HUD is made visible again.
hyperspaceSpinTime
This property was added in Oolite test release 1.77.
hyperspaceSpinTime : Number (read-only, read/write in 1.81)
The length of the ship's hyperspace countdown.
Setting this to a negative value disables the drive entirely.
infoSystem
This property was added in Oolite test release 1.83.
infoSystem : Number (read/write)
The ID of the system shown in the system (F7) screen.
injectorsEngaged
This property was added in Oolite test release 1.81.
injectorsEngaged : Boolean(read-only)
Is the player ship currently using fuel injection.
manifest
manifest : Manifest (read/write)
The manifest contains all the cargo the player carries. It can be addressed as a property of playerShip as well as a class Manifest of its own.
Example:
// addressed as a property of playerShip player.ship.manifest.food = 5 // addressed as a class of its own manifest.food = 5
See also: extraCargo
, cargoSpaceCapacity
, cargoSpaceUsed
, cargoSpaceAvailable
, addCargoEntity()
, dumpCargo()
, removeAllCargo()
massLockable
This property was added in Oolite test release 1.85.
massLockable : Boolean (read/write)
Indicates whether the player ship can be mass-locked.
maxAftShield
maxAftShield : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The highest possible value of aftShield
. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as maxForwardShield
, but this is not necessarily true from 1.81.
See also: aftShield
, aftShieldRechargeRate
, maxForwardShield
maxForwardShield
maxAftShield : Number (read-only in 1.80 and earlier, read/write in 1.81 and later, nonnegative)
The highest possible value of forwardShield
. This is affected by equipment – currently the Shield Boosters and Military Shield Enhancement. In 1.80 and earlier always the same as maxAftShield
, but this is not necessarily true from 1.81.
See also: forwardShield
, forwardShieldRechargeRate
, maxAftShield
missilesOnline
This property was added in Oolite test release 1.77.
missilesOnline : Boolean (read-only)
true
if the ship's targeting system is currently in missile targeting mode, false
if it is currently in identification mode.
messageGuiTextColor
This property was added in Oolite test release 1.85.
messageGuiTextColor : Color specifier (read/write)
Gets/sets the color used by the message GUI component of the HUD to display text messages.
messageGuiTextCommsColor
This property was added in Oolite test release 1.85.
messageGuiTextCommsColor : Color specifier (read/write)
Gets/sets the color used by the message GUI component of the HUD to display comms messages.
multiFunctionDisplayList
This property was added in Oolite test release 1.81.
multiFunctionDisplayList : Array (read-only, strings)
The IDs of the currently active multi-function displays
e.g.
[null, "myoxp_mfd1"] // My OXP MFD1 in the second display, first display blank
multiFunctionDisplays
This property was added in Oolite test release 1.79.
multiFunctionDisplays : Number (read-only, integer)
The number of multi-function displays available on the current HUD.
nextSystem
This property was added in Oolite test release 1.85.
nextSystem : Integer (read-only)
The ID of the next hyperspace system, if the player has a multi-step course plotted on the galactic chart.
See also: targetSystem()
previousSystem
This property was added in Oolite test release 1.91.
previousSystem : Integer (read-only)
The ID of the system the player most recently hyperspaced from.
price
This property was added in Oolite test release 1.77.
price : Number (read-only, positive integer in decicredits)
The value the player's ship would have, including equipment, if in a perfect servicing state. The ship can be exchanged at a shipyard for 75% of this value if it really is in perfect servicing state.
primedEquipment
This property was added in Oolite test release 1.85.
primedEquipment : String (read/write)
Gets/sets the equipment key of current primed equipment item. When setting, the change will happen silently (i.e., there will be no console message informing the player of the change).
See also: setPrimedEquipment()
renovationCost
This property was added in Oolite test release 1.79.
renovationCost : Number (read-only, positive integer in decicredits)
The current price in decicredits to service the ship. Depending on the serviceLevel it may not be possible to actually purchase renovation at this time.
renovationMultiplier
This property was added in Oolite test release 1.79.
renovationMultiplier : Number (read-only, positive)
The multiplier applied to the base cost of renovation (renovationCost
already includes this multiplier) to allow for some ships being more difficult to maintain than others. The default is 1.0 - other values are set in shipyard.plist
reticleColorTarget
This property was added in Oolite test release 1.85.
reticleColorTarget : Color specifier (read/write)
Gets/sets the color used to highlight a target on the HUD.
See also: reticleColorTargetSensitive()
reticleColorTargetSenstive
This property was added in Oolite test release 1.85.
reticleColorTargetSensitive : Color specifier (read/write)
Gets/sets the color used to highlight a target on the HUD when it is lined up (the reticleTargetSensitive
property must be true
).
See also: reticleColorTarget()
, reticleTargetSensitive
reticleColorWormhole
This property was added in Oolite test release 1.85.
reticleColorWormhole : Color specifier (read/write)
Gets/sets the color used to highlight a wormhole on the HUD.
reticleTargetSensitive
reticleTargetSensitive : Boolean (read/write)
If true
and the Scanner Targeting Enhancement is installed, the selected target reticle will turn red when the target is in the player’s sights. This is equivalent to the reticle_target_sensitive
key in HUD plists.
routeMode
This property was added in Oolite test release 1.81.
routeMode : String (read-only)
Gives the current mode of the Advanced Navigational Array. Three possible values
"OPTIMIZED_BY_NONE"
: off, or not fitted"OPTIMIZED_BY_JUMPS"
: shortest route"OPTIMIZED_BY_TIME"
: quickest route
scannerNonLinear
scannerNonLinear : Boolean (read/write)
If true
, the scanner is operating in non-linear mode. This property will be reset to the HUD default if the HUD is changed.
scannerUltraZoom
scannerUltraZoom : Boolean (read/write)
If true
, the scanner has 1x, 2x, 4x, 8x and 16x zoom modes, rather than the conventional 1x, 2x, 3x, 4x and 5x. This property will be reset to the HUD default if the HUD is changed.
scoopOverride
scoopOverride : Boolean (read/write)
If true
and the player has a fuel scoop, the fuel scoop effect will run even if not close to a sun or scooping cargo.
serviceLevel
This property was added in Oolite test release 1.77.
serviceLevel : Number (read/write, positive integer in range 75-100)
The level of servicing the player's ship has. Renovation will be offered in shipyards at 85 or below, and malfunctions are more likely at lower values. This affects the sales price of the ship.
specialCargo
specialCargo : String (read-only)
The special cargo the player is carrying, if any; otherwise null
. This will not be listed in the manifest.
See also: useSpecialCargo()
, removeAllCargo()
targetSystem
targetSystem : Integer (read-only, sometimes read/write in 1.77)
The ID of the selected hyperspace target system. In 1.77, it can be written to if the player's ship is docked. The target system is the final destination system if the player has a multi-jump course plotted on the galactic chart.
See also: nextSystem()
torusEngaged
This property was added in Oolite test release 1.81.
torusEngaged : Boolean(read-only)
Is the player ship currently using torus drive.
viewDirection
viewDirection : String (read-only)
Returns the view direction as string: "VIEW_FORWARD"
, "VIEW_AFT"
, "VIEW_PORT"
, "VIEW_STARBOARD"
, "VIEW_CUSTOM"
or "VIEW_GUI_DISPLAY"
.
viewPosition*
This property was added in Oolite test release 1.79.
viewPositionAft : Vector (read-only) viewPositionForward : Vector (read-only) viewPositionPort : Vector (read-only) viewPositionStarboard : Vector (read-only)
The ship's 4 point-of-view positions in XYZ relative to the model. The corresponding shipdata.plist keys start with view_position_
.
weaponsOnline
weaponsOnline : Boolean (read-only)
Returns the weapon safety status. Player can toggle the status with the underscore-key.
Methods
addCargoEntity
This method was added in Oolite test release 1.85.
function addCargoEntity(cargo : ShipEntity [, processEvents : Boolean [, processMessages : Boolean]]) : Boolean
Adds a cargo entity directly to the player's cargo hold. This can be performed only under the following conditions: the player's ship is in space with enough free cargo capacity, the cargo item passed to the method must be a valid ship entity and able to be scooped. Will return true
if the cargo item was successfully added to the player ship, otherwise false
.
The optional processEvents
parameter controls whether or not standard scooping events (shipWasScooped
and shipScoopedOther
) will be performed when the ship is added. The default is false
.
The optional processMessages
parameter controls whether or not any of the standard scooping messages (eg. "1t Computers") will be displayed. The default is false
.
See also: cargoSpaceCapacity
, cargoSpaceUsed
, manifest
addParcel
This method was added in Oolite test release 1.77.
function addParcel(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean
Add a parcel contract to the ship. arrivalTime
is the arrival time in seconds and must be greater than the current time. start
and destination
are the ID numbers of the start and end systems.
Returns false
when there is already a parcel with that name or the arrival time is invalid.
The advance
and risk
parameters were added in Oolite 1.79. advance
is purely advisory and describes any up-front payment given for the parcel. risk
can be 0
, 1
or 2
: the higher the number, the more likely that assassins will try to kill the player carrying this parcel.
See also: parcelCount
, parcels
, removeParcel()
addPassenger
function addPassenger(name : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, advance: Number [, risk: Number]]) : Boolean
Add a passenger contract to the ship. arrivalTime
is the arrival time in seconds and must be greater than the current time. start
and destination
are the ID numbers of the start and end systems.
Returns false
when there is no room for the passenger, there is already a passenger with that name or the arrival time is invalid.
Example:
player.ship.addPassenger("cmdr Jameson", 34, 67, clock.seconds+3*24*3600, 1500);
If successful - and in galaxy chart 1 - the player will have cmdr Jameson as a passenger, his documents will show that he boarded the ship at Inus, to go to Cemave, within exactly 3 days, and the player will be given 1500 credits if he gets there on time (early or late arrival will affect the amount paid).
N.B. Normally a passenger will pay the captain a small advance upon boarding. Using this method, no initial payment is made. In versions after 1.77, an optional parameter can be added to describe what the advance was, without actually making it.
The risk parameter was added in Oolite 1.79. risk
can be 0
, 1
or 2
: the higher the number, the more likely that assassins will try to kill the player carrying this passenger.
See also: Passenger Berth
, passengerCapacity
, passengerCount
, passengers
, removePassenger()
awardContract
function awardContract(quantity : Number, commodity : String, start : Number, destination : Number, arrivalTime : Number, fee : Number [, premium : Number]) : Boolean
Add a cargo contract to the ship. arrivalTime
is the arrival time in seconds and must be greater than the current time. start
and destination
are the ID numbers of the start and end systems.
Returns false
when there is no room for the cargo, the arrival time is invalid.
Example:
player.ship.awardContract(12, "Food", 34, 67, clock.seconds+7*24*3600, 5000)
If successful - and in galaxy chart 1 - the player will have 12 more food containers on board, the manifest will show that the cargo was picked up at Inus, to be delivered at Cemave, within exactly 7 days, and the player will be given 5000 credits if the cargo is delivered on time (early or late delivery will affect the amount paid).
N.B. Normally to get a contract, the player will have to pay a deposit similar in value to the cargo. Using this method, no deposit payment is made. In versions after 1.77, an optional parameter can be added to describe what the deposit payment was, without actually making it.
See also: contracts
, removeContract()
awardEquipmentToCurrentPylon
function awardEquipmentToCurrentPylon(item : equipmentInfoExpression) : Boolean
Replace the missile or mine currently being launched with the specified item (which must be an external store). This will only have an effect if called while a missile or mine is being launched. Effectively this means that this method must be used within the shipFiredMissile()
handler or in the ENTER message of the GLOBAL state of an missileAI.plist.
Bug: In Oolite 1.74.0, if awardEquipmentToCurrentPylon()
fails the script will be halted without any error message. In future versions, it will simply return false
.
See also: Ship.awardEquipment()
beginGalacticHyperspaceCountdown
This method was added in Oolite test release 1.91.
function beginGalacticHyperspaceCountdown( [ length : Number ] ) : Boolean
This method begins the galactic witchspace sequence for the player ship. It returns true
if the sequence is started successfully, and false
otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.
See also: beginHyperspaceCountdown, cancelHyperspaceCountdown
beginHyperspaceCountdown
This method was added in Oolite test release 1.77.
function beginHyperspaceCountdown( [ length : Number ] ) : Boolean
This method begins the witchspace sequence for the player ship. It returns true
if the sequence is started successfully, and false
otherwise (no destination selected, insufficient fuel, out of range, etc.). Optionally, the length of the countdown can be varied. Values between 5 and 60 seconds are accepted. If this parameter is omitted the default sequence length for this class of ship will be used.
See also: cancelHyperspaceCountdown
cancelDockingRequest
This method was added in Oolite test release 1.85.
function cancelDockingRequest(station : Station)
Tells the station to cancel a previous request for docking. If the player isn't currently waiting for clearance, or doesn't already have clearance, this method will do nothing
See also: requestDockingClearance
cancelHyperspaceCountdown
This method was added in Oolite test release 1.77.
function cancelHyperspaceCountdown() : Boolean
This method cancels the witchspace sequence for the player ship. It returns true
if there was an ongoing sequence to cancel, and false
otherwise.
See also: beginHyperspaceCountdown
disengageAutopilot
function disengageAutopilot()
Disenable autopilot.
See also: engageAutopilotToStation()
engageAutopilotToStation
function engageAutopilotToStation(station : Station) : Boolean
Engage autopilot, set to dock with the specified station.
See also: disengageAutopilot()
hideHUDSelector
This method was added in Oolite test release 1.79.
function hideHUDSelector(selector : String)
Hide all dials using the specified selector on the HUD display. For example
player.ship.hideHUDSelector("drawScanner:");
See also: showHUDSelector()
launch
function launch()
Launches the player’s ship if it is currently docked.
removeAllCargo
function removeAllCargo()
Removes all cargo from the ship’s cargo bay that are measured in tons (including special cargo). Does not affect gold, platinum or gem stones. Can only be used while docked.
See also: cargoSpaceCapacity
, cargoSpaceUsed
, cargoSpaceAvailable
, dumpCargo()
, manifest
removeContract
function removeContract(commodity : String, destination : Number)
Remove the cargo contract matching that commodity and destination.
See also: contracts
, awardContract()
removeParcel
This method was added in Oolite test release 1.77.
function removeParcel(name : String)
Remove a named parcel.
See also: parcelCount
, parcels
, addParcel()
removePassenger
function removePassenger(name : String)
Remove a named passenger.
See also: passengerCapacity
, passengerCount
, passengers
, addPassenger()
requestDockingClearance
This method was added in Oolite test release 1.85.
function requestDockingClearance(station : Station)
Sends the station a request to dock. If the station has already granted docking clearance, or is currently processing a previous request, this method will do nothing.
See also: cancelDockingRequest
resetCustomView
This method was added in Oolite test release 1.77.
function resetCustomView()
Resets the custom view back to the last-used setting defined in shipdata.plist
This method gives an error if used when the custom view camera is not selected.
resetScannerZoom
This method was added in Oolite test release 1.79.
function resetScannerZoom()
Resets the scanner zoom back to 1:1
setCustomView
This method was added in Oolite test release 1.77.
function setCustomView(Vector : position, Quaternion : orientation [,WeaponDirection weapon])
Set the position and orientation of the custom view camera to those specified. As with the custom views specified through shipdata.plist, these are relative to the player's ship's position, and the coordinate frame defined by the ship's forward, right and up Vectors.
The optional weapon parameter can be "FORWARD", "AFT", "PORT" or "STARBOARD" and sets the active weapon accordingly. If omitted, the active weapon for the previous custom view will be preserved.
This method gives an error if used when the custom view camera is not selected. Setting the custom view does not affect the custom views defined in shipdata.plist, which will be switched back to the next time 'v' is pressed, or when resetCustomView is called.
Note: Cim's explanation with example. (2012)
setCustomHUDDial
This method was added in Oolite test release 1.81.
function setCustomHUDDial(key : String, value : Value)
Sets the custom HUD dial data source 'key' to the specified value. Different types of custom HUD dial will expect different types of values; a value of an incorrect type will be converted if possible.
setMultiFunctionDisplay
This method was added in Oolite test release 1.79.
function setMultiFunctionDisplay(index : Number, key : String) : Boolean
Sets the multi-function display with the specified number to display the given multi-function display key
set earlier with setMultiFunctionText(). Multi-function displays are numbered from 0 to multiFunctionDisplays-1. If the index given is outside this range, the first unused multi-function display will be used, or the method will return false
if all are currently in use.
Example:
// picks first unused one player.ship.setMultiFunctionDisplay(player.ship.multiFunctionDisplays, "myOxp_mfd");
As the player can cycle the contents of their displays between the various active keys themselves using keyboard controls, it is advisable not to call this method to override a specific display except in emergencies, as this is likely to annoy the player.
setMultiFunctionText
This method was added in Oolite test release 1.79.
function setMultiFunctionText(key : String [, contents : String [, reflow : Boolean]])
Set the text for the multi-function display with the specified key
to be contents
. The limit on space for a multi-function display is ten lines of text, each 15 blocks wide.
If you specify the optional reflow
parameter, then the text given will automatically be fitted into the available space, with any extra discarded. Otherwise, line-breaks will not be added automatically, so you must enter them into contents
yourself. If any individual line is more than 15 blocks long, the text will be compressed to fit it into the available space. This looks bad and is best avoided.
setPrimedEquipment
This method was added in Oolite test release 1.85.
function setPrimedEquipment(equipmentKey : String [, showMessage : Boolean])
Sets the current primed equipment to the specified equipment key.
Returns true
if the method was successful. If equipment key is not found, primed equipment will be set to "None".
If the showMessage parameter is left out or set to true
, a console message will be displayed informing the player of the change in primed equipment. Setting showMessage to false
will make the change silently.
See also: primedEquipment
showHUDSelector
This method was added in Oolite test release 1.79.
function showHUDSelector(selector : String)
Show all dials using the specified selector on the HUD display if they were previously hidden. For example
player.ship.showHUDSelector("drawScanner:");
See also: hideHUDSelector()
takeInternalDamage
This method was added in Oolite test release 1.77.
function takeInternalDamage() : Boolean
Causes the player ship to potentially take "internal damage". Internal damage can also be caused by hits on the hull and some witchdrive malfunctions, and this method uses the same algorithm to determine the damage taken, which can be:
- damage to cargo
- damage to equipment (according to the damage_probability)
- reduction in service level
- no damage
The method will return false
if "no damage" was selected, or true
otherwise. The relative probabilities of the three options vary depending on the size of the player ship, its cargo capacity, cargo carried and installed equipment.
useSpecialCargo
function useSpecialCargo(description : String)
Fills the cargo bay with the cargo described, effectively disabling the use of the cargo bay until the cargo is removed. Any current cargo (except for g- and kg-based cargo) will be discarded. Use removeAllCargo() to remove the special cargo.
See also: specialCargo
- Updated JavaScript features in Oolite 1.89
- Updated JavaScript features in Oolite 1.87
- Updated JavaScript features in Oolite 1.77
- Updated JavaScript features in Oolite 1.79
- Updated JavaScript features in Oolite 1.83
- Updated JavaScript features in Oolite 1.81
- Updated JavaScript features in Oolite 1.85
- Updated JavaScript features in Oolite 1.91
- Oolite JavaScript Reference