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

#include <World.h>

Public Types
using	ReferenceResolver = xiiDelegate<xiiGameObjectHandle(const void*, xiiComponentHandle hThis, xiiStringView sProperty)>

using	ResourceReloadContext = xiiInternal::WorldData::ResourceReloadContext

using	ResourceReloadFunc = xiiInternal::WorldData::ResourceReloadFunc

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

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

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

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

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

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

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

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

void	GetCoordinateSystem (const xiiVec3 &vGlobalPosition, xiiCoordinateSystem &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 xiiSharedPtr< xiiCoordinateSystemProvider > &pProvider)
	Sets the coordinate system provider that should be used in this world.

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

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

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

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

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

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

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

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

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

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

void	SetMaxInitializationTimePerFrame (xiiTime 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 a xiiGameObjectHandle.

const ReferenceResolver &	GetGameObjectReferenceResolver () const

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

void	RemoveResourceReloadFunction (xiiTypelessResourceHandle hResource, xiiComponentHandle hComponent, void *pUserData)

template<typename ModuleType>
XII_ALWAYS_INLINE ModuleType *	GetOrCreateModule ()

template<typename ModuleType>
XII_ALWAYS_INLINE void	DeleteModule ()

template<typename ModuleType>
XII_ALWAYS_INLINE ModuleType *	GetModule ()

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

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

template<typename ManagerType>
XII_FORCE_INLINE ManagerType *	GetComponentManager ()

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

xiiWorldModule *	GetOrCreateModule (const xiiRTTI *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 xiiRTTI *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.

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

const xiiWorldModule *	GetModule (const xiiRTTI *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.

xiiComponentManagerBase *	GetOrCreateManagerForComponentType (const xiiRTTI *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.

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

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

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

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

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

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

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

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

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

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

void	PostMessage (const xiiGameObjectHandle &hReceiverObject, const xiiMessage &msg, xiiTime delay, xiiObjectMsgQueueType::Enum queueType=xiiObjectMsgQueueType::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 xiiGameObjectHandle &hReceiverObject, const xiiMessage &msg, xiiTime delay, xiiObjectMsgQueueType::Enum queueType=xiiObjectMsgQueueType::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 xiiComponentHandle &hReceiverComponent, xiiMessage &ref_msg)
	Sends a message to the component.

void	PostMessage (const xiiComponentHandle &hReceiverComponent, const xiiMessage &msg, xiiTime delay, xiiObjectMsgQueueType::Enum queueType=xiiObjectMsgQueueType::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 xiiMessage &msg, xiiGameObject pSearchObject, xiiDynamicArray< xiiComponent > &out_components)
	Finds the closest (parent) object, starting at pSearchObject, which has a xiiComponent that handles the given message and returns all matching components owned by that object. If a xiiEventMessageHandlerComponent is found the search is stopped even if it doesn't handle the given message.

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

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

static xiiWorld *	GetWorld (xiiUInt32 uiIndex)
	Returns the world with the given index.

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

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

Helper methods to query xiiWorld limits.
static constexpr xiiUInt64	GetMaxNumGameObjects ()

static constexpr xiiUInt64	GetMaxNumHierarchyLevels ()

static constexpr xiiUInt64	GetMaxNumComponentsPerType ()

static constexpr xiiUInt64	GetMaxNumWorldModules ()

static constexpr xiiUInt64	GetMaxNumComponentTypes ()

static constexpr xiiUInt64	GetMaxNumWorlds ()

Friends
class	xiiGameObject

class	xiiWorldModule

class	xiiComponentManagerBase

class	xiiComponent

Object Functions
enum	TraversalMethod { BreadthFirst , DepthFirst }

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

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

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

void	DeleteObjectDelayed (const xiiGameObjectHandle &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 xiiEvent< const xiiGameObject * > &	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 xiiGameObjectHandle &hObject) const
	Returns whether the given handle corresponds to a valid object.

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

xiiGameObject *	SearchForObject (xiiStringView sSearchPath, xiiGameObject pReferenceObject=nullptr, const xiiRTTI pExpectedComponent=nullptr)
	Searches for an object by path. Can find objects through a global key and/or relative to an object. May also search for an object that has a certain component.

const xiiGameObject *	SearchForObject (xiiStringView sSearchPath, const xiiGameObject pReferenceObject=nullptr, const xiiRTTI pExpectedComponent=nullptr) const
	const overload of SearchForObject()

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

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

xiiInternal::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 256 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 xiiWorld::DeleteObjectDelayed	(	const xiiGameObjectHandle &	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 xiiWorld::DeleteObjectNow	(	const xiiGameObjectHandle &	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 xiiWorld::FindEventMsgHandlers	(	const xiiMessage &	msg,
		const xiiGameObject *	pSearchObject,
		xiiDynamicArray< const xiiComponent * > &	out_components ) const

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

◆ FindEventMsgHandlers() [2/2]

void xiiWorld::FindEventMsgHandlers	(	const xiiMessage &	msg,
		xiiGameObject *	pSearchObject,
		xiiDynamicArray< xiiComponent * > &	out_components )

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

◆ GetGameObjectReferenceResolver()

const xiiWorld::ReferenceResolver & xiiWorld::GetGameObjectReferenceResolver ( ) const

See also: SetGameObjectReferenceResolver()

◆ SearchForObject()

xiiGameObject * xiiWorld::SearchForObject	(	xiiStringView	sSearchPath,
		xiiGameObject *	pReferenceObject = nullptr,
		const xiiRTTI *	pExpectedComponent = nullptr )

nodiscard

Searches for an object by path. Can find objects through a global key and/or relative to an object. May also search for an object that has a certain component.

The syntax for sSearchPath is as follows:

All pieces of the path must be separated by slashes (/)
If it starts with "G:" then it will search for an object via global key. Ie "G:keyname" will search for an object with the global key "keyname". If no such object exists, the search fails. Otherwise this object becomes the reference object for the remainder. If pReferenceObject was nullptr to begin with, sSearchPath MUST start with a global key search.
If it starts (or continues) with "P:" it will search "upwards" from the reference object to find the closest parent object that has the requested name. Ie "P:parentname" will check the reference object's name for "parentname", if it doesn't match, it checks the parent object, and so on, until it either fails, because no such named parent exists, or it finds an object.
If the path starts (or continues) with "../" it will go to the parent object of the current object. This is repeated for every occurrance of "../". The search fails, if there are not enough parent objects.
If the path starts (or continues) with a relative path (e.g. "a/b") it then searches for any direct or indirect child called "a" and below that a direct or indirect object with name "b". If that is found, and pExpectedComponent is not nullptr, it is checked whether the found object has that component type attached. If so, the search terminates successfully. Otherwise the search continues for all other combinations of objects called "a" with decendants called "b" until it finds an object with that component type, or runs out of objects.

Example paths:

"G:player" -> search for the object with the global key "player"
"P:root" -> starting at the reference object searches for the parent object called "root"
"../.." -> starting at the reference object, goes two levels up
"head/camera" -> starting at the reference object searches for a child object called "head" and from there searches for a child object called "camera"
"G:door1/P:frame" -> uses a global key to find the "door1" object and from there gets the parent object called "frame"
"G:door1/.." -> uses a global key to find the "door1" object and returns its parent object
"P:root/obj2" -> starting at the reference object searches for a parent called "root" and from there searches for a child object called "obj2"

Invalid paths:

"P:name/G:key" -> "G:" must be the first part of the string.
"obj/../" -> ".." can only appear at the beginning of the relative path
"obj/P:name" -> "P:" must be at the very beginning or directly after "G:"

◆ SetGameObjectReferenceResolver()

void xiiWorld::SetGameObjectReferenceResolver ( const ReferenceResolver & resolver )

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

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/XII/XII/Source/Engine/Core/World/World.h
/home/runner/work/XII/XII/Source/Engine/Core/World/Implementation/World.cpp
/home/runner/work/XII/XII/Source/Engine/Core/World/Implementation/World_inl.h

Public Types

Public Member Functions

Static Public Member Functions

Friends

Object Functions