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

#include <World.h>

Public Types
using	ReferenceResolver = plDelegate<plGameObjectHandle(const void*, plComponentHandle hThis, plStringView sProperty)>

using	ResourceReloadContext = plInternal::WorldData::ResourceReloadContext

using	ResourceReloadFunc = plInternal::WorldData::ResourceReloadFunc

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

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

plStringView	GetName () const
	Returns the name of this world.

plUInt32	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 plWorld for a detailed description of the update phases.

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

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

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

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

void	GetCoordinateSystem (const plVec3 &vGlobalPosition, plCoordinateSystem &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 plSharedPtr< plCoordinateSystemProvider > &pProvider)
	Sets the coordinate system provider that should be used in this world.

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

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

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

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

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

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

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

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

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

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

void	SetMaxInitializationTimePerFrame (plTime 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 plGameObjectHandle.

const ReferenceResolver &	GetGameObjectReferenceResolver () const

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

void	RemoveResourceReloadFunction (plTypelessResourceHandle hResource, plComponentHandle hComponent, void *pUserData)

template<typename ModuleType >
PL_ALWAYS_INLINE ModuleType *	GetOrCreateModule ()

template<typename ModuleType >
PL_ALWAYS_INLINE void	DeleteModule ()

template<typename ModuleType >
PL_ALWAYS_INLINE ModuleType *	GetModule ()

template<typename ModuleType >
PL_ALWAYS_INLINE const ModuleType *	GetModule () const

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

template<typename ManagerType >
PL_FORCE_INLINE ManagerType *	GetComponentManager ()

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

plWorldModule *	GetOrCreateModule (const plRTTI *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 plRTTI *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.

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

const plWorldModule *	GetModule (const plRTTI *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.

plComponentManagerBase *	GetOrCreateManagerForComponentType (const plRTTI *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.

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

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

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

template<typename ComponentType >
bool	TryGetComponent (const plComponentHandle &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 plComponentHandle &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.

plComponentInitBatchHandle	CreateComponentInitBatch (plStringView 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 plComponentInitBatchHandle &hBatch)
	Deletes a component init batch. It must be completely processed before it can be deleted.

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

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

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

bool	IsComponentInitBatchCompleted (const plComponentInitBatchHandle &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 plComponentInitBatchHandle &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 plGameObjectHandle &hReceiverObject, plMessage &ref_msg)
	Sends a message to all components of the receiverObject.

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

void	PostMessage (const plGameObjectHandle &hReceiverObject, const plMessage &msg, plTime delay, plObjectMsgQueueType::Enum queueType=plObjectMsgQueueType::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 plGameObjectHandle &hReceiverObject, const plMessage &msg, plTime delay, plObjectMsgQueueType::Enum queueType=plObjectMsgQueueType::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 plComponentHandle &hReceiverComponent, plMessage &ref_msg)
	Sends a message to the component.

void	PostMessage (const plComponentHandle &hReceiverComponent, const plMessage &msg, plTime delay, plObjectMsgQueueType::Enum queueType=plObjectMsgQueueType::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 plMessage &msg, plGameObject pSearchObject, plDynamicArray< plComponent > &out_components)
	Finds the closest (parent) object, starting at pSearchObject, which has an plComponent that handles the given message and returns all matching components owned by that object. If a plEventMessageHandlerComponent is found the search is stopped even if it doesn't handle the given message.

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

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

static plWorld *	GetWorld (plUInt32 uiIndex)
	Returns the world with the given index.

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

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

Helper methods to query plWorld limits
static constexpr plUInt64	GetMaxNumGameObjects ()

static constexpr plUInt64	GetMaxNumHierarchyLevels ()

static constexpr plUInt64	GetMaxNumComponentsPerType ()

static constexpr plUInt64	GetMaxNumWorldModules ()

static constexpr plUInt64	GetMaxNumComponentTypes ()

static constexpr plUInt64	GetMaxNumWorlds ()

Friends
class	plGameObject

class	plWorldModule

class	plComponentManagerBase

class	plComponent

Object Functions
enum	TraversalMethod { BreadthFirst , DepthFirst }

using	VisitorFunc = plInternal::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.

plGameObjectHandle	CreateObject (const plGameObjectDesc &desc)
	Create a new game object from the given description and returns a handle to it.

plGameObjectHandle	CreateObject (const plGameObjectDesc &desc, plGameObject *&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 plGameObjectHandle &hObject, bool bAlsoDeleteEmptyParents=true)
	Deletes the given object, its children and all components.

void	DeleteObjectDelayed (const plGameObjectHandle &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.

const plEvent< const plGameObject * > &	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 plGameObjectHandle &hObject) const
	Returns whether the given handle corresponds to a valid object.

bool	TryGetObject (const plGameObjectHandle &hObject, plGameObject *&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 plGameObjectHandle &hObject, const plGameObject *&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 plTempHashedString &sGlobalKey, plGameObject *&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 plTempHashedString &sGlobalKey, const plGameObject *&out_pObject) const
	Returns whether an object with the given global key exists and if so writes out the corresponding pointer to out_pObject.

plUInt32	GetObjectCount () const
	Returns the total number of objects in this world.

plInternal::WorldData::ObjectIterator	GetObjects ()
	Returns an iterator over all objects in this world in no specific order.

plInternal::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 plWorld::DeleteObjectDelayed	(	const plGameObjectHandle &	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 plWorld::DeleteObjectNow	(	const plGameObjectHandle &	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 plWorld::FindEventMsgHandlers	(	const plMessage &	msg,
		const plGameObject *	pSearchObject,
		plDynamicArray< const plComponent * > &	out_components ) const

Finds the closest (parent) object, starting at pSearchObject, which has an plComponent that handles the given message and returns all matching components owned by that object. If a plEventMessageHandlerComponent 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 plEventMessageHandlerComponent instances that are set to 'handle global events' that handle messages of the given type.

◆ FindEventMsgHandlers() [2/2]

void plWorld::FindEventMsgHandlers	(	const plMessage &	msg,
		plGameObject *	pSearchObject,
		plDynamicArray< plComponent * > &	out_components )

Finds the closest (parent) object, starting at pSearchObject, which has an plComponent that handles the given message and returns all matching components owned by that object. If a plEventMessageHandlerComponent 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 plEventMessageHandlerComponent instances that are set to 'handle global events' that handle messages of the given type.

◆ GetGameObjectReferenceResolver()

const plWorld::ReferenceResolver & plWorld::GetGameObjectReferenceResolver ( ) const

See also: SetGameObjectReferenceResolver()

◆ SetGameObjectReferenceResolver()

void plWorld::SetGameObjectReferenceResolver ( const ReferenceResolver & resolver )

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

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:

Code/Engine/Core/World/World.h
Code/Engine/Core/World/Implementation/World.cpp
Code/Engine/Core/World/Implementation/World_inl.h

Public Types

Public Member Functions

Static Public Member Functions

Friends

Object Functions