ezEngine  Milestone 9
ezWorld Class Reference

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

#include <World.h>

Public Member Functions

 ezWorld (ezWorldDesc &desc)
 Creates a new world with the given name.
 
void Clear ()
 Deletes all game objects in a world.
 
const char * GetName () const
 Returns the name of this world.
 
ezUInt32 GetIndex () const
 Returns the index of this world.
 
void SetWorldSimulationEnabled (bool bEnable)
 If enabled, the full simulation should be executed, otherwise only the rendering related updates should be done.
 
bool GetWorldSimulationEnabled () const
 If enabled, the full simulation should be executed, otherwise only the rendering related updates should be done.
 
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.
 
ezSpatialSystemGetSpatialSystem ()
 Returns the spatial system that is associated with this world.
 
const ezSpatialSystemGetSpatialSystem () const
 Returns the spatial system that is associated with this world.
 
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 ()
 Returns the coordinate system provider that is associated with this world.
 
const ezCoordinateSystemProviderGetCoordinateSystemProvider () const
 Returns the coordinate system provider that is associated with this world.
 
ezClockGetClock ()
 Returns the clock that is used for all updates in this game world.
 
const ezClockGetClock () const
 Returns the clock that is used for all updates in this game world.
 
ezRandomGetRandomNumberGenerator ()
 Accesses the default random number generator. If more control is desired, individual components should use their own RNG.
 
ezAllocatorBaseGetAllocator ()
 Returns the allocator used by this world.
 
ezInternal::WorldLargeBlockAllocatorGetBlockAllocator ()
 Returns the block allocator used by this world.
 
ezDoubleBufferedStackAllocatorGetStackAllocator ()
 Returns the stack 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 ModuleType >
EZ_ALWAYS_INLINE ModuleType * GetOrCreateModule ()
 
template<typename ModuleType >
EZ_ALWAYS_INLINE void DeleteModule ()
 
template<typename ModuleType >
EZ_ALWAYS_INLINE ModuleType * GetModule ()
 
template<typename ModuleType >
EZ_ALWAYS_INLINE const ModuleType * GetModule () const
 
template<typename ManagerType >
EZ_FORCE_INLINE ManagerType * GetComponentManager ()
 
template<typename ManagerType >
EZ_FORCE_INLINE const ManagerType * GetComponentManager () const
 
Module Functions
template<typename ModuleType >
ModuleType * GetOrCreateModule ()
 Creates an instance of the given module type or derived type or returns a pointer to an already existing instance.
 
template<typename ModuleType >
void DeleteModule ()
 Deletes the module of the given type or derived types.
 
template<typename ModuleType >
ModuleType * GetModule ()
 Returns the instance to the given module type or derived types.
 
template<typename ModuleType >
const ModuleType * GetModule () const
 Returns the instance to the given module type or derived types.
 
Component Functions
template<typename ManagerType >
ManagerType * GetOrCreateComponentManager ()
 Creates an instance of the given component manager type or returns a pointer to an already existing instance.
 
ezComponentManagerBaseGetOrCreateComponentManager (const ezRTTI *pComponentRtti)
 Returns the component manager that handles the given rtti component type.
 
template<typename ManagerType >
void DeleteComponentManager ()
 Deletes the component manager of the given type and all its components.
 
template<typename ManagerType >
ManagerType * GetComponentManager ()
 Returns the instance to the given component manager type.
 
template<typename ManagerType >
const ManagerType * GetComponentManager () const
 Returns the instance to the given component manager type.
 
ezComponentManagerBaseGetComponentManager (const ezRTTI *pComponentRtti)
 Returns the component manager that handles the given rtti component type.
 
const ezComponentManagerBaseGetComponentManager (const ezRTTI *pComponentRtti) 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)
 Returns if a component with the given handle exists and if so writes out the corresponding pointer to out_pComponent.
 
template<typename ComponentType >
bool TryGetComponent (const ezComponentHandle &component, const ComponentType *&out_pComponent) const
 Returns if a component with the given handle exists and if so writes out the corresponding pointer to out_pComponent.
 
Message Functions
void SendMessage (const ezGameObjectHandle &receiverObject, ezMessage &msg)
 Sends a message to all components of the receiverObject.
 
void SendMessageRecursive (const ezGameObjectHandle &receiverObject, ezMessage &msg)
 Sends a message to all components of the receiverObject and all its children.
 
void PostMessage (const ezGameObjectHandle &receiverObject, const ezMessage &msg, ezObjectMsgQueueType::Enum queueType, ezTime delay=ezTime()) const
 Queues the message for the given phase. The message is send to the receiverObject after the given delay in the corresponding phase.
 
void PostMessageRecursive (const ezGameObjectHandle &receiverObject, const ezMessage &msg, ezObjectMsgQueueType::Enum queueType, ezTime delay=ezTime()) const
 Queues the message for the given phase. The message is send to the receiverObject and all its children after the given delay in the corresponding phase.
 
void SendMessage (const ezComponentHandle &receiverComponent, ezMessage &msg)
 Sends a message to the component.
 
void PostMessage (const ezComponentHandle &receiverComponent, const ezMessage &msg, ezObjectMsgQueueType::Enum queueType, ezTime delay=ezTime()) const
 Queues the message for the given phase. The message is send to the receiverComponent after the given delay in the corresponding phase.
 

Static Public Member Functions

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

Friends

class ezGameObject
 
class ezWorldModule
 
class ezComponentManagerBase
 
class ezComponent
 

Object Functions

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.
 
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 DeleteObjectNow (const ezGameObjectHandle &object)
 Deletes the given object, its children and all components. More...
 
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)
 Returns if an object with the given handle exists and if so writes out the corresponding pointer to out_pObject.
 
bool TryGetObject (const ezGameObjectHandle &object, const ezGameObject *&out_pObject) const
 Returns if an object with the given handle exists and if so writes out the corresponding pointer to out_pObject.
 
bool TryGetObjectWithGlobalKey (const ezTempHashedString &sGlobalKey, ezGameObject *&out_pObject)
 Returns if an object with the given global key exists and if so writes out the corresponding pointer to out_pObject.
 
bool TryGetObjectWithGlobalKey (const ezTempHashedString &sGlobalKey, const ezGameObject *&out_pObject) const
 Returns if an object with the given global key exists and if so writes out the corresponding pointer to out_pObject.
 
ezUInt32 GetObjectCount () const
 Returns the total number of objects in this world.
 
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.
 

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 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

◆ DeleteObjectNow()

void ezWorld::DeleteObjectNow ( const ezGameObjectHandle object)

Deletes the given object, its children and all components.

Note
This function deletes the object immediately! It is unsafe to use this during a game update loop, as other objects may rely on this object staying valid for the rest of the frame. Use DeleteObjectDelayed() instead for safe removal at the end of the frame.

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