Difference between revisions of "Oolite JavaScript Reference: Entity"

From Elite Wiki
m (Added Oolite scripting category.)
m (Format clean-up.)
Line 13: Line 13:
   
 
== Properties ==
  
== Properties ==
  +
=== <code>distanceTravelled</code> ===
  +
'''distanceTravelled''' : Number (read-only)
  +
The distance the entity has travelled since being spawned, in game metres.
  +
  +
=== <code>energy</code> ===
  +
'''energy''' : Number (read/write)
  +
The entity’s total energy; ranges from 0 to <code>[[#maxEnergy|maxEnergy]]</code>.
  +
  +
=== <code>heading</code> ===
  +
'''heading''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-only)
  +
The heading of the entity. This is equivalent to <code>[[#orientation|orientation]]</code>, but ignoring the axial twist component (roll in the case of a ship).
  +
  +
<code>entity.heading()</code> is equivalent to <code>entity.[[#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#forwardVector|forwardVector]]()</code>.
  +
 
=== <code>ID</code> ===
  
=== <code>ID</code> ===
−
ID [read-only integer]
 +
'''ID''' : Number (read-only, integer)
 
The [[#Universal IDs|universal ID]] of the entity.
  
The [[#Universal IDs|universal ID]] of the entity.
   
−
=== <code>position</code> ===
 +
=== <code>mass</code> ===
−
position [read-only [[Oolite JavaScript Reference: Vector|Vector]]]
 +
'''mass''' : Number (read-only)
−
The position of the entity in system co-ordinates.
 +
The mass of the entity. Currently, this is directly proportional to the volume.
   
−
'''See Also:''' <code>[[#setPosition|setPosition]]()</code>
  
  +
=== <code>maxEnergy</code> ===
  +
'''maxEnergy''' : Number (read-only)
  +
The highest permissible value of <code>[[#energy|energy]]</code>.
   
 
=== <code>orientation</code> ===
  
=== <code>orientation</code> ===
−
orientation [read-only [[Oolite JavaScript Reference: Quaternion|Quaternion]]]
 +
'''orientation''' : [[Oolite JavaScript Reference: Quaternion|Quaternion]] (read-only)
 
The spacial orientation of the entity.
  
The spacial orientation of the entity.
   
 
'''See Also:''' <code>[[#setOrientation|setOrientation]]()</code>
  
'''See Also:''' <code>[[#setOrientation|setOrientation]]()</code>
   
−
=== <code>heading</code> ===
 +
=== <code>owner</code> ===
−
heading [read-only [[Oolite JavaScript Reference: Vector|Vector]]]
 +
'''owner''' : Entity (read-only)
−
The heading of the entity. This is equivalent to <code>[[#orientation|orientation]]</code>, but ignoring the axial twist component (roll in the case of a ship).
 +
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.
   
−
<code>entity.heading()</code> is equivalent to <code>entity.[[#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#forwardVector|forwardVector]]()</code>.
  
  +
=== <code>position</code> ===
  +
'''position''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-only)
  +
The position of the entity in system co-ordinates.
   
−
=== <code>status</code> ===
  
  +
'''See Also:''' <code>[[#setPosition|setPosition]]()</code>
−
status [read-only string]
  
−
The current status of the entity (such as “STATUS_IN_FLIGHT” and “STATUS_BEING_SCOOPED”).
  
   
 
=== <code>scanClass</code> ===
  
=== <code>scanClass</code> ===
−
scanClass [read-only string]
 +
'''scanClass''' : String (read-only)
 
The current scan class of the entity (such as “CLASS_NEUTRAL” and “CLASS_CARGO”).
  
The current scan class of the entity (such as “CLASS_NEUTRAL” and “CLASS_CARGO”).
   
−
=== <code>mass</code> ===
 +
=== <code>spawnTime</code> ===
−
mass [read-only double]
 +
'''spawnTime''' : Number (read-only)
−
The mass of the entity. Currently, this is directly proportional to the volume.
 +
The time at which the entity came into existence.
   
−
=== <code>owner</code> ===
 +
=== <code>status</code> ===
−
owner [read-only Entity]
 +
'''status''' : String (read-only)
−
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.
 +
The current status of the entity (such as “STATUS_IN_FLIGHT” and “STATUS_BEING_SCOOPED”).
   
−
=== <code>energy</code> ===
 +
=== <code>isPlanet</code> ===
−
energy [read-write double]
 +
'''isPlanet''' : Boolean (read-only)
−
The entity’s total energy; ranges from 0 to <code>[[#maxEnergy|maxEnergy]]</code>.
 +
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Planet|Planet]], <code>false</code> otherwise.
   
−
=== <code>maxEnergy</code> ===
 +
=== <code>isPlayer</code> ===
−
maxEnergy [read-only double]
 +
'''isPlayer''' : Boolean (read-only)
−
The highest permissible value of <code>[[#energy|energy]]</code>.
 +
<code>true</code> if the entity is the [[Oolite JavaScript Reference: Player|Player]], <code>false</code> otherwise.
−  
−
=== <code>isValid</code> ===
  
−
isValid [read-only boolean]
  
−
<code>true</code> if the entity is a valid entity variable, <code>false</code> if it is [[#Stale References|stale]].
  
   
 
=== <code>isShip</code> ===
  
=== <code>isShip</code> ===
−
isShip [read-only boolean]
 +
'''isShip''' : Boolean (read-only)
 
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Ship|Ship]], <code>false</code> otherwise.
  
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Ship|Ship]], <code>false</code> otherwise.
   
 
=== <code>isStation</code> ===
  
=== <code>isStation</code> ===
−
isStation [read-only boolean]
 +
'''isStation''' : Boolean (read-only)
 
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Station|Station]], <code>false</code> otherwise.
  
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Station|Station]], <code>false</code> otherwise.
   
 
=== <code>isSubEntity</code> ===
  
=== <code>isSubEntity</code> ===
−
isSubEntity [read-only boolean]
 +
'''isSubEntity''' : Boolean (read-only)
 
<code>true</code> if the entity is a subentity, <code>false</code> otherwise. A subentity’s owner can be acquired through the <code>[[#owner|owner]]</code> property.
  
<code>true</code> if the entity is a subentity, <code>false</code> otherwise. A subentity’s owner can be acquired through the <code>[[#owner|owner]]</code> property.
   
 
=== <code>isSun</code> ===
  
=== <code>isSun</code> ===
−
isSun [read-only boolean]
 +
'''isSun''' : Boolean (read-only)
 
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Sun|Sun]], <code>false</code> otherwise.
  
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Sun|Sun]], <code>false</code> otherwise.
   
−
=== <code>isPlayer</code> ===
 +
=== <code>isValid</code> ===
−
isPlayer [read-only boolean]
 +
'''isValid''' : Boolean (read-only)
−
<code>true</code> if the entity is the [[Oolite JavaScript Reference: Player|Player]], <code>false</code> otherwise.
 +
<code>true</code> if the entity is a valid entity variable, <code>false</code> if it is [[#Stale References|stale]].
−  
−
=== <code>isPlanet</code> ===
  
−
isPlanet [read-only boolean]
  
−
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Planet|Planet]], <code>false</code> otherwise.
  
−  
−
=== <code>distanceTravelled</code> ===
  
−
distanceTravelled [read-only double]
  
−
The distance the entity has travelled since being spawned, in game metres.
  
−  
−
=== <code>spawnTime</code> ===
  
−
spawnTime [read-only double]
  
−
The time at which the entity came into existence.
  
   
 
== Methods ==
  
== Methods ==
−
=== <code>setPosition</code> ===
 +
=== <code>call</code> ===
−
void setPosition([[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
 +
'''call'''(methodName : String, ...)
−
Instantaneously move the entity to the specified position.
 +
Call a method on the underlying Objective-C class. This is the same approach taken by script actions in plist scripts and AI actions in AI plists. The first argument is the name of the method to call. If the method takes a parameter (in which case it will end with a colon), any number of additional arguments may be specified; these will be concatenated together, separated by spaces, and passed the requested method. If the underlying method returns a value, it will be returned from <code>call()</code>, otherwise the result will be <code>undefined</code>.
   
 
=== <code>setOrientation</code> ===
  
=== <code>setOrientation</code> ===
−
void setOrientation([[Oolite JavaScript Reference: Quaternion#Quaternion Expressions|quaternionExpression]])
 +
'''setOrientation'''(orientation : [[Oolite JavaScript Reference: Quaternion#Quaternion Expressions|quaternionExpression]])
 
Instantaneously rotate the entity to the specified orientation.
  
Instantaneously rotate the entity to the specified orientation.
   
−
=== <code>call</code> ===
 +
=== <code>setPosition</code> ===
−
call(methodName, ...)
 +
'''setPosition'''(postion : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
−
Call a method on the underlying Objective-C class. This is the same approach taken by script actions in plist scripts and AI actions in AI plists. The first argument is the name of the method to call. If the method takes a parameter (in which case it will end with a colon), any number of additional arguments may be specified; these will be concatenated together, separated by spaces, and passed the requested method. If the underlying method returns a value, it will be returned from <code>call()</code>, otherwise the result will be <code>undefined</code>.
 +
Instantaneously move the entity to the specified position.
   
 
== Deprecated methods ==
  
== Deprecated methods ==
 
The following method is deprecated as of Oolite 1.70, and will be removed before the next stable release:
  
The following method is deprecated as of Oolite 1.70, and will be removed before the next stable release:
 
=== <code>valid</code> ===
  
=== <code>valid</code> ===
−
* <code>valid()</code>: use [[#isValid|isValid]] instead.
 +
* <code>'''valid'''() : Boolean</code>: use [[#isValid|isValid]] instead.
   
 
== Static methods ==
  
== Static methods ==
 
Static methods are methods which can be called on <code>Entity</code>, rather than an entity variable. Example: <code>var myEntity = Entity.entityWithID(142);</code>
  
Static methods are methods which can be called on <code>Entity</code>, rather than an entity variable. Example: <code>var myEntity = Entity.entityWithID(142);</code>
 
=== <code>entityWithID</code> ===
  
=== <code>entityWithID</code> ===
−
entityWithID(integer)
 +
'''entityWithID'''(ID : Number (integer)) : Entity
 
Returns the entity with the specified [[#Universal IDs|universal ID]].
  
Returns the entity with the specified [[#Universal IDs|universal ID]].
   

Revision as of 18:11, 6 December 2007

Prototype: Object
Subtypes: Planet, Ship, Sun

This class was added in Oolite test release 1.70.

The Entity class represents an object in the game universe. Ships, Stations, Planets and the Playerare 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

distanceTravelled

distanceTravelled : Number (read-only)

The distance the entity has travelled since being spawned, in game metres.

energy

energy : Number (read/write)

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

heading

heading : Vector (read-only)

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().

ID

ID : Number (read-only, integer)

The universal ID of the entity.

mass

mass : Number (read-only)

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

maxEnergy

maxEnergy : Number (read-only)

The highest permissible value of energy.

orientation

orientation : Quaternion (read-only)

The spacial orientation of the entity.

See Also: setOrientation()

owner

owner : Entity (read-only)

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.

position

position : Vector (read-only)

The position of the entity in system co-ordinates.

See Also: setPosition()

scanClass

scanClass : String (read-only)

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

spawnTime

spawnTime : Number (read-only)

The time at which the entity came into existence.

status

status : String (read-only)

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

isPlanet

isPlanet : Boolean (read-only)

true if the entity is a Planet, false otherwise.

isPlayer

isPlayer : Boolean (read-only)

true if the entity is the Player, false otherwise.

isShip

isShip : Boolean (read-only)

true if the entity is a Ship, false otherwise.

isStation

isStation : Boolean (read-only)

true if the entity is a Station, false otherwise.

isSubEntity

isSubEntity : Boolean (read-only)

true if the entity is a subentity, false otherwise. A subentity’s owner can be acquired through the owner property.

isSun

isSun : Boolean (read-only)

true if the entity is a Sun, false otherwise.

isValid

isValid : Boolean (read-only)

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

Methods

call

call(methodName : String, ...)

Call a method on the underlying Objective-C class. This is the same approach taken by script actions in plist scripts and AI actions in AI plists. The first argument is the name of the method to call. If the method takes a parameter (in which case it will end with a colon), any number of additional arguments may be specified; these will be concatenated together, separated by spaces, and passed the requested method. If the underlying method returns a value, it will be returned from call(), otherwise the result will be undefined.

setOrientation

setOrientation(orientation : quaternionExpression)

Instantaneously rotate the entity to the specified orientation.

setPosition

setPosition(postion : vectorExpression)

Instantaneously move the entity to the specified position.

Deprecated methods

The following method is deprecated as of Oolite 1.70, and will be removed before the next stable release:

valid

  • valid() : Boolean: use isValid instead.

Static methods

Static methods are methods which can be called on Entity, rather than an entity variable. Example: var myEntity = Entity.entityWithID(142);

entityWithID

entityWithID(ID : Number (integer)) : Entity

Returns the entity with the specified universal ID.

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