| | 1 | '''Pyrogenesis Object Model : Entity Class''' |
| | 2 | |
| | 3 | The Entity class allows interaction with engine entities from within !JavaScript. This class is designed to be user-extensible, with only the minimum required functionality being defined by the engine, leaving other properties and methods to be defined and used via data files and scripting. This class also supports Prometheus' inheritance system, meaning an entity will, by default, use the properties of it's template object (see !EntityTemplate), though these properties can be modified or overridden at will. |
| | 4 | |
| | 5 | = Entity Methods = |
| | 6 | |
| | 7 | == Entity (Constructor) == |
| | 8 | * '''Overview:''' |
| | 9 | * Instantiates an Entity object. |
| | 10 | * '''Syntax:''' |
| | 11 | * new Entity( templateObject, position ); |
| | 12 | * new Entity( className, position ); |
| | 13 | * new Entity( templateObject, position, orientation ); |
| | 14 | * new Entity( className, position, orientation ); |
| | 15 | * '''Parameters:''' |
| | 16 | * templateObject: An !EntityTemplate object representing the class of the new entity. |
| | 17 | * className: A string giving the class name of the new entity (used to retrieve the appropriate !EntityTemplate). |
| | 18 | * position: A Vector3D giving the position in the world the entity should be created at. |
| | 19 | * orientation: A real number giving the initial orientation of the entity, in radians. If unspecifed, defaults to zero orientation. |
| | 20 | * '''Returns:''' |
| | 21 | * An Entity object with the specified state. |
| | 22 | * '''Notes:''' |
| | 23 | * The entity is immediately registered and begins taking part in the simulation. |
| | 24 | |
| | 25 | == toString (Implicit) == |
| | 26 | * '''Overview:''' |
| | 27 | * Overrides the default string conversion to include the name and type of this entity. |
| | 28 | * '''Syntax:''' |
| | 29 | * toString(); |
| | 30 | * '''Parameters:''' |
| | 31 | * None. |
| | 32 | * '''Returns:''' |
| | 33 | * A string of the form '[object Entity "<Name>" (<Class>)]'. |
| | 34 | * '''Notes:''' |
| | 35 | * This function is called implicitly by the !JavaScript engine to convert this object to a string. |
| | 36 | |
| | 37 | = Entity Properties = |
| | 38 | |
| | 39 | These are the properties currently defined for entities by the engine. A more complete list, including the properties defined by data for 0 A.D., can be found in the design document. |
| | 40 | |
| | 41 | == template == |
| | 42 | * '''Overview:''' |
| | 43 | * Gets or sets a reference to the template object, used to determine this entity's class. |
| | 44 | * '''Type:''' |
| | 45 | * !EntityTemplate |
| | 46 | |
| | 47 | == name == |
| | 48 | * '''Overview:''' |
| | 49 | * Gets or sets the entity's displayed name. |
| | 50 | * '''Type:''' |
| | 51 | * string |
| | 52 | * '''Notes:''' |
| | 53 | * This property can be inherited from the class template. |
| | 54 | |
| | 55 | == extant == |
| | 56 | * '''Overview:''' |
| | 57 | * Gets or sets a value that determines whether the entity is still active in the simulation. |
| | 58 | * '''Type:''' |
| | 59 | * boolean |
| | 60 | * '''Notes:''' |
| | 61 | * If extant is false, no processing whatsoever is performed on the entity. Such a state indicates that, while the memory for the entity is still allocated, no guarantee can be made about the state of any property other than this one. For this reason, it is not valid to set this property to true once it has become false. |
| | 62 | |
| | 63 | == selected == |
| | 64 | * '''Overview:''' |
| | 65 | * Gets or sets a value that determines whether the entity is selected. |
| | 66 | * '''Type:''' |
| | 67 | * boolean |
| | 68 | |
| | 69 | == group == |
| | 70 | * '''Overview:''' |
| | 71 | * Gets or sets a value indicating the entity's current group. |
| | 72 | * '''Type:''' |
| | 73 | * integer |
| | 74 | * '''Notes:''' |
| | 75 | * -1 indicates that the entity is ungrouped. |
| | 76 | |
| | 77 | == position == |
| | 78 | * '''Overview:''' |
| | 79 | * Gets or sets the position of this entity. |
| | 80 | * '''Type:''' |
| | 81 | * Vector3D |
| | 82 | |
| | 83 | == orientation == |
| | 84 | * '''Overview:''' |
| | 85 | * Gets or sets the orientation of this entity, in radians. |
| | 86 | * '''Type:''' |
| | 87 | * double |
| | 88 | |
| | 89 | == speed == |
| | 90 | * '''Overview:''' |
| | 91 | * Gets or sets the maximum speed of this entity. |
| | 92 | * '''Type:''' |
| | 93 | * double |
| | 94 | * '''Notes:''' |
| | 95 | * This property can be inherited from the class template. |
| | 96 | |
| | 97 | == turningRadius == |
| | 98 | * '''Overview:''' |
| | 99 | * Gets or sets the minimum turning radius of this entity. |
| | 100 | * '''Type:''' |
| | 101 | * double |
| | 102 | * '''Notes:''' |
| | 103 | * This property can be inherited from the class template. |
| | 104 | |
| | 105 | = Entity Global Functions = |
| | 106 | |
| | 107 | == getEntityByHandle == |
| | 108 | * '''Overview:''' |
| | 109 | * Retrieve the entity currently occupying the specified handle. |
| | 110 | * Caution, debug only. |
| | 111 | * '''Syntax:''' |
| | 112 | * entity = getEntityByHandle( handle ); |
| | 113 | * '''Parameters:''' |
| | 114 | * handle [int] |
| | 115 | * '''Returns:''' |
| | 116 | * An object representing the entity occupying the handle, or null, if the argument is invalid or the specified handle is unused. |
| | 117 | * '''Notes:''' |
| | 118 | * Handles are a low-level internal representation of entities, and their use by !JavaScript is not recommended where an alternative is available. Details of handle allocation and implementation may change. Handles are allocated starting from 0. |
| | 119 | |
| | 120 | == getEntityTemplate == |
| | 121 | * '''Overview:''' |
| | 122 | * Retrieves the entity template object (holding attributes shared amongst all entities of that type) for the class with the specified name. |
| | 123 | * Deprecated. Will be removed shortly. |
| | 124 | |
| | 125 | = Entity Global Objects = |
| | 126 | |
| | 127 | == groups == |
| | 128 | * '''Overview:''' |
| | 129 | * Gets or sets an array representing the selection groups. |
| | 130 | * Caution, not multiplayer-safe. |
| | 131 | * '''Type:''' |
| | 132 | * Array of !EntityCollection |
| | 133 | |
| | 134 | == selection == |
| | 135 | * '''Overview:''' |
| | 136 | * Gets or sets a !JavaScript object representing the current selection. |
| | 137 | * Caution, not multiplayer-safe. |
| | 138 | * '''Type:''' |
| | 139 | * !EntityCollection |
