1 /**
  2  * @class entity
  3  * @description
  4  * extensible behavior object updated by the engine. Created with 
  5  * {@link sandboxe.entity.create}</br></br>
  6  *
  7  * Entities are the base object that provides means to easily 
  8  * include custom update behavior. Along with calling custom step and draw 
  9  * functions over time, with {@link component}s you can provide
 10  * a more manageable software platform fior youtr project. </br></br>
 11  *
 12  * Entities are arranged in a hierarchical fashion, where the root
 13  * is assigned using {@link sandboxe.engine.setRoot} 
 14  */
 15 
 16 function entity() {
 17 
 18     /**
 19      * Performs the normal draw iteration, which calls onDraw() for this entity,
 20      * draw() for all children entities, and draw() for all attached components.
 21      */
 22     this.draw = function(){};
 23 
 24     /**
 25      * Performs the normal draw iteration, which calls onStep() for this entity,
 26      * step() for all children entities, and step() for all attached components.
 27      */
 28     this.step = function(){};
 29 
 30     /**
 31      * Returns whether the entity has been removed from sandboxe. It will 
 32      * still be accessible, but not usable.
 33      * @returns {Boolean} Whether this entity is still valid.
 34      */
 35     this.valid = function(){};
 36 
 37     /**
 38      * Detaches and marks this entity for deletion.
 39      */
 40     this.remove = function(){};
 41 
 42     /**
 43      * Adds the given entity as a child. When a child, an Entity will be
 44      * updated when the World is updated.
 45      * @param {entity} child
 46      */
 47     this.attach = function(){};
 48 
 49     /**
 50      * Removes the child-parent relationship, detaching this entity from its parent.
 51      */
 52     this.detach = function(){};
 53 
 54     /**
 55      * Returns the number of children belonging to this entity.
 56      * @returns {Number}
 57      */
 58     this.getNumChildren = function(){};
 59 
 60     /**
 61      * Returns whether the given entity is contained within this entity.
 62      * @param {entity} queriedEntity 
 63      * @returns {Boolean}
 64      */
 65     this.contains = function(){};
 66 
 67     /**
 68      * Returns the i'th Entity starting at 0.
 69      *
 70      * Entities are ordered by priority, where the first entity
 71      * is guaranteed to be the one with the lowest Priority value.
 72      * @returns {Array} children
 73      */
 74     this.getChildren = function(){};
 75 
 76     /**
 77      * Returns all Entities that are within this Entity's hierarchy.
 78      * @returns {Array} allSubEntities
 79      */
 80     this.getAllSubEntities = function(){};
 81 
 82     /**
 83      * Returns all bound entities with the name equivalent to the one given within 
 84      * this entity's hierarchy.
 85      * @returns {Array} searchResults
 86      */
 87     this.findChildByName = function(){};
 88 
 89     /**
 90      * Convenienve function to create a new entity that is set 
 91      * as a child of this entity.
 92      * @returns {entity}
 93      */
 94     this.createChild = function(){};
 95 
 96     /**
 97      * Creates a new component as part of this entity.
 98      * @param {Number} type The component type to use. See {@link sandboxe.component.type} 
 99      * @returns {component} The component created.
100      */
101     this.addComponent = function(){};
102 
103     /**
104      * Returns the last recorded amount of milliseconds it took the
105      * Entity, iedentified by id, to complete its step cycle. A step cycle consists of the Entities
106      * Step function and any attached components' step.
107      * @returns {Number} 
108      */
109     this.stepDuration = function(){};
110 
111     /**
112      * Returns the last recorded amount of milliseconds it took the
113      * Entity, iedentified by id, to complete its draw cycle. A draw cycle consists of the Entities
114      * Draw function and any attached components' draw.
115      * @returns {Number}
116      */
117     this.drawDuration = function(){};
118 
119     /**
120      * Alters the priority of this entity.
121      *
122      * Priorty determines the order in which this
123      * entity is updated. A lower priority means it will be drawn and updated earlier.
124      * It is undefined which entity is updated first if both have the same priority.
125      * @param {Number} p The new priority.
126      */
127     this.setPriority = function(){};
128 
129 
130     /**
131      * Sends the entity of the ID to
132      * be the last of in line for drawing and updates.
133      */
134     this.setPriorityLast = function(){};
135 
136     /**
137      * Sends the entity to be drawn and updated as the last in the queue
138      * causing it to be on top when drawing.
139      */
140     this.setPriorityFirst = function(){};
141 
142     /**
143      * Returns the priority of the this entity.
144      * @returns {Number} priority value
145      */
146     this.getPriority = function(){};
147 
148     /**
149      * Returns the parent of the entity.
150      * @returns {entity} 
151      */
152     this.getParent = function(){};
153 
154     /**
155      * Returns whether this entity has a parent.
156      * @returns {Boolean}
157      */
158     this.hasParent = function(){};
159 
160 
161     /**
162      * Returns whether or not there is currently an attached component of the
163      * tag given if it exists. If there a multiple, the earliest component 
164      * added is returned.
165      * @returns {component}
166      */
167     this.queryComponent = function(){};
168 
169     /**
170      * Returns all components that belong to the Entity.
171      * @returns {Array} array of all components
172      */
173     this.getComponents = function(){};
174 
175     /**
176      * Removes the first occurrance of a component
177      * with the tag given.
178      *
179      * @param {String} tag The tag that identifies the component to remove.
180      */
181     this.removeComponent = function(){};
182 
183 
184 
185     /**
186      * Returns wether or not the engine is handling calling step() automatically,
187      * taking into account the Entity's hierarchy.
188      *
189      * @type {Boolean}
190      */
191     this.isStepping = 0;
192 
193     /**
194      * Returns wether or not the Engine is handling calling Draw() automatically,
195      * taking into account the Entity's hierarchy.
196      *
197      * @type {Boolean}
198      */
199     this.isDrawing = 0;
200 
201     /**
202      * The entity's unique ID.
203      *
204      * The ID uniquely identifies an entity. 
205      * @type {Number}
206      */
207     this.id = 0;
208 
209     /**
210      * The name identifier of the entity.
211      * The name is settable only the first time it is set. 
212      * Afterward, any further setting will have no effect.
213      * @type {String}
214      */
215     this.name = 0;
216 
217     /**
218      * The Node of the Entity, holding info such as the position and rotation.
219      *
220      * @type {transform}
221      */
222     this.node = 0;
223 
224     /**
225      * The global X position of this entity that considers all parents of this entity.
226      */
227     this.globalX = 0;    
228 
229     /**
230      * The global Y position of this entity that considers all parents of this entity.
231      */
232     this.globalY = 0;    
233 
234     /**
235      * The global Z position of this entity that considers all parents of this entity.
236      */
237     this.globalZ = 0;    
238 
239      
240     return this;
241 }
242