ezEngine  Milestone 7
ezWorld Class Reference

A world encapsulates a scene graph of game objects and various component managers and their components. More...

#include <World.h>

Public Types

enum  TraversalMethod { BreadthFirst, DepthFirst }
 
typedef
ezInternal::WorldData::VisitorFunc 
VisitorFunc
 Defines a visitor function that is called for every game-object when using the traverse method. The function takes a pointer to the game object as argument and returns a bool which indicates whether to continue (true) or abort (false) traversal.
 

Public Member Functions

 ezWorld (const char *szWorldName)
 Creates a new world with the given name.
 
const char * GetName () const
 Returns the name of this world.
 
ezGameObjectHandle CreateObject (const ezGameObjectDesc &desc)
 Create a new game object from the given description and returns a handle to it.
 
ezGameObjectHandle CreateObject (const ezGameObjectDesc &desc, ezGameObject *&out_pObject)
 Create a new game object from the given description, writes a pointer to it to out_pObject and returns a handle to it.
 
void DeleteObject (const ezGameObjectHandle &object)
 Deletes the given object. Note that the object and all its components and children will be invalidated first and the actual deletion is postponed.
 
void DeleteObjectDelayed (const ezGameObjectHandle &object)
 Deletes the given object at the beginning of the next world update. The object and its components and children stay completely valid until then.
 
bool IsValidObject (const ezGameObjectHandle &object) const
 Returns whether the given handle corresponds to a valid object.
 
bool TryGetObject (const ezGameObjectHandle &object, ezGameObject *&out_pObject) const
 Returns if an object with the given handle exists and if so writes out the corresponding pointer to out_pObject.
 
ezUInt32 GetObjectCount () const
 Returns if an object with the given name exists and if so writes out the corresponding pointer to the first object with that name to out_pObject. More...
 
ezInternal::WorldData::ObjectStorage::Iterator GetObjects ()
 Returns an iterator over all objects in this world in no specific order.
 
ezInternal::WorldData::ObjectStorage::ConstIterator GetObjects () const
 Returns an iterator over all objects in this world in no specific order.
 
void Traverse (VisitorFunc visitorFunc, TraversalMethod method=DepthFirst)
 Traverses the game object tree starting at the top level objects and then recursively all children. The given callback function is called for every object.
 
template<typename ManagerType >
ManagerType * CreateComponentManager ()
 Creates an instance of the given component manager type or returns a pointer to an already existing instance.
 
template<typename ManagerType >
void DeleteComponentManager ()
 Deletes the component manager of the given type and all its components.
 
template<typename ManagerType >
ManagerType * GetComponentManager () const
 Returns the instance to the given component manager type.
 
ezComponentManagerBaseGetComponentManager (const ezRTTI *pRtti) const
 Returns the component manager that handles the given rtti component type.
 
bool IsValidComponent (const ezComponentHandle &component) const
 Checks whether the given handle references a valid component.
 
template<typename ComponentType >
bool TryGetComponent (const ezComponentHandle &component, ComponentType *&out_pComponent) const
 Returns if a component with the given handle exists and if so writes out the corresponding pointer to out_pComponent.
 
void SendMessage (const ezGameObjectHandle &receiverObject, ezMessage &msg, ezObjectMsgRouting::Enum routing=ezObjectMsgRouting::Default)
 Sends a message to all components of the receiverObject. Depending on the routing options the message is also send to parents or children.
 
void PostMessage (const ezGameObjectHandle &receiverObject, ezMessage &msg, ezObjectMsgQueueType::Enum queueType, ezObjectMsgRouting::Enum routing=ezObjectMsgRouting::Default)
 Queues the message for the given phase and send it later in that phase to the receiverObject.
 
void PostMessage (const ezGameObjectHandle &receiverObject, ezMessage &msg, ezObjectMsgQueueType::Enum queueType, ezTime delay, ezObjectMsgRouting::Enum routing=ezObjectMsgRouting::Default)
 Queues the message for the given phase. The message is send to the receiverObject after the given delay in the corresponding phase.
 
void Update ()
 Updates the world by calling the various update methods on the component managers and also updates the transformation data of the game objects. See ezWorld for a detailed description of the update phases.
 
ezTaskGetUpdateTask ()
 Returns a task implementation that calls Update on this world.
 
const ezInternal::SpatialDataGetSpatialData () const
 
void GetCoordinateSystem (const ezVec3 &vGlobalPosition, ezCoordinateSystem &out_CoordinateSystem) const
 Returns the coordinate system for the given position. By default this always returns a coordinate system with forward = +X, right = +Y and up = +Z. This can be customized by setting a different coordinate system provider.
 
void SetCoordinateSystemProvider (ezUniquePtr< ezCoordinateSystemProvider > &&pProvider)
 Sets the coordinate system provider that should be used in this world.
 
ezCoordinateSystemProviderGetCoordinateSystemProvider () const
 Returns the coordinate system provider that is associated with this world.
 
ezAllocatorBaseGetAllocator ()
 Returns the allocator used by this world.
 
ezInternal::WorldLargeBlockAllocatorGetBlockAllocator ()
 Returns the block allocator used by this world.
 
ezInternal::WorldData::ReadMarkerGetReadMarker () const
 Mark the world for reading by using EZ_LOCK(world.GetReadMarker()). Multiple threads can read simultaneously if none is writing.
 
ezInternal::WorldData::WriteMarkerGetWriteMarker ()
 Mark the world for writing by using EZ_LOCK(world.GetWriteMarker()). Only one thread can write at a time.
 
void SetUserData (void *pUserData)
 Associates the given user data with the world. The user is responsible for the life time of user data.
 
void * GetUserData () const
 Returns the associated user data.
 
template<typename ManagerType >
EZ_FORCE_INLINE ManagerType * GetComponentManager () const
 

Static Public Member Functions

static ezUInt32 GetWorldCount ()
 Returns the number of active worlds.
 
static ezWorldGetWorld (ezUInt32 uiIndex)
 Returns the world with the given index.
 

Private Types

typedef
ezInternal::WorldData::ObjectStorage::Entry 
ObjectStorageEntry
 
typedef
ezInternal::WorldData::QueuedMsgMetaData 
QueuedMsgMetaData
 

Private Member Functions

void CheckForReadAccess () const
 
void CheckForWriteAccess () const
 
ezGameObjectGetObjectUnchecked (ezUInt32 uiIndex) const
 
void SetParent (ezGameObject *pObject, ezGameObject *pNewParent)
 
void LinkToParent (ezGameObject *pObject)
 
void UnlinkFromParent (ezGameObject *pObject)
 
void ProcessQueuedMessages (ezObjectMsgQueueType::Enum queueType)
 
ezResult RegisterUpdateFunction (const ezComponentManagerBase::UpdateFunctionDesc &desc)
 
ezResult RegisterUpdateFunctionWithDependency (const ezComponentManagerBase::UpdateFunctionDesc &desc, bool bInsertAsUnresolved)
 
ezResult DeregisterUpdateFunction (const ezComponentManagerBase::UpdateFunctionDesc &desc)
 
void DeregisterUpdateFunctions (ezComponentManagerBase *pManager)
 
void UpdateFromThread ()
 
void UpdateSynchronous (const ezArrayPtr< ezInternal::WorldData::RegisteredUpdateFunction > &updateFunctions)
 
void UpdateAsynchronous ()
 
void DeleteDeadObjects ()
 
void DeleteDeadComponents ()
 
void PatchHierarchyData (ezGameObject *pObject)
 

Private Attributes

ezProfilingId m_UpdateProfilingID
 
ezDelegateTask< void > m_UpdateTask
 
ezInternal::WorldData m_Data
 
ezInternal::SpatialData m_SpatialData
 
ezUInt32 m_uiIndex
 

Static Private Attributes

static ezStaticArray< ezWorld *, 64 > s_Worlds
 

Friends

class ezGameObject
 
class ezComponentManagerBase
 

Detailed Description

A world encapsulates a scene graph of game objects and various component managers and their components.

There can be multiple worlds active at a time, but only 64 at most. The world manages all object storage and might move objects around in memory. Thus it is not allowed to store pointers to objects. They should be referenced by handles.
The world has a multi-phase update mechanism which is divided in the following phases:

  • Pre-async phase: The corresponding component manager update functions are called synchronously in the order of their dependencies.
  • Async phase: The update functions are called in batches asynchronously on multiple threads. There is absolutely no guarantee in which order the functions are called. Thus it is not allowed to access any data other than the components own data during that phase.
  • Post-async phase: Another synchronous phase like the pre-async phase.
  • Actual deletion of dead objects and components as well as re-parenting of objects are done now.
  • Transform update: The world transformation of all dynamic objects is updated.
  • Post-transform phase: Another synchronous phase like the pre-async phase after the transformation has been updated.

Member Function Documentation

EZ_FORCE_INLINE ezUInt32 ezWorld::GetObjectCount ( ) const

Returns if an object with the given name exists and if so writes out the corresponding pointer to the first object with that name to out_pObject.

Returns the total number of objects in this world.


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