Difference between revisions of "Oolite JavaScript Reference: Ship"

Revision as of 11:56, 4 August 2007

Prototype: Entity
Subtypes: Station, Player

This page documents a planned future Oolite scripting feature. It is presented as a basis for discussion or to help developers organize their thoughts. The functionality presented may end up taking a radically different form, or may not become available at all.

The Ship class is an Entity representing a ship, station, missile, cargo pod or other flying item – anything that can be specified in shipdata.plist. A Ship has all the properties and methods of a Entity, and several others.

Stations and the Player are types of ship. Note that these more specific types have additional properties and methods.

Properties

`AI`

AI [read-only string]

The name of the ship’s current AI. (See also: AIState, setAI(), switchAI(), exitAI())

`AIState`

AIState [read/write string, read-only for player]

The ship’s AI’s current state. (See also: AI, reactToAIMessage(), hasSuspendedAI)

`beaconCode`

beaconCode [read-only string]

If the ship is a beacon, an identifying string. The first character is used for identification on the Advanced Space Compass. For non-beacons, this property is null. (See also: isBeacon)

`bounty`

bounty [read/write integer]

The bounty on the ship. This also determines its legal status. In the case of the player, it is halved at each witchspace jump.

`entityPersonality`

entityPersonality [read-only int]

A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the entityPersonalityInt [[http://wiki.alioth.net/index.php/Shaders_in_Oolite:_uniforms#Ship%7Cuniform binding.

`escorts`

target [read-only array of Entitys]

The ship’s deployed targets.

`fuel`

fuel [read/write double]

The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth. (See also: Player.fuelLeakRate)

`groupID`

groupID [read-only int]

The ID of the group to which this ship belongs. 0 for no group. An example of a group is a ship with escorts and the escorts.

`hasHostileTarget`

hasHostileTarget [read-only boolean]

true if the ship’s AI is trying to kill something, false otherwise. Always false for the player.

`hasSuspendedAI`

hasSuspendedAI [read-only boolean]

true if the ship has suspended AIs, false otherwise.

`heatInsulation`

heatInsulation [read/write double]

The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.

`isBeacon`

isBeacon [read-only boolean]

true if the ship is a beacon (i.e., can show up on the Advanced Space Compass with a character indicating its identity), false otherwise. (See also: beaconCode)

`isCloaked`

isCloaked [read/write boolean]

true if the ship has a cloaking device which is currently active false otherwise. If the ship has a cloaking device and sufficient energy to use it, you can activate it by setting isCloaked to true.

`isFrangible`

isFrangible [read-only boolean]

true if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), false otherwise. (See also: subEntities)

`isJamming`

isJamming [read-only boolean]

true if the ship has a military scanner jammer which is currently active false otherwise.

`maxCargo`

maxCargo [read-only integer]

The ship’s cargo capacity.

`maxSpeed`

maxSpeed [read-only double]

The ship’s maximum speed under normal power. Note that speed may exceed this when witch fuel injectors or hyperspeed are in use. (See also: speed)

`potentialCollider`

potentialCollider [read-only Entity]

The entity the ship is currently trying not to crash into, if any.

`reportAIMessages`

reportAIMessages [read/write boolean]

Debugging facility: set to true to dump information about AI activity to the log.

`roles`

roles [read-only array]

The roles of the ship. Probabilities are not included.

`scannerRange`

scannerRange [read-only double]

The range of the ship’s scanner.

`speed`

speed [read-only double]

The ship’s current speed. (See also: maxSpeed)

`shipDescription`

shipDescription [read-only string]

The name of the ship type (name key in shipdata.plist).

`subEntities`

subEntities [read-only array of Ships]

The ships subentities, or null if it has none. Special subentities such as flashers and exhaust plumes are not included. (See also: isFrangible)

`target`

target [read/write Oolite/Development/Scripting/Class/Ship|Ship]

The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.

`temperature`

temperature [read/write double]

The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.

`weaponRange`

weaponRange [read-only double]

The maximum range of the ship’s primary weapon.

`withinStationAegis`

withinStationAegis [read-only boolean]

true if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).

Methods

`deployEscorts`

deployEscorts()

Launch the ship’s escorts, if any.

`dockEscorts`

dockEscorts()

Dock the ship’s deployed escorts, if any.

`exitAI`

exitAI()

Exit the current AI, restoring the previous one. Equivalent to the exitAI: AI method. May not be used on player. Will generate a warning if there are no suspended AI states. (See also: AI, setAI(), hasSuspendedAI)

`reactToAIMessage`

reactToAIMessage(AIState)

Immediately execute the ship’s AI in the specified state.

`setAI`

setAI(AIName)

Set the current AI, leaving the old one suspended. Equivalent to the setAITo: AI method. May not be used on player. (See also: AI, switchAI(), exitAI())

`switchAI`

void switchAI(AIName)

Set the current AI, exiting the old one. Equivalent to the switchAITo: AI method. May not be used on player. (See also: AI, setAI(), exitAI())

@@ Line 9: / Line 9: @@
 == Properties ==
-=== <code>shipDescription</code> ===
- shipDescription [read-only string]
-The name of the ship type (<code>name</code> key in [[shipdata.plist]]).
-=== <code>roles</code> ===
- roles [read-only array]
-The roles of the ship. Probabilities are not included.
 === <code>AI</code> ===
  AI [read-only string]
@@ Line 25: / Line 17: @@
 The ship’s AI’s current state. (See also: <code>[[#AI|AI]]</code>, <code>[[#reactToAIMessage|reactToAIMessage()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>)
-=== <code>fuel</code> ===
+=== <code>beaconCode</code> ===
- fuel [read/write double]
+ beaconCode [read-only string]
-The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth. (See also: <code>[[Oolite/Development/Scripting/Class/Player#fuelLeakRate|Player.fuelLeakRate]]</code>)
+If the ship is a beacon, an identifying string. The first character is used for identification on the [[Advanced Space Compass]]. For non-beacons, this property is <code>null</code>. (See also: <code>[[#isBeacon|isBeacon]]</code>)
 === <code>bounty</code> ===
@@ Line 33: / Line 25: @@
 The bounty on the ship. This also determines its legal status. In the case of the player, it is halved at each witchspace jump.
-=== <code>subEntities</code> ===
+=== <code>entityPersonality</code> ===
- subEntities [read-only array of Ships]
+ entityPersonality [read-only int]
-The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included.
+A random number in the range 0..32767 which is generated when the ship is created. Equivalent to the <code>entityPersonalityInt</code> [[http://wiki.alioth.net/index.php/Shaders_in_Oolite:_uniforms#Ship|uniform binding</code>.
+=== <code>escorts</code> ===
+ target [read-only array of [[Oolite/Development/Scripting/Class/Entity|Entity]]s]
+The ship’s deployed targets.
+=== <code>fuel</code> ===
+ fuel [read/write double]
+The ship’s current fuel capacity, in LY. The game will limit this to the range 0..7, and round it off to the nearest tenth. (See also: <code>[[Oolite/Development/Scripting/Class/Player#fuelLeakRate|Player.fuelLeakRate]]</code>)
+=== <code>groupID</code> ===
+ groupID [read-only int]
+The ID of the group to which this ship belongs. 0 for no group. An example of a group is a ship with escorts and the escorts.
+=== <code>hasHostileTarget</code> ===
+ hasHostileTarget [read-only boolean]
+<code>true</code> if the ship’s AI is trying to kill something, <code>false</code> otherwise. Always <code>false</code> for the player.
 === <code>hasSuspendedAI</code> ===
  hasSuspendedAI [read-only boolean]
 <code>true</code> if the ship has suspended AIs, <code>false</code> otherwise.
+=== <code>heatInsulation</code> ===
+ heatInsulation [read/write double]
+The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.
+=== <code>isBeacon</code> ===
+ isBeacon [read-only boolean]
+<code>true</code> if the ship is a beacon (i.e., can show up on the [[Advanced Space Compass]] with a character indicating its identity), <code>false</code> otherwise. (See also: <code>[[#beaconCode|beaconCode]]</code>)
+=== <code>isCloaked</code> ===
+ isCloaked [read/write boolean]
+<code>true</code> if the ship has a cloaking device which is currently active <code>false</code> otherwise. If the ship has a cloaking device and sufficient energy to use it, you can activate it by setting <code>isCloaked</code> to <code>true</code>.
+=== <code>isFrangible</code> ===
+ isFrangible [read-only boolean]
+<code>true</code> if the ship is frangible (i.e., its subentities can be destroyed separately from the main ship), <code>false</code> otherwise. (See also: <code>[[#subEntities|subEntities]]</code>)
+=== <code>isJamming</code> ===
+ isJamming [read-only boolean]
+<code>true</code> if the ship has a military scanner jammer which is currently active <code>false</code> otherwise.
+=== <code>maxCargo</code> ===
+ maxCargo [read-only integer]
+The ship’s cargo capacity.
+=== <code>maxSpeed</code> ===
+ maxSpeed [read-only double]
+The ship’s maximum speed under normal power. Note that <code>[[#speed|speed]]</code> may exceed this when [[witch fuel injectors]] or [[hyperspeed]] are in use. (See also: <code>[[#speed|speed]]</code>)
+=== <code>potentialCollider</code> ===
+ potentialCollider [read-only Entity]
+The entity the ship is currently trying not to crash into, if any.
+=== <code>reportAIMessages</code> ===
+ reportAIMessages [read/write boolean]
+Debugging facility: set to <code>true</code> to dump information about AI activity to the log.
+=== <code>roles</code> ===
+ roles [read-only array]
+The roles of the ship. Probabilities are not included.
+=== <code>scannerRange</code> ===
+ scannerRange [read-only double]
+The range of the ship’s scanner.
+=== <code>speed</code> ===
+ speed [read-only double]
+The ship’s current speed. (See also: <code>[[#maxSpeed|maxSpeed]]</code>)
+=== <code>shipDescription</code> ===
+ shipDescription [read-only string]
+The name of the ship type (<code>name</code> key in [[shipdata.plist]]).
+=== <code>subEntities</code> ===
+ subEntities [read-only array of Ships]
+The ships subentities, or <code>null</code> if it has none. Special subentities such as flashers and exhaust plumes are not included. (See also: <code>[[#isFrangible|isFrangible]]</code>)
 === <code>target</code> ===
  target [read/write Oolite/Development/Scripting/Class/Ship|Ship]
 The ship’s primary target, i.e. the entity it will attempt to shoot at. This value is automatically co-ordinated between a ship and its subentities.
-=== <code>escorts</code> ===
- target [read-only array of [[Oolite/Development/Scripting/Class/Entity|Entity]]s]
-The ship’s deployed targets.
 === <code>temperature</code> ===
@@ Line 53: / Line 97: @@
 The ship’s temperature, normalized such that a temperature of 1.0 is the level at which a ship starts taking heat damage.
-=== <code>heatInsulation</code> ===
+=== <code>weaponRange</code> ===
- heatInsulation [read/write double]
+ weaponRange [read-only double]
-The ship’s heat insulation factor. 1.0 is normal, higher values mean more resistance to heat.
+The maximum range of the ship’s primary weapon.
+=== <code>withinStationAegis</code> ===
+ withinStationAegis [read-only boolean]
+<code>true</code> if the ship is within the aegis of the system’s main station (i.e., no more than 51 200 game metres from the station, or twice scanner range).
 == Methods ==
-=== <code>setAI</code> ===
+=== <code>deployEscorts</code> ===
- void setAI(AIName)
+ deployEscorts()
-Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. (See also: <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>)
+Launch the ship’s escorts, if any.
-=== <code>switchAI</code> ===
+=== <code>dockEscorts</code> ===
- void switchAI(AIName)
+ dockEscorts()
-Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player. (See also: <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>)
+Dock the ship’s deployed escorts, if any.
 === <code>exitAI</code> ===
- void exitAI()
+ exitAI()
 Exit the current AI, restoring the previous one. Equivalent to the <code>[[AI_methods|exitAI]]:</code> AI method. May not be used on player. Will generate a warning if there are no suspended AI states. (See also: <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#hasSuspendedAI|hasSuspendedAI]]</code>)
 === <code>reactToAIMessage</code> ===
- void reactToAIMessage(AIState)
+ reactToAIMessage(AIState)
 Immediately execute the ship’s AI in the specified state.
-=== <code>deployEscorts</code> ===
+=== <code>setAI</code> ===
- void deployEscorts()
+ setAI(AIName)
-Launch the ship’s escorts, if any.
+Set the current AI, leaving the old one suspended. Equivalent to the <code>[[AI_methods|setAITo]]:</code> AI method. May not be used on player. (See also: <code>[[#AI|AI]]</code>, <code>[[#switchAI|switchAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>)
-=== <code>dockEscorts</code> ===
+=== <code>switchAI</code> ===
- void dockEscorts()
+ void switchAI(AIName)
-Dock the ship’s deployed escorts, if any.
+Set the current AI, exiting the old one. Equivalent to the <code>[[AI_methods|switchAITo]]:</code> AI method. May not be used on player. (See also: <code>[[#AI|AI]]</code>, <code>[[#setAI|setAI()]]</code>, <code>[[#exitAI|exitAI()]]</code>)

Difference between revisions of "Oolite JavaScript Reference: Ship"

Revision as of 11:56, 4 August 2007

Contents

Properties

AI

AIState

beaconCode

bounty

entityPersonality

escorts

fuel

groupID

hasHostileTarget

hasSuspendedAI

heatInsulation

isBeacon

isCloaked

isFrangible

isJamming

maxCargo

maxSpeed

potentialCollider

reportAIMessages

roles

scannerRange

speed

shipDescription

subEntities

target

temperature

weaponRange

withinStationAegis