Difference between revisions of "Oolite JavaScript Reference: Entity"

From Elite Wiki
(Added isSun.)
(→‎status)
 
(38 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
<small>'''Prototype:''' <code>Object</code></small><br />
  
<small>'''Prototype:''' <code>Object</code></small><br />
−
<small>'''Subtypes:''' <code>[[Oolite/Development/Scripting/Class/Planet|Planet]]</code>, <code>[[Oolite/Development/Scripting/Class/Ship|Ship]]</code>, <code>[[Oolite/Development/Scripting/Class/Sun|Sun]]</code></small>
 +
<small>'''Subtypes:''' <code>[[Oolite JavaScript Reference: Planet|Planet]]</code>, <code>[[Oolite JavaScript Reference: Ship|Ship]]</code>, <code>[[Oolite JavaScript Reference: Sun|Sun]]</code></small>
   
−
{{Oolite-future-scripting}}
  
  +
The '''<code>Entity</code>''' class represents an object in the game universe. <code>[[Oolite JavaScript Reference: Ship|Ship]]</code>s, <code>[[Oolite JavaScript Reference: Station|Station]]</code>s, <code>[[Oolite JavaScript Reference: Planet|Planet]]</code>s and <code>[[Oolite JavaScript Reference: Sun|Sun]]</code>s are 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|Ship]]</code>s, <code>[[Oolite/Development/Scripting/Class/Station|Station]]</code>s, <code>[[Oolite/Development/Scripting/Class/Planet|Planet]]</code>s and the <code>[[Oolite/Development/Scripting/Class/Player|Player]]</code>are types of entity. Note that these more specific types have additional properties and methods.
  
   
 
=== Stale References ===
  
=== 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.
 +
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>[[#isValid|isValid]]</code> property.
−  
−
=== Universal IDs ===
  
−
Every <code>Entity</code> has an unique universal ID. All Oolite-provided functions which take an <code>Entity</code> as an argument may also be passed an integer representing the <code>Entity</code>’s ID.
  
   
 
== Properties ==
  
== Properties ==
−
=== <code>ID</code> ===
 +
=== <code>collisionRadius</code> ===
−
ID [read-only integer]
 +
'''collisionRadius''' : Number (read-only)
−
The [[#Universal IDs|universal ID]] of the entity.
 +
The radius of the entity, in game meters. This is the radius of the spherical entity representation Oolite calculates with for non-colliding entities.
   
−
=== <code>position</code> ===
 +
=== <code>distanceTravelled</code> ===
−
position [read-only [[Oolite/Development/Scripting/Class/Vector|Vector]]]
 +
'''distanceTravelled''' : Number (read-only)
−
The position of the entity in system co-ordinates.
 +
The distance the entity has travelled since being spawned, in game meters. It only tracks the distance change generated by thrust. (useful for missiles). Distance traveled by an initial velocity, like with cargo pods, is not added in this value.
   
−
'''See Also:''' <code>[[#setPosition|setPosition]]()</code>
  
  +
=== <code>energy</code> ===
−  
  +
'''energy''' : Number (read/write)
−
=== <code>orientation</code> ===
  
  +
The entity’s total energy; ranges from 0 to <code>[[#maxEnergy|maxEnergy]]</code>.
−
orientation [read-only [[Oolite/Development/Scripting/Class/Quaternion|Quaternion]]]
  
−
The spacial orientation of the entity.
  
−  
−
'''See Also:''' <code>[[#setOrientation|setOrientation]]()</code>
  
   
 
=== <code>heading</code> ===
  
=== <code>heading</code> ===
−
heading [read-only [[Oolite/Development/Scripting/Class/Vector|Vector]]]
 +
'''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).
  
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/Development/Scripting/Class/Quaternion#forwardVector|forwardVector]]()</code>.
 +
<code>entity.heading()</code> is equivalent to <code>entity.[[#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#forwardVector|forwardVector]]()</code>.
   
−
=== <code>status</code> ===
 +
=== <code>isDock</code> ===
−
status [read-only string]
 +
{{oolite-prop-added|1.77}}
−
The current status of the entity (such as “STATUS_IN_FLIGHT” and “STATUS_BEING_SCOOPED”).
 +
'''isDock''' : Boolean (read-only)
  +
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Dock|Dock]], <code>false</code> otherwise.
   
−
=== <code>scanClass</code> ===
 +
=== <code>isInSpace</code> ===
−
scanClass [read-only string]
 +
{{oolite-prop-added|1.77}}
−
The current scan class of the entity (such as “CLASS_NEUTRAL” and “CLASS_CARGO”).
 +
'''isInSpace''' : Boolean (read-only)
  +
<code>true</code> if the entity is currently independently in real space, <code>false</code> otherwise (e.g. dead, docked, in a hold, in witchspace, etc.)
   
−
=== <code>mass</code> ===
 +
=== <code>isPlanet</code> ===
−
mass [read-only double]
 +
'''isPlanet''' : Boolean (read-only)
−
The mass of the entity. Currently, this is directly proportional to the volume.
 +
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Planet|Planet]], <code>false</code> otherwise.
   
−
=== <code>owner</code> ===
 +
=== <code>isPlayer</code> ===
−
owner [read-only Entity]
 +
'''isPlayer''' : Boolean (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.
 +
<code>true</code> if the entity is the [[Oolite JavaScript Reference: PlayerShip|player ship]], <code>false</code> otherwise.
−  
−
=== <code>energy</code> ===
  
−
energy [read-write double]
  
−
The entity’s total energy; ranges from 0 to <code>[[#maxEnergy|maxEnergy]]</code>.
  
−  
−
=== <code>maxEnergy</code> ===
  
−
maxEnergy [read-only double]
  
−
The highest permissible value of <code>[[#energy|energy]]</code>.
  
−  
−
=== <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/Development/Scripting/Class/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/Development/Scripting/Class/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> ===
−
isSubEntity [read-only boolean]
 +
'''isSun''' : Boolean (read-only)
−
<code>true</code> if the entity is a [[Oolite/Development/Scripting/Class/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>isSunlit</code> ===
−
isPlayer [read-only boolean]
 +
{{oolite-prop-added|1.89}}
−
<code>true</code> if the entity is the [[Oolite/Development/Scripting/Class/Player|Player]], <code>false</code> otherwise.
 +
'''isSunlit''' : Boolean (read-only)
  +
<code>true</code> if the entity is a currently being lit by the sun or <code>false</code> if in the shadow of another entity, like a planet or station.
   
−
=== <code>isPlanet</code> ===
 +
=== <code>isValid</code> ===
−
isPlanet [read-only boolean]
 +
'''isValid''' : Boolean (read-only)
−
<code>true</code> if the entity is a [[Oolite/Development/Scripting/Class/Planet|Planet]], <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>distanceTravelled</code> ===
 +
=== <code>isVisible</code> ===
−
distanceTravelled [read-only double]
 +
{{Oolite-prop-added|1.77}}
−
The distance the entity has travelled since being spawned, in game metres.
 +
'''isVisible''' : Boolean (read-only)
  +
Determines if the entity is close enough to the player to be drawn.
   
−
=== <code>spawnTime</code> ===
 +
=== <code>isVisualEffect</code> ===
−
spawnTime [read-only double]
 +
{{oolite-prop-added|1.77}}
−
The time at which the entity came into existence.
 +
'''isVisualEffect''' : Boolean (read-only)
  +
<code>true</code> if the entity is a [[Oolite JavaScript Reference: VisualEffect|VisualEffect]], <code>false</code> otherwise.
   
−
== Methods ==
  
  +
=== <code>isWormhole</code> ===
−
=== <code>setPosition</code> ===
  
  +
{{Oolite-prop-added|1.79}}
−
void setPosition([[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
  
  +
'''isWormhole''' : Boolean (read-only)
−
Instantaneously move the entity to the specified position.
  
  +
<code>true</code> if the entity is a [[Oolite JavaScript Reference: Wormhole|Wormhole]], <code>false</code> otherwise.
   
−
=== <code>setOrientation</code> ===
 +
=== <code>mass</code> ===
−
void setOrientation([[Oolite JavaScript Reference: Quaternion#Quaternion Expressions|quaternionExpression]])
 +
'''mass''' : Number (read-only)
−
Instantaneously rotate the entity to the specified orientation.
 +
The mass of the entity. Currently, this is directly proportional to the volume.
   
−
=== <code>call</code> ===
 +
=== <code>maxEnergy</code> ===
−
call(methodName, ...)
 +
'''maxEnergy''' : Number (read-only, read/write from 1.81)
−
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>.
 +
The highest permissible value of <code>[[#energy|energy]]</code>.
   
−
== Deprecated methods ==
  
  +
=== <code>orientation</code> ===
−
The following method is deprecated as of Oolite 1.70, and will be removed before the next stable release:
  
  +
'''orientation''' : [[Oolite JavaScript Reference: Quaternion|Quaternion]] (read/write)
−
=== <code>valid</code> ===
  
  +
−
* <code>valid()</code>: use [[#isValid|isValid]] instead.
 +
=== <code>owner</code> ===
  +
'''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 an escort, the group leader. In the case of a missile, the ship that launched it. There may be other uses.
  +
  +
=== <code>position</code> ===
  +
'''position''' : [[Oolite JavaScript Reference: Vector|Vector]] (read/write)
  +
  +
=== <code>scanClass</code> ===
  +
'''scanClass''' : String (read-only)
  +
The current scan class of the entity (such as “CLASS_NEUTRAL” and “CLASS_CARGO”).
  +
  +
In 1.77 or later, this is partially read/write for Ship entities other than the PlayerShip.
  +
  +
=== <code>spawnTime</code> ===
  +
'''spawnTime''' : Number (read-only)
  +
The time at which the entity came into existence.
  +
  +
=== <code>status</code> ===
  +
'''status''' : String (read-only)
  +
The current status of the entity. Possible values (though not an exhaustive list):
  +
* STATUS_IN_FLIGHT
  +
* STATUS_BEING_SCOOPED
  +
* STATUS_DOCKED
  +
* STATUS_WITCHSPACE_COUNTDOWN
  +
* STATUS_EXITING_WITCHSPACE
   
−
== Static methods ==
  
  +
[[Category:Oolite JavaScript Reference]]
−
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> ===
  
−
entityWithID(integer)
  
−
Returns the entity with the specified [[#Universal IDs|universal ID]].
  

Latest revision as of 23:32, 4 July 2021

Prototype: Object
Subtypes: Planet, Ship, Sun

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

Properties

collisionRadius

collisionRadius : Number (read-only)

The radius of the entity, in game meters. This is the radius of the spherical entity representation Oolite calculates with for non-colliding entities.

distanceTravelled

distanceTravelled : Number (read-only)

The distance the entity has travelled since being spawned, in game meters. It only tracks the distance change generated by thrust. (useful for missiles). Distance traveled by an initial velocity, like with cargo pods, is not added in this value.

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

isDock

This property was added in Oolite test release 1.77. 

isDock : Boolean (read-only)

true if the entity is a Dock, false otherwise.

isInSpace

This property was added in Oolite test release 1.77. 

isInSpace : Boolean (read-only)

true if the entity is currently independently in real space, false otherwise (e.g. dead, docked, in a hold, in witchspace, etc.)

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 ship, 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.

isSunlit

This property was added in Oolite test release 1.89. 

isSunlit : Boolean (read-only)

true if the entity is a currently being lit by the sun or false if in the shadow of another entity, like a planet or station.

isValid

isValid : Boolean (read-only)

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

isVisible

This property was added in Oolite test release 1.77. 

isVisible : Boolean (read-only)

Determines if the entity is close enough to the player to be drawn.

isVisualEffect

This property was added in Oolite test release 1.77. 

isVisualEffect : Boolean (read-only)

true if the entity is a VisualEffect, false otherwise.

isWormhole

This property was added in Oolite test release 1.79. 

isWormhole : Boolean (read-only)

true if the entity is a Wormhole, false otherwise.

mass

mass : Number (read-only)

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

maxEnergy

maxEnergy : Number (read-only, read/write from 1.81)

The highest permissible value of energy.

orientation

orientation : Quaternion (read/write)

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 an escort, the group leader. In the case of a missile, the ship that launched it. There may be other uses.

position

position : Vector (read/write)

scanClass

scanClass : String (read-only)

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

In 1.77 or later, this is partially read/write for Ship entities other than the PlayerShip.

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. Possible values (though not an exhaustive list):

  • STATUS_IN_FLIGHT
  • STATUS_BEING_SCOOPED
  • STATUS_DOCKED
  • STATUS_WITCHSPACE_COUNTDOWN
  • STATUS_EXITING_WITCHSPACE
Retrieved from "http://backup.witchspacewiki.org/index.php?title=Oolite_JavaScript_Reference:_Entity&oldid=66949"