Difference between revisions of "Oolite JavaScript Reference: Entity"

Revision as of 17:23, 3 August 2007

Prototype: Object
Subtypes: Ship, Planet

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 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

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

`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.

`isValid`

isValid [read-only boolean]

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

`isShip`

isShip [read-only boolean]

true if the entity is a Ship, false otherwise.

`isStation`

isStation [read-only boolean]

true if the entity is a Station, false otherwise.

`isPlayer`

isPlayer [read-only boolean]

true if the entity is the Player, false otherwise.

`isPlanet`

isPlanet [read-only boolean]

true if the entity is a Planet, false otherwise.

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.

`call`

call(methodName, ...)

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.

Deprecated methods

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

`valid`

valid(): 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(integer)

Returns the entity with the specified universal ID.

@@ Line 58: / Line 58: @@
  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> ===
+ isShip [read-only boolean]
+<code>true</code> if the entity is a [[Oolite/Development/Scripting/Class/Ship|Ship]], <code>false</code> otherwise.
+=== <code>isStation</code> ===
+ isStation [read-only boolean]
+<code>true</code> if the entity is a [[Oolite/Development/Scripting/Class/Station|Station]], <code>false</code> otherwise.
+=== <code>isPlayer</code> ===
+ isPlayer [read-only boolean]
+<code>true</code> if the entity is the [[Oolite/Development/Scripting/Class/Player|Player]], <code>false</code> otherwise.
+=== <code>isPlanet</code> ===
+ isPlanet [read-only boolean]
+<code>true</code> if the entity is a [[Oolite/Development/Scripting/Class/Planet|Planet]], <code>false</code> otherwise.
 == Methods ==
 === <code>setPosition</code> ===
- void setPosition([[Oolite/Development/Scripting/Class/Vector#Vector Expressions|vectorExpression]])
+ void setPosition([[Oolite JavaScript Reference: Vector#Vector Expressions|vectorExpression]])
 Instantaneously move the entity to the specified position.
 === <code>setOrientation</code> ===
- void setOrientation([[Oolite/Development/Scripting/Class/Quaternion#Quaternion Expressions|quaternionExpression]])
+ void setOrientation([[Oolite JavaScript Reference: Quaternion#Quaternion Expressions|quaternionExpression]])
 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]].
 === <code>call</code> ===
  call(methodName, ...)
 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>.
+== Deprecated methods ==
+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>: use [[#isValid|isValid]] 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> ===
+ entityWithID(integer)
+Returns the entity with the specified [[#Universal IDs|universal ID]].