Difference between revisions of "Oolite JavaScript Reference: Entity"

Revision as of 20:17, 17 June 2010

Prototype: Object
Subtypes: Planet, Ship, Sun

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

`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/write)

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/write)

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.

@@ Line 2: / Line 2: @@
 <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-class-added|1.70}}
+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 the <code>[[Oolite JavaScript Reference: Player|Player]]</code>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 JavaScript Reference: Vessel|Ship]]</code>s, <code>[[Oolite JavaScript Reference: Station|Station]]</code>s, <code>[[Oolite JavaScript Reference: Planet|Planet]]</code>s and the <code>[[Oolite JavaScript Reference: Player|Player]]</code>are types of entity. Note that these more specific types have additional properties and methods.
 === Stale References ===
@@ Line 26: / Line 24: @@
 <code>entity.heading()</code> is equivalent to <code>entity.[[#orientation|orientation]].[[Oolite JavaScript Reference: Quaternion#forwardVector|forwardVector]]()</code>.
-=== <code>ID</code> ===
-{{Oolite-script-item-deprecated|property|1.74}}
- '''ID''' : Number (read-only, integer)
-The [[#Universal IDs|universal ID]] of the entity.
 === <code>mass</code> ===
@@ Line 41: / Line 34: @@
 === <code>orientation</code> ===
- '''orientation''' : [[Oolite JavaScript Reference: Quaternion|Quaternion]] (read-only)
+ '''orientation''' : [[Oolite JavaScript Reference: Quaternion|Quaternion]] (read/write)
-The spacial orientation of the entity. (Since Oolite 1.73 read-write))
 '''See Also:''' <code>[[#setOrientation|setOrientation]]()</code>
@@ Line 50: / Line 43: @@
 === <code>position</code> ===
- '''position''' : [[Oolite JavaScript Reference: Vector|Vector]] (read-only)
+ '''position''' : [[Oolite JavaScript Reference: Vector|Vector]] (read/write)
-The position of the entity in system co-ordinates. (Since Oolite 1.73 read-write))
 '''See Also:''' <code>[[#setPosition|setPosition]]()</code>
@@ Line 93: / Line 86: @@
  '''isValid''' : Boolean (read-only)
 <code>true</code> if the entity is a valid entity variable, <code>false</code> if it is [[#Stale References|stale]].
-== Methods ==
-=== <code>call</code> ===
-<div class="boilerplate metadata" id="oolite-scripting-change" style="margin: 0 5%; padding: 0 7px 7px 7px; background: #EDF1F1; border: 1px solid #999999; text-align: left; font-size:95%;"><small>Starting in Oolite test release '''1.72''', the <code>call()</code> method will only be available with the [[Debug OXP]] installed. Additionally, <code>call()</code> will only ever be available in test releases.</small></div>
- function '''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 <code>call()</code>, otherwise the result will be <code>undefined</code>.
-=== <code>setOrientation</code> ===
-{{Oolite-script-item-deprecated|method|1.74}}
- function '''setOrientation'''(orientation : [[Oolite JavaScript Reference: Quaternion#Quaternion Expressions|quaternionExpression]])
-Assign a value to the <code>[[#orientation|orientation]]</code> property instead.
-=== <code>setPosition</code> ===
-{{Oolite-script-item-deprecated|method|1.74}}
- function '''setPosition'''(postion : [[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
-Assign a value to the <code>[[#position|position]]</code> property instead.
-== 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>
-=== <code>entityWithID</code> ===
-{{Oolite-script-item-deprecated|method|1.74}}
- '''entityWithID'''(ID : Number (integer)) : Entity
-Returns the entity with the specified [[#Universal IDs|universal ID]].
 [[Category:Oolite scripting]]