Difference between revisions of "Oolite JavaScript Reference: Entity"

From Elite Wiki
m (<code>heading</code>)
(Added valid().)
Line 2: Line 2:
  
 
The '''<code>Entity</code>''' class represents an object in the game universe – <code>[[Oolite/Development/Scripting/Class/Vessel|Vessel]]</code>s, <code>[[Oolite/Development/Scripting/Class/Station|Station]]</code>s and <code>[[Oolite/Development/Scripting/Class/CelestialBody|CelestialBody]]</code>s are common types of entity. Note that these more specific types have additional properties and methods.
 
The '''<code>Entity</code>''' class represents an object in the game universe – <code>[[Oolite/Development/Scripting/Class/Vessel|Vessel]]</code>s, <code>[[Oolite/Development/Scripting/Class/Station|Station]]</code>s and <code>[[Oolite/Development/Scripting/Class/CelestialBody|CelestialBody]]</code>s are common types of entity. Note that these more specific types have additional properties and methods.
 +
 +
=== Stale References ===
 +
When an entity dies or is otherwise removed from the game universe (for instance, because player jumped from the system), existing <code>Entity</code> variables referring to the entity become invalid; all their properties become <code>undefined</code>, and their methods do nothing. In addition to the undefined properties, this can be detected with the <code>[[#valid|valid]]()</code> method.
  
 
=== Universal IDs ===
 
=== Universal IDs ===
Line 71: Line 74:
 
  void setOrientation([[Oolite/Development/Scripting/Class/Quaternion#Quaternion Expressions|quaternionExpression]])
 
  void setOrientation([[Oolite/Development/Scripting/Class/Quaternion#Quaternion Expressions|quaternionExpression]])
 
Instantaneously rotate the entity to the specified orientation.
 
Instantaneously rotate the entity to the specified orientation.
 +
 +
=== <code>valid</code> ===
 +
boolean valid()
 +
Returns <code>true</code> if the target is a valid entity variable, <code>false</code> if it is [[#Stale References|stale]].
  
  
 
[[Category:Oolite scripting]] [[Category:Oolite Development]]
 
[[Category:Oolite scripting]] [[Category:Oolite Development]]

Revision as of 16:17, 6 April 2007

The Entity class represents an object in the game universe – Vessels, Stations and CelestialBodys are common types of entity. Note that these more specific types have additional properties and methods.

Stale References

When an entity dies or is otherwise removed from the game universe (for instance, because player jumped from the system), existing Entity variables referring to the entity become invalid; all their properties become undefined, and their methods do nothing. In addition to the undefined properties, this can be detected with the valid() method.

Universal IDs

Every Entity has an unique universal ID. All Oolite-provided functions which take an Entity as an argument may also be passed an integer representing the Entity’s ID.

Properties

ID

ID [read-only integer]

The universal ID of the entity.

position

position [read-only Vector]

The position of the entity in system co-ordinates.

See Also: setPosition()

velocity

velocity [read-only Vector]

The velocity of the entity in system units (nominal metres) per second.

speed

speed [read-only double]

The speed of the entity in system units (nominal metres) per second.

entity.speed() is equivalent to entity.velocity().magnitude().

orientation

orientation [read-only Quaternion]

The spacial orientation of the entity.

See Also: setOrientation()

heading

heading [read-only Vector]

The heading of the entity. This is equivalent to orientation, but ignoring the axial twist component (roll in the case of a ship).

entity.heading() is equivalent to entity.orientation.forwardVector().

status

status [read-only string]

The current status of the entity (such as “STATUS_IN_FLIGHT” and “STATUS_BEING_SCOOPED”).

scanClass

scanClass [read-only string]

The current scan class of the entity (such as “CLASS_NEUTRAL” and “CLASS_CARGO”).

mass

mass [read-only double]

The mass of the entity. Currently, this is directly proportional to the volume.

owner

owner [read-only Entity]

The entity which owns this one. In the case of a subentity, the entity to which it is attached. In the case of a defense ship, the station it belongs to. In the case of a missile, the ship that launched it. There may be other uses.

energy

energy [read-write double]

The entity’s total energy; ranges from 0 to maxEnergy.

maxEnergy

maxEnergy [read-only double]

The highest permissible value of energy.

Methods

setPosition

void setPosition(vectorExpression)

Instantaneously move the entity to the specified position.

setOrientation

void setOrientation(quaternionExpression)

Instantaneously rotate the entity to the specified orientation.

valid

boolean valid()

Returns true if the target is a valid entity variable, false if it is stale.