This class represents game entities, which are the basic elements of a world. More...

#include "Entity.hpp"

Inheritance diagram for cf::GameSys::EntityT:

Public Member Functions
	EntityT (const EntityCreateParamsT &Params)
	The normal constructor. More...

	EntityT (const EntityT &Entity, bool Recursive=false)
	The copy constructor. More...

virtual EntityT *	Clone (bool Recursive=false) const
	The virtual copy constructor. More...

virtual	~EntityT ()
	The virtual destructor. Deletes this entity and all its children. More...

WorldT &	GetWorld () const

unsigned int	GetID () const
	Returns the ID of this entity. More...

IntrusivePtrT< EntityT >	GetParent () const
	Returns the parent entity of this entity. More...

const ArrayT< IntrusivePtrT < EntityT > > &	GetChildren () const
	Returns the immediate children of this entity. More...

void	GetChildren (ArrayT< IntrusivePtrT< EntityT > > &Chld, bool Recurse=false) const
	Returns the children of this entity. More...

void	GetAll (ArrayT< IntrusivePtrT< EntityT > > &List)
	Traverses the hierarchy (sub-tree) that is rooted at this entity in depth-first order and records all encountered entities in the given list. More...

bool	AddChild (IntrusivePtrT< EntityT > Child, unsigned long Pos=0xFFFFFFFF)
	Adds the given entity to the children of this entity, and sets this entity as the parent of the child. More...

bool	RemoveChild (IntrusivePtrT< EntityT > Child)
	Removes the given entity from the children of this entity. More...

IntrusivePtrT< EntityT >	GetRoot ()
	Returns the top-most parent of this entity, that is, the root of the hierarchy that this entity is in. More...

IntrusivePtrT< ComponentBaseT >	GetApp ()
	Returns the application component of this entity. More...

IntrusivePtrT< const ComponentBaseT >	GetApp () const
	The `const` variant of the GetApp() method above. See GetApp() for details. More...

void	SetApp (IntrusivePtrT< ComponentBaseT > App)
	Sets the application component for this entity. See GetApp() for details. More...

IntrusivePtrT< ComponentBasicsT >	GetBasics () const
	Returns the "Basics" component of this entity. More...

IntrusivePtrT < ComponentTransformT >	GetTransform () const
	Returns the "Transform" component of this entity. More...

const ArrayT< IntrusivePtrT < ComponentBaseT > > &	GetComponents () const
	Returns the components that this entity is composed of. More...

IntrusivePtrT< ComponentBaseT >	GetComponent (const std::string &TypeName, unsigned int n=0) const
	Returns the (`n`-th) component of the given (type) name. More...

IntrusivePtrT< ComponentBaseT >	GetComponent (unsigned int n) const
	Returns the `n`-th component of this entity, covering both the "custom" as well as the fixed components (application, "Basics" and "Transform"). More...

bool	AddComponent (IntrusivePtrT< ComponentBaseT > Comp, unsigned long Index=ULONG_MAX)
	Adds the given component to this entity. More...

void	DeleteComponent (unsigned long CompNr)
	Deletes the component at the given index from this entity. More...

IntrusivePtrT< EntityT >	FindID (unsigned int WantedID)
	Finds the entity with the given ID in the hierachy tree of this entity. More...

IntrusivePtrT< EntityT >	Find (const std::string &WantedName)
	Finds the entity with the name WantedName in the hierachy tree of this entity. More...

void	FindByComponent (const std::string &TypeName, ArrayT< IntrusivePtrT< EntityT > > &Result)
	Finds all entities in the hierachy tree of this entity that have at least one component of the given (type) name. More...

bool	Has (IntrusivePtrT< EntityT > Ent) const
	Returns whether the given entity is in the hierarchy (sub-tree) of this entity. More...

BoundingBox3fT	GetCullingBB (bool WorldSpace) const
	Returns a bounding-box that encloses the visual representation of this entity. More...

void	Serialize (cf::Network::OutStreamT &Stream, bool WithChildren=false) const
	Writes the current state of this entity into the given stream. More...

void	Deserialize (cf::Network::InStreamT &Stream, bool IsIniting)
	Reads the state of this entity from the given stream, and updates the entity accordingly. More...

bool	RenderComponents (bool FirstPersonView, float LodDist) const
	Renders the components of this entity. More...

virtual bool	OnInputEvent (const CaKeyboardEventT &KE)
	Keyboard input event handler. More...

virtual bool	OnInputEvent (const CaMouseEventT &ME, float PosX, float PosY)
	Mouse input event handler. More...

void	OnServerFrame (float t)
	Advances the entity one frame (one "clock-tick") on the server. More...

void	OnClientFrame (float t)
	Advances the entity one frame (one "clock-tick") on the client. More...

bool	CallLuaMethod (const char MethodName, int NumExtraArgs, const char Signature="",...)
	Calls the Lua method with name `MethodName` of this entity. More...

virtual const cf::TypeSys::TypeInfoT *	GetType () const

Public Member Functions inherited from RefCountedT
unsigned int	GetRefCount () const

Static Public Member Functions
static void *	CreateInstance (const cf::TypeSys::CreateParamsT &Params)

Static Public Attributes
static const cf::TypeSys::TypeInfoT	TypeInfo

Static Protected Member Functions
static int	GetID (lua_State *LuaState)

static int	AddChild (lua_State *LuaState)

static int	RemoveChild (lua_State *LuaState)

static int	GetParent (lua_State *LuaState)

static int	GetRoot (lua_State *LuaState)

static int	GetChildren (lua_State *LuaState)

static int	FindByID (lua_State *LuaState)

static int	FindByName (lua_State *LuaState)

static int	FindByComponent (lua_State *LuaState)

static int	GetBasics (lua_State *LuaState)

static int	GetTransform (lua_State *LuaState)

static int	AddComponent (lua_State *LuaState)

static int	RmvComponent (lua_State *LuaState)

static int	GetComponents (lua_State *LuaState)

static int	GetComponent (lua_State *LuaState)

static int	toString (lua_State *LuaState)

Static Protected Attributes
static const luaL_Reg	MethodsList []
	List of methods registered with Lua. More...

static const char *	DocClass

static const cf::TypeSys::MethsDocT	DocMethods []

static const cf::TypeSys::MethsDocT	DocCallbacks []

Additional Inherited Members
Protected Member Functions inherited from RefCountedT
	RefCountedT (const RefCountedT &)

RefCountedT &	operator= (const RefCountedT &)

Detailed Description

This class represents game entities, which are the basic elements of a world.

EntityT instances can be created in C++ code or in Lua scripts, using the world:new() function. They can be passed from C++ code to Lua and from Lua to C++ code at will. In C++ code, all EntityT instances are kept in IntrusivePtrT's. Their lifetime is properly managed: An entity is deleted automatically when it is no longer used in Lua and in C++. That is, code like Example 1: w = world:new("EntityT"); world:SetRootEntity(w); w = nil; Example 2: w = world:new("EntityT"); w:AddChild(world:new("EntityT")); works as expected. See the cf::ScriptBinderT class for technical and implementation details.

Constructor & Destructor Documentation

EntityT::EntityT ( const EntityCreateParamsT & Params )

The normal constructor.

Parameters

Params The creation parameters for the entity.

EntityT::EntityT	(	const EntityT &	Entity,
		bool	Recursive = `false`
	)

The copy constructor.

It creates a new entity as a copy of another entity. The parent of the copy is always NULL, and it is up to the caller to insert the copy somewhere into an entity hierarchy.

Parameters

Entity	The entity to copy-construct this entity from.
Recursive	Whether to recursively copy all children as well.

EntityT::~EntityT ( )

virtual

The virtual destructor. Deletes this entity and all its children.

Member Function Documentation

bool EntityT::AddChild	(	IntrusivePtrT< EntityT >	Child,
		unsigned long	Pos = `0xFFFFFFFF`
	)

Adds the given entity to the children of this entity, and sets this entity as the parent of the child.

This method also makes sure that the name of the Child is unique among its siblings, modifying it as necessary. See SetName() for more details.

Parameters

Child	The entity to add to the children of this entity.
Pos	The position among the children to insert the child entity at.

Returns: true on success, false on failure (Child has a parent already, or is the root of this entity).

bool EntityT::AddComponent	(	IntrusivePtrT< ComponentBaseT >	Comp,
		unsigned long	Index = `ULONG_MAX`
	)

Adds the given component to this entity.

Parameters

Comp	The component to add to this entity.
Index	The position among the other components to insert `Comp` at.

Returns: true on success, false on failure (if Comp is part of an entity already).

bool EntityT::CallLuaMethod	(	const char *	MethodName,
		int	NumExtraArgs,
		const char *	Signature = `""`,
			...
	)

Calls the Lua method with name MethodName of this entity.

This method is analogous to UniScriptStateT::CallMethod(), see there for details.

Parameters

MethodName	The name of the Lua method to call.
NumExtraArgs	The number of extra arguments that have been pushed on the stack.
Signature	See UniScriptStateT::Call() for details.

EntityT * EntityT::Clone ( bool Recursive = false ) const

virtual

The virtual copy constructor.

Callers can use this method to create a copy of this entity without knowing its concrete type. Overrides in derived classes use a covariant return type to facilitate use when the concrete type is known.

Parameters

Recursive Whether to recursively clone all children of this entity as well.

void EntityT::DeleteComponent ( unsigned long CompNr )

Deletes the component at the given index from this entity.

void EntityT::Deserialize	(	cf::Network::InStreamT &	Stream,
		bool	IsIniting
	)

Reads the state of this entity from the given stream, and updates the entity accordingly.

This method is called after the state of the entity has been received over the network, has been loaded from disk, has been read from the clipboard, or must be "reset" for the purpose of (re-)prediction.

Parameters

Stream	The stream to read the state data from.
IsIniting	Used to indicate that the call is part of the construction / first-time initialization of the entity. The implementation will use this to not wrongly process the event counters, interpolation, etc.

IntrusivePtrT< EntityT > EntityT::Find ( const std::string & WantedName )

Finds the entity with the name WantedName in the hierachy tree of this entity.

Use GetRoot()->Find("xy") in order to search the entire world for the entity with name xy.

Note that the method cannot be const because the return type is not const (see the implementation for details).

Parameters

WantedName The name of the entity that is to be found.

Returns: The pointer to the desired entity, or NULL if no entity with this name exists.

void EntityT::FindByComponent	(	const std::string &	TypeName,
		ArrayT< IntrusivePtrT< EntityT > > &	Result
	)

Finds all entities in the hierachy tree of this entity that have at least one component of the given (type) name.

Use GetRoot()->FindByComponent("xy") in order to search the entire world for entities with component xy.

Note that the method cannot be const because the return type is not const (see the implementation for details).

Parameters

TypeName	The type name of the component that found entities must have.
Result	All found entities are appended to this array.

IntrusivePtrT< EntityT > EntityT::FindID ( unsigned int WantedID )

Finds the entity with the given ID in the hierachy tree of this entity.

Use GetRoot()->Find(xy) in order to search the entire world for the entity with ID xy.

Note that the method cannot be const because the return type is not const (see the implementation for details).

Parameters

WantedID The ID of the entity that is to be found.

Returns: The pointer to the desired entity, or NULL if no entity with this ID exists.

void EntityT::GetAll ( ArrayT< IntrusivePtrT< EntityT > > & List )

Traverses the hierarchy (sub-tree) that is rooted at this entity in depth-first order and records all encountered entities in the given list.

Parameters

List	All nodes in this sub-tree are added to this list in depth-first order.

IntrusivePtrT<ComponentBaseT> cf::GameSys::EntityT::GetApp ( )

inline

Returns the application component of this entity.

This component is much like the "Basics" and "Transform" components, but it can be set by the application (see SetApp()), and is intended for the sole use by the application, e.g. for implementing a "selection gizmo" in the Map Editor.

IntrusivePtrT<const ComponentBaseT> cf::GameSys::EntityT::GetApp ( ) const

inline

The const variant of the GetApp() method above. See GetApp() for details.

IntrusivePtrT<ComponentBasicsT> cf::GameSys::EntityT::GetBasics ( ) const

inline

Returns the "Basics" component of this entity.

The "Basics" component defines the name and the "show" flag of the entity.

const ArrayT< IntrusivePtrT<EntityT> >& cf::GameSys::EntityT::GetChildren ( ) const

inline

Returns the immediate children of this entity.

This is analogous to calling GetChildren(Chld, false) with an initially empty Chld array.

void EntityT::GetChildren	(	ArrayT< IntrusivePtrT< EntityT > > &	Chld,
		bool	Recurse = `false`
	)		const

Returns the children of this entity.

Parameters

Chld	The array to which the children of this entity are appended. Note that Chld gets not initially cleared by this function!
Recurse	Determines if also the grand-children, grand-grand-children etc. are returned.

IntrusivePtrT< ComponentBaseT > EntityT::GetComponent	(	const std::string &	TypeName,
		unsigned int	n = `0`
	)		const

Returns the (n-th) component of the given (type) name.

Covers both the "custom" as well as the fixed components (application, "Basics" and "Transform"). That is, GetComponent("Basics") == GetBasics() and GetComponent("Transform") == GetTransform().

IntrusivePtrT< ComponentBaseT > EntityT::GetComponent ( unsigned int n ) const

Returns the n-th component of this entity, covering both the "custom" as well as the fixed components (application, "Basics" and "Transform").

This method facilitates looping over all of the entity's components, especially when neither their concrete type nor their concrete order are paramount.

const ArrayT< IntrusivePtrT<ComponentBaseT> >& cf::GameSys::EntityT::GetComponents ( ) const

inline

Returns the components that this entity is composed of.

Only the "custom" components are returned, does not include the application component, "Basics" or "Transform".

BoundingBox3fT EntityT::GetCullingBB ( bool WorldSpace ) const

Returns a bounding-box that encloses the visual representation of this entity.

It is used to determine if the entity is in the view-frustum of a camera, how large a region must be updated in the 2D views of a Map Editor, if the entity is in the potentially-visibility-set (PVS) of another entity, and similar purposes.

This method does not recurse: The returned bounding-box covers this entity, but not its children.

Note that many details are up to the entity's components, whose GetCullingBB() method this method's implementation calls. For example, it is up to the Map Editor's "App" component to decide whether it includes selection gizmo handles and/or the map primitives in the returned bounding-box.

Parameters

WorldSpace If true, the bounding-box is returned in world-space coordinates. If false, the bounding-box is returned in local entity-space. Note that due to the transformation, the volume of the bounding-box in world-space may be larger than the volume of the bounding-box in entity-space.

Returns: The bounding-box that encloses the visual representation of this entity. The returned bounding-box is always valid, but possibly not inited (!IsInited()), indicating that the entity doesn't have a visual representation.

unsigned int cf::GameSys::EntityT::GetID ( ) const

inline

Returns the ID of this entity.

The ID is unique in the world, and used to unambiguously identify the entity in network messages and as entity index number into .cw world files.

IntrusivePtrT<EntityT> cf::GameSys::EntityT::GetParent ( ) const

inline

Returns the parent entity of this entity.

IntrusivePtrT< EntityT > EntityT::GetRoot ( )

Returns the top-most parent of this entity, that is, the root of the hierarchy that this entity is in.

IntrusivePtrT<ComponentTransformT> cf::GameSys::EntityT::GetTransform ( ) const

inline

Returns the "Transform" component of this entity.

The "Transform" component defines the position, size and orientation of the entity.

bool EntityT::Has ( IntrusivePtrT< EntityT > Ent ) const

Returns whether the given entity is in the hierarchy (sub-tree) of this entity.

void EntityT::OnClientFrame ( float t )

Advances the entity one frame (one "clock-tick") on the client.

It typically updates eye-candy that is not sync'ed over the network. ComponentBaseT::OnClientFrame() is called by this method for all components of this entity.

Parameters

t	The time in seconds since the last client frame.

bool EntityT::OnInputEvent ( const CaKeyboardEventT & KE )

virtual

Keyboard input event handler.

Parameters

KE	Keyboard event.

bool EntityT::OnInputEvent	(	const CaMouseEventT &	ME,
		float	PosX,
		float	PosY
	)

virtual

Mouse input event handler.

Parameters

ME	Mouse event.
PosX	Mouse position x.
PosY	Mouse position y.

void EntityT::OnServerFrame ( float t )

Advances the entity one frame (one "clock-tick") on the server.

It typically updates all game-relevant state that is sync'ed over the network to all connected game clients. ComponentBaseT::OnServerFrame() is called by this method for all components of this entity.

Parameters

t	The time in seconds since the last server frame.

bool EntityT::RemoveChild ( IntrusivePtrT< EntityT > Child )

Removes the given entity from the children of this entity.

Parameters

Child The entity to remove from the children of this entity.

Returns: true on success, false on failure (Child is not a child of this entity).

bool EntityT::RenderComponents	(	bool	FirstPersonView,
		float	LodDist
	)		const

Renders the components of this entity.

Note that this method does not recurse into the children, and it does not setup any of the MatSys's model, view or projection matrices: it's up to the caller to do that.

Parameters

FirstPersonView	If the world is rendered from the perspective of this entity.
LodDist	The distance of the viewer entity to this entity.

Returns: true if "something" was rendered, false otherwise (in this case the Map Editor may choose to render another visual representation of this component's entity).

void EntityT::Serialize	(	cf::Network::OutStreamT &	Stream,
		bool	WithChildren = `false`
	)		const

Writes the current state of this entity into the given stream.

This method is called to send the state of the entity over the network, to save it to disk, or to store it in the clipboard.

Parameters

Stream	The stream to write the state data to.
WithChildren	Should the children be recursively serialized as well?

void EntityT::SetApp ( IntrusivePtrT< ComponentBaseT > App )

Sets the application component for this entity. See GetApp() for details.

Member Data Documentation

const cf::TypeSys::MethsDocT EntityT::DocCallbacks

staticprotected

Initial value:

=
{
    { "OnInit",
      "This method is called for each entity when a new world is loaded.\n"
      "Note that these OnInit() methods are automatically written by the Cafu Map Editor\n"
      "into a world's `.cent` files, you normally don't write them yourself.\n"
      "Use the ComponentBaseT::OnInit() methods instead for custom dynamic initialization.",
      "", "()" },
    { NULL, NULL, NULL, NULL }
}

const char * EntityT::DocClass

staticprotected

Initial value:

=
    "An entity is the basic element in a game world.\n"
    "\n"
    "Entity can be hierarchically arranged in parent/child relationships, e.g. a player that rides a car.\n"
    "\n"
    "An entity is a separate unit that is self-contained and has its own identity, but has very little own features.\n"
    "Instead, an entity contains a set of components, each of which implements a specific feature for the entity."

const cf::TypeSys::MethsDocT EntityT::DocMethods

staticprotected

Initial value:

=
{
    META_GetID,
    META_AddChild,
    META_RemoveChild,
    META_GetParent,
    META_GetRoot,
    META_GetChildren,
    META_FindByID,
    META_FindByName,
    META_FindByComponent,
    META_GetBasics,
    META_GetTransform,
    META_AddComponent,
    META_RemoveComponent,
    META_GetComponents,
    META_GetComponent,
    META_toString,
    { NULL, NULL, NULL, NULL }
}

const luaL_Reg EntityT::MethodsList

staticprotected

Initial value:

=
{
    { "GetID",           GetID },
    { "AddChild",        AddChild },
    { "RemoveChild",     RemoveChild },
    { "GetParent",       GetParent },
    { "GetRoot",         GetRoot },
    { "GetChildren",     GetChildren },
    { "FindByID",        FindByID },
    { "FindByName",      FindByName },
    { "FindByComponent", FindByComponent },
    { "GetBasics",       GetBasics },
    { "GetTransform",    GetTransform },
    { "AddComponent",    AddComponent },
    { "RemoveComponent", RmvComponent },
    { "GetComponents",   GetComponents },
    { "GetComponent",    GetComponent },
    { "__tostring",      toString },
    { NULL, NULL }
}

List of methods registered with Lua.

The documentation for this class was generated from the following files:

Libs/GameSys/Entity.hpp
Libs/GameSys/Entity.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Static Protected Member Functions

Static Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation