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

#include <World.h>

Public Types
using	ReferenceResolver = ezDelegate< ezGameObjectHandle(const void *, ezComponentHandle hThis, ezStringView sProperty)>

using	ResourceReloadContext = ezInternal::WorldData::ResourceReloadContext

using	ResourceReloadFunc = ezInternal::WorldData::ResourceReloadFunc

Public Member Functions
	ezWorld (ezWorldDesc &ref_desc)
	Creates a new world with the given name.

void	Clear ()
	Deletes all game objects in a world.

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

const ezSharedPtr< ezTask > &	GetUpdateTask ()
	Returns a task implementation that calls Update on this world.

ezUInt32	GetUpdateCounter () const
	Returns the number of update calls. Can be used to determine whether an operation has already been done during a frame.

ezSpatialSystem *	GetSpatialSystem ()
	Returns the spatial system that is associated with this world.

const ezSpatialSystem *	GetSpatialSystem () 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 (const ezSharedPtr< ezCoordinateSystemProvider > &pProvider)
	Sets the coordinate system provider that should be used in this world.

ezCoordinateSystemProvider &	GetCoordinateSystemProvider ()
	Returns the coordinate system provider that is associated with this world.

const ezCoordinateSystemProvider &	GetCoordinateSystemProvider () const
	Returns the coordinate system provider that is associated with this world.

ezClock &	GetClock ()
	Returns the clock that is used for all updates in this game world.

const ezClock &	GetClock () const
	Returns the clock that is used for all updates in this game world.

ezRandom &	GetRandomNumberGenerator ()
	Accesses the default random number generator. If more control is desired, individual components should use their own RNG.

ezAllocator *	GetAllocator ()
	Returns the allocator used by this world.

ezInternal::WorldLargeBlockAllocator *	GetBlockAllocator ()
	Returns the block allocator used by this world.

ezDoubleBufferedLinearAllocator *	GetStackAllocator ()
	Returns the stack allocator used by this world.

ezInternal::WorldData::ReadMarker &	GetReadMarker () const
	Mark the world for reading by using EZ_LOCK(world.GetReadMarker()). Multiple threads can read simultaneously if none is writing.

ezInternal::WorldData::WriteMarker &	GetWriteMarker ()
	Mark the world for writing by using EZ_LOCK(world.GetWriteMarker()). Only one thread can write at a time.

void	SetMaxInitializationTimePerFrame (ezTime maxInitTime)
	Allows re-setting the maximum time that is spent on component initialization per frame, which is first configured on construction.

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.

void	SetGameObjectReferenceResolver (const ReferenceResolver &resolver)
	If set, this delegate can be used to map some data (GUID or string) to an ezGameObjectHandle. More...

const ReferenceResolver &	GetGameObjectReferenceResolver () const

void	AddResourceReloadFunction (ezTypelessResourceHandle hResource, ezComponentHandle hComponent, void *pUserData, ResourceReloadFunc function)
	Add a function that is called when the given resource has been reloaded.

void	RemoveResourceReloadFunction (ezTypelessResourceHandle hResource, ezComponentHandle hComponent, void *pUserData)

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 >
const EZ_ALWAYS_INLINE ModuleType *	GetModule () const

template<typename ModuleType >
const EZ_ALWAYS_INLINE ModuleType *	GetModuleReadOnly () const

template<typename ManagerType >
EZ_FORCE_INLINE ManagerType *	GetComponentManager ()

template<typename ManagerType >
const EZ_FORCE_INLINE 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.

ezWorldModule *	GetOrCreateModule (const ezRTTI *pRtti)
	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.

void	DeleteModule (const ezRTTI *pRtti)
	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.

template<typename ModuleType >
const ModuleType *	GetModuleReadOnly () const
	Returns the instance to the given module type or derived types.

ezWorldModule *	GetModule (const ezRTTI *pRtti)
	Returns the instance to the given module type or derived types.

const ezWorldModule *	GetModule (const ezRTTI *pRtti) 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.

ezComponentManagerBase *	GetOrCreateManagerForComponentType (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.

ezComponentManagerBase *	GetManagerForComponentType (const ezRTTI *pComponentRtti)
	Returns the component manager that handles the given rtti component type.

const ezComponentManagerBase *	GetManagerForComponentType (const ezRTTI *pComponentRtti) const
	Returns the component manager that handles the given rtti component type.

bool	IsValidComponent (const ezComponentHandle &hComponent) const
	Checks whether the given handle references a valid component.

template<typename ComponentType >
bool	TryGetComponent (const ezComponentHandle &hComponent, ComponentType *&out_pComponent)
	Returns whether 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 &hComponent, const ComponentType *&out_pComponent) const
	Returns whether a component with the given handle exists and if so writes out the corresponding pointer to out_pComponent.

template<typename T , typename U , std::enable_if_t<!std::disjunction_v< std::is_base_of< U, T >, std::is_base_of< T, U >>, bool > = true>
bool	TryGetComponent (const ezTypedComponentHandle< T > &hComponent, U *&out_pComponent)=delete
	Explicitly delete TryGetComponent overload when handle type is not related to a pointer type given by out_pComponent.

template<typename T , typename U , std::enable_if_t<!std::disjunction_v< std::is_base_of< U, T >, std::is_base_of< T, U >>, bool > = true>
bool	TryGetComponent (const ezTypedComponentHandle< T > &hComponent, const U *&out_pComponent) const =delete
	Explicitly delete TryGetComponent overload when handle type is not related to a pointer type given by out_pComponent.

ezComponentInitBatchHandle	CreateComponentInitBatch (ezStringView sBatchName, bool bMustFinishWithinOneFrame=true)
	Creates a new component init batch. It is ensured that the Initialize function is called for all components in a batch before the OnSimulationStarted is called. If bMustFinishWithinOneFrame is set to false the processing of an init batch can be distributed over multiple frames if m_MaxComponentInitializationTimePerFrame in the world desc is set to a reasonable value.

void	DeleteComponentInitBatch (const ezComponentInitBatchHandle &hBatch)
	Deletes a component init batch. It must be completely processed before it can be deleted.

void	BeginAddingComponentsToInitBatch (const ezComponentInitBatchHandle &hBatch)
	All components that are created between an BeginAddingComponentsToInitBatch/EndAddingComponentsToInitBatch scope are added to the given init batch.

void	EndAddingComponentsToInitBatch (const ezComponentInitBatchHandle &hBatch)
	End adding components to the given batch. Components created after this call are added to the default init batch.

void	SubmitComponentInitBatch (const ezComponentInitBatchHandle &hBatch)
	After all components have been added to the init batch call submit to start processing the batch.

bool	IsComponentInitBatchCompleted (const ezComponentInitBatchHandle &hBatch, double *pCompletionFactor=nullptr)
	Returns whether the init batch has been completely processed and all corresponding components are initialized and their OnSimulationStarted function was called.

void	CancelComponentInitBatch (const ezComponentInitBatchHandle &hBatch)
	Cancel the init batch if it is still active. This might leave outstanding components in an inconsistent state, so this function has be used with care.

Message Functions
void	SendMessage (const ezGameObjectHandle &hReceiverObject, ezMessage &ref_msg)
	Sends a message to all components of the receiverObject.

void	SendMessageRecursive (const ezGameObjectHandle &hReceiverObject, ezMessage &ref_msg)
	Sends a message to all components of the receiverObject and all its children.

void	PostMessage (const ezGameObjectHandle &hReceiverObject, const ezMessage &msg, ezTime delay, ezObjectMsgQueueType::Enum queueType=ezObjectMsgQueueType::NextFrame) 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 &hReceiverObject, const ezMessage &msg, ezTime delay, ezObjectMsgQueueType::Enum queueType=ezObjectMsgQueueType::NextFrame) 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 &hReceiverComponent, ezMessage &ref_msg)
	Sends a message to the component.

void	PostMessage (const ezComponentHandle &hReceiverComponent, const ezMessage &msg, ezTime delay, ezObjectMsgQueueType::Enum queueType=ezObjectMsgQueueType::NextFrame) const
	Queues the message for the given phase. The message is send to the receiverComponent after the given delay in the corresponding phase.

void	FindEventMsgHandlers (const ezMessage &msg, ezGameObject pSearchObject, ezDynamicArray< ezComponent > &out_components)
	Finds the closest (parent) object, starting at pSearchObject, which has an ezComponent that handles the given message and returns all matching components owned by that object. If a ezEventMessageHandlerComponent is found the search is stopped even if it doesn't handle the given message. More...

void	FindEventMsgHandlers (const ezMessage &msg, const ezGameObject pSearchObject, ezDynamicArray< const ezComponent > &out_components) const
	Finds the closest (parent) object, starting at pSearchObject, which has an ezComponent that handles the given message and returns all matching components owned by that object. If a ezEventMessageHandlerComponent is found the search is stopped even if it doesn't handle the given message. More...

Static Public Member Functions
static ezUInt32	GetWorldCount ()
	Returns the number of active worlds.

static ezWorld *	GetWorld (ezUInt32 uiIndex)
	Returns the world with the given index.

static ezWorld *	GetWorld (const ezGameObjectHandle &hObject)
	Returns the world for the given game object handle.

static ezWorld *	GetWorld (const ezComponentHandle &hComponent)
	Returns the world for the given component handle.

Helper methods to query ezWorld limits
static constexpr ezUInt64	GetMaxNumGameObjects ()

static constexpr ezUInt64	GetMaxNumHierarchyLevels ()

static constexpr ezUInt64	GetMaxNumComponentsPerType ()

static constexpr ezUInt64	GetMaxNumWorldModules ()

static constexpr ezUInt64	GetMaxNumComponentTypes ()

static constexpr ezUInt64	GetMaxNumWorlds ()

Friends
class	ezGameObject

class	ezWorldModule

class	ezComponentManagerBase

class	ezComponent

Object Functions
enum	TraversalMethod { BreadthFirst, DepthFirst }

using	VisitorFunc = ezInternal::WorldData::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 &hObject, bool bAlsoDeleteEmptyParents=true)
	Deletes the given object, its children and all components. More...

void	DeleteObjectDelayed (const ezGameObjectHandle &hObject, bool bAlsoDeleteEmptyParents=true)
	Deletes the given object at the beginning of the next world update. The object and its components and children stay completely valid until then. More...

const ezEvent< const ezGameObject * > &	GetObjectDeletionEvent () const
	Returns the event that is triggered before an object is deleted. This can be used for external systems to cleanup data which is associated with the deleted object.

bool	IsValidObject (const ezGameObjectHandle &hObject) const
	Returns whether the given handle corresponds to a valid object.

bool	TryGetObject (const ezGameObjectHandle &hObject, ezGameObject *&out_pObject)
	Returns whether an object with the given handle exists and if so writes out the corresponding pointer to out_pObject.

bool	TryGetObject (const ezGameObjectHandle &hObject, const ezGameObject *&out_pObject) const
	Returns whether 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 whether 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 whether 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::ObjectIterator	GetObjects ()
	Returns an iterator over all objects in this world in no specific order.

ezInternal::WorldData::ConstObjectIterator	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 global transformation of dynamic objects is updated.
Post-transform phase: Another synchronous phase like the pre-async phase after the transformation has been updated.

Member Function Documentation

◆ DeleteObjectDelayed()

void ezWorld::DeleteObjectDelayed	(	const ezGameObjectHandle &	hObject,
		bool	bAlsoDeleteEmptyParents = `true`
	)

Deletes the given object at the beginning of the next world update. The object and its components and children stay completely valid until then.

If bAlsoDeleteEmptyParents is set, any ancestor object that has no other children and no components, will also get deleted.

◆ DeleteObjectNow()

void ezWorld::DeleteObjectNow	(	const ezGameObjectHandle &	hObject,
		bool	bAlsoDeleteEmptyParents = `true`
	)

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.

If bAlsoDeleteEmptyParents is set, any ancestor object that has no other children and no components, will also get deleted.

◆ FindEventMsgHandlers() [1/2]

void ezWorld::FindEventMsgHandlers	(	const ezMessage &	msg,
		const ezGameObject *	pSearchObject,
		ezDynamicArray< const ezComponent * > &	out_components
	)		const

Finds the closest (parent) object, starting at pSearchObject, which has an ezComponent that handles the given message and returns all matching components owned by that object. If a ezEventMessageHandlerComponent is found the search is stopped even if it doesn't handle the given message.

If no such parent object exists, it searches for all ezEventMessageHandlerComponent instances that are set to 'handle global events' that handle messages of the given type.

◆ FindEventMsgHandlers() [2/2]

void ezWorld::FindEventMsgHandlers	(	const ezMessage &	msg,
		ezGameObject *	pSearchObject,
		ezDynamicArray< ezComponent * > &	out_components
	)

Finds the closest (parent) object, starting at pSearchObject, which has an ezComponent that handles the given message and returns all matching components owned by that object. If a ezEventMessageHandlerComponent is found the search is stopped even if it doesn't handle the given message.

If no such parent object exists, it searches for all ezEventMessageHandlerComponent instances that are set to 'handle global events' that handle messages of the given type.

◆ GetGameObjectReferenceResolver()

const ezWorld::ReferenceResolver & ezWorld::GetGameObjectReferenceResolver ( ) const

See also: SetGameObjectReferenceResolver()

◆ SetGameObjectReferenceResolver()

void ezWorld::SetGameObjectReferenceResolver ( const ReferenceResolver & resolver )

If set, this delegate can be used to map some data (GUID or string) to an ezGameObjectHandle.

Currently only used in editor settings, to create a runtime handle from a unique editor reference.

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

/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/World/World.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/World/Implementation/World.cpp
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/World/Implementation/World_inl.h

Public Types

Public Member Functions

Static Public Member Functions

Friends

Object Functions