Eris  1.3.23
Entity.h
1 #ifndef ERIS_ENTITY_H
2 #define ERIS_ENTITY_H
3 
4 #include <Eris/Types.h>
5 
6 #include <Atlas/Objects/ObjectsFwd.h>
7 
8 #include <wfmath/point.h>
9 #include <wfmath/vector.h>
10 #include <wfmath/axisbox.h>
11 #include <wfmath/quaternion.h>
12 #include <wfmath/timestamp.h>
13 
14 #include <sigc++/trackable.h>
15 #include <sigc++/slot.h>
16 #include <sigc++/signal.h>
17 #include <sigc++/connection.h>
18 
19 #include <map>
20 #include <vector>
21 
22 namespace Atlas {
23  namespace Message {
24  class Element;
25  typedef std::map<std::string, Element> MapType;
26  }
27 }
28 
29 namespace Eris {
30 
31 // Forward Declerations
32 class Entity;
33 class TypeInfo;
34 class View;
35 class EntityRouter;
36 class Task;
37 
38 typedef std::vector<Entity*> EntityArray;
39 typedef std::vector<Task*> TaskArray;
40 typedef std::vector<TypeInfoPtr> TypeInfoArray;
41 
57 class Entity : virtual public sigc::trackable
58 {
59 public:
60  typedef std::map<std::string, Atlas::Message::Element> AttrMap;
61 
62  explicit Entity(const std::string& id, TypeInfo* ty);
63  virtual ~Entity();
64 
70  virtual void shutdown();
71 
72 // heirarchy interface
78  unsigned int numContained() const;
79 
85  Entity* getContained(unsigned int index) const;
86 
94  const Atlas::Message::Element& valueOfAttr(const std::string& attr) const;
95 
101  bool hasAttr(const std::string &p) const;
102 
106  typedef sigc::slot<void, const Atlas::Message::Element&> AttrChangedSlot;
107 
115  sigc::connection observe(const std::string& attr, const AttrChangedSlot& aslot);
116 
117 // accessors
122  const std::string& getId() const;
123 
129  const std::string& getName() const;
130 
135  float getStamp() const;
136 
141  TypeInfo* getType() const;
142 
147  Entity* getLocation() const;
148 
153  WFMath::Point<3> getPosition() const;
154 
162  const AttrMap getAttributes() const;
163 
171  const AttrMap& getInstanceAttributes() const;
172 
177  bool isMoving() const;
178 
184  WFMath::Point<3> getPredictedPos() const;
185 
190  WFMath::Vector<3> getPredictedVelocity() const;
191 
193  WFMath::Point<3> getViewPosition() const;
194 
196  WFMath::Quaternion getViewOrientation() const;
197 
199  const WFMath::Vector< 3 > & getVelocity(void) const;
200 
202  const WFMath::Quaternion & getOrientation(void) const;
203 
205  const WFMath::AxisBox< 3 > & getBBox(void) const;
206 
212  bool hasBBox() const;
213 
218  const TaskArray& getTasks() const;
219 
225  TypeInfoArray getUseOperations() const;
226 
227  bool hasChild(const std::string& eid) const;
228 
230  bool isVisible() const;
231 
244  static bool extractEntityId(const Atlas::Message::Element& element, std::string& id);
245 
246 // coordinate transformations
247  template<class C>
248  C toLocationCoords(const C& c) const;
249 
250  template<class C>
251  C fromLocationCoords(const C& c) const;
252 
253  // A vector (e.g., the distance between two points, or
254  // a velocity) gets rotated by a coordinate transformation,
255  // but doesn't get shifted by the change in the position
256  // of the origin, so we handle it separately. We also
257  // need to copy the vector before rotating, because
258  // Vector::rotate() rotates it in place.
259  WFMath::Vector<3> toLocationCoords(const WFMath::Vector<3>& v) const;
260 
261  WFMath::Vector<3> fromLocationCoords(const WFMath::Vector<3>& v) const;
262 
263 // Signals
264  sigc::signal<void, Entity*> ChildAdded;
265  sigc::signal<void, Entity*> ChildRemoved;
266 
268 
272  sigc::signal<void, Entity*> LocationChanged;
273 
276  sigc::signal<void, const StringSet&> Changed;
277 
279  sigc::signal<void> Moved;
280 
283  sigc::signal<void, bool> Moving;
284 
300  sigc::signal< void, const Atlas::Objects::Root & > Say;
301 
306  sigc::signal<void, const std::string&> Emote;
307 
313  sigc::signal<void, const Atlas::Objects::Operation::RootOperation&> Acted;
314 
320  sigc::signal<void, const Atlas::Objects::Root&> Noise;
321 
326  sigc::signal<void, bool> VisibilityChanged;
327 
333  sigc::signal<void> BeingDeleted;
334 
338  sigc::signal<void, Task*> TaskAdded;
342  sigc::signal<void, Task*> TaskRemoved;
343 protected:
347  virtual void init(const Atlas::Objects::Entity::RootEntity &ge, bool fromCreateOp);
348 
352  virtual void onTalk(const Atlas::Objects::Operation::RootOperation& talk);
353 
354  virtual void onAttrChanged(const std::string& attr, const Atlas::Message::Element &v);
355 
356  virtual void onLocationChanged(Entity* oldLoc);
357 
360  virtual void onMoved();
361 
365  virtual void onVisibilityChanged(bool vis);
366 
371  virtual void onAction(const Atlas::Objects::Operation::RootOperation& act);
372 
377  virtual void onSoundAction(const Atlas::Objects::Operation::RootOperation& op);
378 
383  virtual void onImaginary(const Atlas::Objects::Root& act);
384 
390  virtual void setMoving(bool moving);
391 
396  virtual void onChildAdded(Entity* child);
397 
402  virtual void onChildRemoved(Entity* child);
403 
408  virtual void onTaskAdded(Task* task);
409 
410  friend class IGRouter;
411  friend class View;
412  friend class Task;
413 
418  void sight(const Atlas::Objects::Entity::RootEntity& gent);
419 
420 
427  void setFromRoot(const Atlas::Objects::Root& obj, bool allowMotion, bool includeTypeInfoAttributes = false);
428 
431  void setVisible(bool vis);
432 
433  void setAttr(const std::string &p, const Atlas::Message::Element &v);
434 
439  bool nativeAttrChanged(const std::string &p, const Atlas::Message::Element &v);
440 
447  void typeInfo_AttributeChanges(const std::string& attributeName, const Atlas::Message::Element& element);
448 
455  virtual void attrChangedFromTypeInfo(const std::string& attributeName, const Atlas::Message::Element& element);
456 
457 
464  void fillAttributesFromType(Entity::AttrMap& attributes, TypeInfo* typeInfo) const;
465 
466  void beginUpdate();
467  void addToUpdate(const std::string& attr);
468  void endUpdate();
469 
472  void setLocationFromAtlas(const std::string& locId);
473 
477  void setLocation(Entity* newLocation);
478 
481  void setContentsFromAtlas(const StringList& contents);
482 
487  void filterMoveAttrs(Atlas::Message::MapType& attrs) const;
488 
489  typedef std::map<std::string, Entity*> IdEntityMap;
490  void buildEntityDictFromContents(IdEntityMap& dict);
491 
492  void addChild(Entity* e);
493  void removeChild(Entity* e);
494 
495  void addToLocation();
496  void removeFromLocation();
497 
498  void updateTasks(const Atlas::Message::Element& e);
499  void removeTask(Task* t);
500 
503  void updateCalculatedVisibility(bool wasVisible);
504 
506  {
507  public:
508  WFMath::Point<3> position;
509  WFMath::Vector<3> velocity;
510  };
511 
512  void updatePredictedState(const WFMath::TimeStamp& t);
513 
514  void createAlarmExpired();
515 
520  virtual TypeService* getTypeService() const = 0;
521 
526  virtual void removeFromMovementPrediction() = 0;
527 
532  virtual void addToMovementPredition() = 0;
533 
538  virtual Entity* getEntity(const std::string& id) = 0;
539 
540 
541  AttrMap m_attrs;
542 
543  TypeInfo* m_type;
544 
545 // primary state, in native form
546  Entity* m_location;
547  EntityArray m_contents;
548 
549  const std::string m_id;
550  std::string m_name;
551  float m_stamp;
552  std::string m_description;
553  bool m_visible;
554  bool m_limbo;
555 
556  WFMath::AxisBox<3> m_bbox;
557  WFMath::Point<3> m_position;
558  WFMath::Vector<3> m_velocity;
559  WFMath::Quaternion m_orientation;
560  WFMath::Vector<3> m_acc;
561 
562  DynamicState m_predicted;
563 
564 // extra state and state tracking things
569 
574  StringSet m_modifiedAttrs;
575 
576  typedef sigc::signal<void, const Atlas::Message::Element&> AttrChangedSignal;
577 
578  typedef std::map<std::string, AttrChangedSignal> ObserverMap;
579  ObserverMap m_observers;
580 
584  bool m_hasBBox;
585 
586  WFMath::TimeStamp m_lastMoveTime;
587  bool m_moving;
588 
590 
591  TaskArray m_tasks;
592 
593  bool m_initialised;
594 };
595 
596 inline unsigned int Entity::numContained() const {
597  return m_contents.size();
598 }
599 
600 inline Entity* Entity::getContained(unsigned int index) const {
601  return m_contents[index];
602 }
603 
604 inline const std::string& Entity::getId() const
605 {
606  return m_id;
607 }
608 
609 inline const std::string& Entity::getName() const
610 {
611  return m_name;
612 }
613 
614 inline float Entity::getStamp() const
615 {
616  return m_stamp;
617 }
618 
619 inline TypeInfo* Entity::getType() const
620 {
621  return m_type;
622 }
623 
626 {
627  return m_location;
628 }
629 
631 inline WFMath::Point<3> Entity::getPosition() const
632 {
633  return m_position;
634 }
636 inline const WFMath::Vector< 3 > & Entity::getVelocity(void) const
637 {
638  return m_velocity;
639 }
640 
642 inline const WFMath::Quaternion & Entity::getOrientation(void) const
643 {
644  return m_orientation;
645 }
646 
648 inline const WFMath::AxisBox< 3 > & Entity::getBBox(void) const
649 {
650  return m_bbox;
651 }
652 
653 inline bool Entity::hasBBox() const
654 {
655  return m_hasBBox;
656 }
657 
658 inline const TaskArray& Entity::getTasks() const
659 {
660  return m_tasks;
661 }
662 
663 template<class C>
664 inline C Entity::toLocationCoords(const C& c) const
665 {
666  return c.toParentCoords(getPredictedPos(), m_orientation);
667 }
668 
669 template<class C>
670 inline C Entity::fromLocationCoords(const C& c) const
671 {
672  return c.toLocalCoords(getPredictedPos(), m_orientation);
673 }
674 
675 inline WFMath::Vector<3> Entity::toLocationCoords(const WFMath::Vector<3>& v) const
676 {
677  return WFMath::Vector<3>(v).rotate(m_orientation);
678 }
679 
680 inline WFMath::Vector<3> Entity::fromLocationCoords(const WFMath::Vector<3>& v) const
681 {
682  return WFMath::Vector<3>(v).rotate(m_orientation.inverse());
683 }
684 
685 } // of namespace
686 
687 #endif
Eris::Entity::Say
sigc::signal< void, const Atlas::Objects::Root & > Say
Emitted with the entity speaks.
Definition: Entity.h:300
Eris::Entity::isVisible
bool isVisible() const
determine if this entity is visible.
Definition: Entity.cpp:785
Eris::Entity::onChildAdded
virtual void onChildAdded(Entity *child)
Over-rideable hook when child entities are added.
Definition: Entity.cpp:362
Eris::Entity::setContentsFromAtlas
void setContentsFromAtlas(const StringList &contents)
wrapper for setLocation with additional code the retrive the location if it's not available right now
Definition: Entity.cpp:693
Eris::Entity::hasAttr
bool hasAttr(const std::string &p) const
Checks whether an attribute exists.
Definition: Entity.cpp:124
Eris::Entity::typeInfo_AttributeChanges
void typeInfo_AttributeChanges(const std::string &attributeName, const Atlas::Message::Element &element)
Connected to the TypeInfo::AttributeChanges event.
Definition: Entity.cpp:472
Eris::Entity::observe
sigc::connection observe(const std::string &attr, const AttrChangedSlot &aslot)
Setup an observer so that the specified slot is fired when the named attribue's value changes.
Definition: Entity.cpp:163
Eris::Entity::onSoundAction
virtual void onSoundAction(const Atlas::Objects::Operation::RootOperation &op)
Over-rideable hook when this entity is heard performing an action.
Definition: Entity.cpp:332
Eris::Entity::valueOfAttr
const Atlas::Message::Element & valueOfAttr(const std::string &attr) const
Gets the value of a named attribute.
Definition: Entity.cpp:104
Eris::Entity::setLocationFromAtlas
void setLocationFromAtlas(const std::string &locId)
update the entity's location based on Atlas data.
Definition: Entity.cpp:626
Eris::Entity::getLocation
Entity * getLocation() const
The containing entity, or null if this is a top-level visible entity.
Definition: Entity.h:625
Eris::Entity::getContained
Entity * getContained(unsigned int index) const
Gets the child entity at the specified index.
Definition: Entity.h:600
Eris::Entity
Entity is a concrete (instantiable) class representing one game entity.
Definition: Entity.h:57
Eris::Entity::getPosition
WFMath::Point< 3 > getPosition() const
Returns the Entity's position inside it's parent in the parent's local system coordinates.
Definition: Entity.h:631
Eris::Entity::m_id
const std::string m_id
the Atlas object ID
Definition: Entity.h:549
Eris::Entity::Emote
sigc::signal< void, const std::string & > Emote
Emitted when this entity emits an imaginary operation (also known as an emote.
Definition: Entity.h:306
Eris::Entity::Changed
sigc::signal< void, const StringSet & > Changed
Emitted when one or more attributes change.
Definition: Entity.h:276
Eris::Entity::hasBBox
bool hasBBox() const
Returns true if the entity has a bounding box.
Definition: Entity.h:653
Eris::Entity::AttrChangedSlot
sigc::slot< void, const Atlas::Message::Element & > AttrChangedSlot
A slot which can be used for receiving attribute update signals.
Definition: Entity.h:106
Eris::Entity::m_hasBBox
bool m_hasBBox
This flag should be set when the server notifies that this entity has a bounding box.
Definition: Entity.h:584
Eris::Entity::updateCalculatedVisibility
void updateCalculatedVisibility(bool wasVisible)
recursively update the real visiblity of this entity, and fire appropriate signals.
Definition: Entity.cpp:795
Eris::Entity::isMoving
bool isMoving() const
Test if this entity has a non-zero velocity vector.
Definition: Entity.cpp:206
Eris::Entity::TaskAdded
sigc::signal< void, Task * > TaskAdded
Emitted when a task has been added to the entity.
Definition: Entity.h:338
Eris::Entity::getTypeService
virtual TypeService * getTypeService() const =0
Gets the typeservice used throughout the Eris system.
Eris::IGRouter
Definition: IGRouter.h:13
Eris::Entity::onChildRemoved
virtual void onChildRemoved(Entity *child)
Over-rideable hook when child entities are removed.
Definition: Entity.cpp:367
Eris::Entity::m_limbo
bool m_limbo
waiting for parent bind
Definition: Entity.h:554
Eris::TypeService
A service class querying and caching types.
Definition: TypeService.h:24
Eris::Entity::getTasks
const TaskArray & getTasks() const
Gets the tasks associated with this entity.
Definition: Entity.h:658
Eris::Entity::setLocation
void setLocation(Entity *newLocation)
setLocation is the core of the entity hierarchy maintenance logic.
Definition: Entity.cpp:648
Eris::Entity::getVelocity
const WFMath::Vector< 3 > & getVelocity(void) const
Returns the entity's velocity as last set explicitely.
Definition: Entity.h:636
Eris::Entity::getViewOrientation
WFMath::Quaternion getViewOrientation() const
retreive this Entity's orientation in view coordinates.
Definition: Entity.cpp:180
Eris::Entity::setAttr
void setAttr(const std::string &p, const Atlas::Message::Element &v)
Definition: Entity.cpp:380
Eris::Entity::TaskRemoved
sigc::signal< void, Task * > TaskRemoved
Emitted when a task has been removed from the entity.
Definition: Entity.h:342
Eris::Entity::onMoved
virtual void onMoved()
over-rideable hook method when then Entity position, orientation or velocity change.
Definition: Entity.cpp:322
Eris::Entity::getType
TypeInfo * getType() const
Gets the type of this entity.
Definition: Entity.h:619
Eris::Entity::setFromRoot
void setFromRoot(const Atlas::Objects::Root &obj, bool allowMotion, bool includeTypeInfoAttributes=false)
Initialise all simple state from a Root.
Definition: Entity.cpp:265
Eris::Entity::getAttributes
const AttrMap getAttributes() const
Gets all attributes defined for this entity.
Definition: Entity.cpp:138
Eris::TypeInfo::getParents
const TypeInfoSet & getParents() const
Gets the currently resolved parent TypeInfo instances.
Definition: TypeInfo.h:206
Eris::error
Definition: LogStream.h:55
Eris::Entity::removeFromMovementPrediction
virtual void removeFromMovementPrediction()=0
Removes the entity from any movement prediction service.
Eris::Entity::getStamp
float getStamp() const
Access the current time-stamp of the entity.
Definition: Entity.h:614
Eris::Entity::m_modifiedAttrs
StringSet m_modifiedAttrs
When a batched property update is in progress, the set tracks the names of each modified property.
Definition: Entity.h:574
Eris::Entity::onVisibilityChanged
virtual void onVisibilityChanged(bool vis)
over-rideable hook when the actual (computed) visiblity of this entity changed.
Definition: Entity.cpp:822
Eris::Entity::extractEntityId
static bool extractEntityId(const Atlas::Message::Element &element, std::string &id)
Extracts an entity id from the supplied element.
Definition: Entity.cpp:832
Eris::Entity::BeingDeleted
sigc::signal< void > BeingDeleted
Emitted prior to deletion.
Definition: Entity.h:333
Eris::Entity::getPredictedVelocity
WFMath::Vector< 3 > getPredictedVelocity() const
Retrieve the current predicted velocity of an entity.
Definition: Entity.cpp:201
Eris::Entity::getOrientation
const WFMath::Quaternion & getOrientation(void) const
Returns the entity's orientation as last set explicitely.
Definition: Entity.h:642
Eris::Alarm
Definition: Alarm.h:13
Eris::TypeService::getTypeByName
TypeInfoPtr getTypeByName(const std::string &tynm)
find the TypeInfo for the named type; this may involve a search, or a map lookup.
Definition: TypeService.cpp:62
Eris::Entity::getId
const std::string & getId() const
Retrieve the unique entity ID.
Definition: Entity.h:604
Eris::Entity::nativeAttrChanged
bool nativeAttrChanged(const std::string &p, const Atlas::Message::Element &v)
Map Atlas attributes to natively stored properties.
Definition: Entity.cpp:425
Eris::Entity::addToMovementPredition
virtual void addToMovementPredition()=0
Adds the entity to any movement prediction service.
Eris::Entity::filterMoveAttrs
void filterMoveAttrs(Atlas::Message::MapType &attrs) const
Remove from a map all items whose key is a movement related attribute, eg position or velocity.
Definition: Entity.cpp:295
Eris::Entity::onTaskAdded
virtual void onTaskAdded(Task *task)
Over-rideable hook for when tasks are added.
Definition: Entity.cpp:372
Eris::Entity::init
virtual void init(const Atlas::Objects::Entity::RootEntity &ge, bool fromCreateOp)
over-rideable initialisation helper.
Definition: Entity.cpp:90
Eris::InvalidOperation
Definition: Exceptions.h:28
Eris::Entity::Moved
sigc::signal< void > Moved
Emitted when then entity's position, orientation or velocity change.
Definition: Entity.h:279
Eris::Entity::getBBox
const WFMath::AxisBox< 3 > & getBBox(void) const
Returns the entity's bounding box in the entity's local system coordinates.
Definition: Entity.h:648
Eris::Entity::fillAttributesFromType
void fillAttributesFromType(Entity::AttrMap &attributes, TypeInfo *typeInfo) const
Utility method for recursively filling a map of attributes from a TypeInfo instance.
Definition: Entity.cpp:154
Eris::TypeInfo
The representation of an Atlas type (i.e a class or operation definition).
Definition: TypeInfo.h:37
Eris::Entity::setMoving
virtual void setMoving(bool moving)
over-rideable hook for when the entity changes from stationary to moving or vice-versa.
Definition: Entity.cpp:345
Eris::TypeInfo::getAttributes
const Atlas::Message::MapType & getAttributes() const
Gets the default attributes for this entity type.
Definition: TypeInfo.h:186
Eris::Entity::m_updateLevel
int m_updateLevel
If greater than zero, we are doing a batched update.
Definition: Entity.h:568
Eris::Entity::getViewPosition
WFMath::Point< 3 > getViewPosition() const
retreive this Entity's position in view coordinates.
Definition: Entity.cpp:169
Eris::Entity::setVisible
void setVisible(bool vis)
the View calls this to change local entity visibility.
Definition: Entity.cpp:773
Eris::Entity::m_name
std::string m_name
a human readable name
Definition: Entity.h:550
Eris::Entity::sight
void sight(const Atlas::Objects::Entity::RootEntity &gent)
Fully initialise all entity state based on a RootEntity, including location and contents.
Definition: Entity.cpp:257
Eris::Entity::getInstanceAttributes
const AttrMap & getInstanceAttributes() const
Gets all locally defined attributes.
Definition: Entity.cpp:149
Eris::TypeInfo::getAttribute
const Atlas::Message::Element * getAttribute(const std::string &attributeName) const
Gets the value of the named attribute.
Definition: TypeInfo.cpp:216
Eris::Entity::Noise
sigc::signal< void, const Atlas::Objects::Root & > Noise
Emitted when this entity performs an action which causes a noise.
Definition: Entity.h:320
Eris::Entity::m_recentlyCreated
bool m_recentlyCreated
flag set if this entity was the subject of a sight(create)
Definition: Entity.h:589
Eris::Entity::DynamicState
Definition: Entity.h:505
Eris::Entity::attrChangedFromTypeInfo
virtual void attrChangedFromTypeInfo(const std::string &attributeName, const Atlas::Message::Element &element)
Called when an attribute has been changed in the TypeInfo for this entity.
Definition: Entity.cpp:477
Eris::Entity::LocationChanged
sigc::signal< void, Entity * > LocationChanged
Signal that the entity's container changed.
Definition: Entity.h:272
Eris::Entity::m_moving
bool m_moving
flag recording if this entity is current considered in-motion
Definition: Entity.h:587
Eris::warning
Definition: LogStream.h:45
Eris::Entity::getName
const std::string & getName() const
Gets the name of the entity.
Definition: Entity.h:609
Eris::Entity::Acted
sigc::signal< void, const Atlas::Objects::Operation::RootOperation & > Acted
Emitted when this entity performs an action.
Definition: Entity.h:313
Eris::Entity::getEntity
virtual Entity * getEntity(const std::string &id)=0
Gets an entity with the supplied id from the system.
Eris::Entity::onTalk
virtual void onTalk(const Atlas::Objects::Operation::RootOperation &talk)
process TALK data - default implementation emits the Say signal.
Definition: Entity.cpp:304
Eris::Entity::m_stamp
float m_stamp
last modification time (in seconds)
Definition: Entity.h:551
Eris::Task
Definition: Task.h:25
Eris::View
View encapsulates the set of entities currently visible to an Avatar, as well as those that have rece...
Definition: View.h:33
Eris::Entity::numContained
unsigned int numContained() const
Gets the number of contained entities, i.e.
Definition: Entity.h:596
Eris::Entity::shutdown
virtual void shutdown()
Shuts down the entity.
Definition: Entity.cpp:65
Eris::Entity::onImaginary
virtual void onImaginary(const Atlas::Objects::Root &act)
Over-rideable hook when this entity is seen to emit an imginary op.
Definition: Entity.cpp:337
Eris::Entity::getPredictedPos
WFMath::Point< 3 > getPredictedPos() const
Retrieve the predicted position of this entity, based on it's velocity and acceleration.
Definition: Entity.cpp:191
Eris::Entity::VisibilityChanged
sigc::signal< void, bool > VisibilityChanged
Emitted when the visibility of the entity changes.
Definition: Entity.h:326
Eris::Entity::getUseOperations
TypeInfoArray getUseOperations() const
Get a list of operations supported by this entity (tool) If the entity does no provide an operations ...
Definition: Entity.cpp:226
Eris::Entity::Moving
sigc::signal< void, bool > Moving
Emitted when an entity starts or stops moving (as determined by the 'inMotion' method.
Definition: Entity.h:283
Eris::Entity::onAction
virtual void onAction(const Atlas::Objects::Operation::RootOperation &act)
Over-rideable hook when this entity is seen to perform an action.
Definition: Entity.cpp:327