#include <GameState.h>

Inheritance diagram for xiiGameState:

Public Member Functions
xiiWorld *	GetMainWorld ()
	Returns the xiiWorld that is currently the active one.
xiiCamera *	GetMainCamera ()
	Gives access to the game state's main camera object.
xiiView *	GetMainView ()
	Returns the xiiView that is currently the one used for rendering the main output.
bool	IsLoadingSceneInBackground (float *out_pProgress=nullptr) const
	Whether a scene is currently being loaded.
bool	IsInLoadingScreen () const
	Whether the game state currently displays a loading screen. This usually implies that a scene is being loaded as well.
virtual void	OnActivation (xiiWorld *pWorld, xiiStringView sStartPosition, const xiiTransform &startPositionOffset) override
virtual void	OnDeactivation () override
	Cleans up the main window before the game is shut down.
virtual void	RequestQuit (xiiStringView sRequestedBy) override
virtual bool	WasQuitRequested () const override
	Whether WasQuitRequested() was called before.
virtual void	ProcessInput () override
	The xiiGameState doesn't implement any input logic, but it forwards to UpdateBackgroundSceneLoading().
void	LoadScene (xiiStringView sSceneFile, xiiStringView sPreloadCollection, xiiStringView sStartPosition, const xiiTransform &startPositionOffset)
void	SwitchToLoadingScreen (xiiStringView sTargetSceneFile)
void	ChangeMainWorld (xiiWorld *pNewMainWorld, xiiStringView sStartPosition, const xiiTransform &startPositionOffset)
void	StartBackgroundSceneLoading (xiiStringView sSceneFile, xiiStringView sPreloadCollection)
void	CancelBackgroundSceneLoading ()
Public Member Functions inherited from xiiGameStateBase
virtual void	BeforeWorldUpdate ()
	Called once each frame before the worlds are updated.
virtual void	AfterWorldUpdate ()
	Called once each frame after the worlds have been updated.
virtual bool	IsFallbackGameState () const
Public Member Functions inherited from xiiReflectedClass
virtual const xiiRTTI *	GetDynamicRTTI () const
bool	IsInstanceOf (const xiiRTTI *pType) const
	Returns whether the type of this instance is of the given type or derived from it.
template<typename T>
XII_ALWAYS_INLINE bool	IsInstanceOf () const
	Returns whether the type of this instance is of the given type or derived from it.

Static Public Member Functions
static xiiGameState *	GetActiveGameState ()
	Returns the active xiiGameState. Only one xiiGameState is allowed to exist.
Static Public Member Functions inherited from xiiNoBase
static const xiiRTTI *	GetStaticRTTI ()

Protected Member Functions
	xiiGameState ()
	This class cannot be instantiated directly.
virtual void	CreateWindows ()
virtual void	ConfigureInputActions ()
virtual xiiResult	SpawnPlayer (xiiStringView sStartPosition, const xiiTransform &startPositionOffset)
xiiView *	CreateMainView ()
	Creates a default main view.
virtual void	OnChangedMainWorld (xiiWorld pPreviousWorld, xiiWorld pNewWorld, xiiStringView sStartPosition, const xiiTransform &startPositionOffset)
virtual void	ConfigureMainCamera () override
virtual xiiUniquePtr< xiiWindow >	CreateMainWindow ()
	Override this to modify the default window creation behavior. Called by CreateWindows().
virtual xiiUniquePtr< xiiWindowOutputTargetGAL >	CreateMainOutputTarget (xiiWindow *pMainWindow)
	Override this to modify the default output target creation behavior. Called by CreateWindows().
virtual void	SetupMainView (xiiGALSwapChain *pSwapChain, xiiSizeU32 viewportSize)
	Creates a default render view. Unless overridden, OnActivation() will do this for the main window.
virtual void	ConfigureMainWindowInputDevices (xiiWindow *pWindow)
virtual void	GetStartupOptions (xiiString &out_sScene, xiiString &out_sPreloadCollection)
virtual xiiUniquePtr< xiiWorld >	CreateLoadingScreenWorld (xiiStringView sTargetSceneFile)
void	UpdateBackgroundSceneLoading ()
virtual void	OnBackgroundSceneLoadingFinished (xiiUniquePtr< xiiWorld > &&pWorld)
virtual void	OnBackgroundSceneLoadingFailed (xiiStringView sReason)
	Called by UpdateBackgroundSceneLoading() when a scene failed to load.
virtual void	OnBackgroundSceneLoadingCanceled ()
	Called by CancelBackgroundSceneLoading() when scene loading gets canceled.
virtual void	OnWindowEvent (const xiiWindowEvent &e)
	Forwards window events from the platform window. Override this to react to window events, such as resizing.

Protected Attributes
xiiWorld *	m_pMainWorld = nullptr
xiiCamera	m_MainCamera
xiiViewHandle	m_hMainView
bool	m_bStateWantsToQuit = false
bool	m_bTransitionWhenReady = false
xiiUniquePtr< xiiSceneLoadUtility >	m_pBackgroundSceneLoad
xiiUniquePtr< xiiWorld >	m_pLoadingScreenWorld
xiiUniquePtr< xiiWorld >	m_pLoadedWorld
xiiString	m_sTargetSceneSpawnPoint
xiiTransform	m_TargetSceneSpawnOffset = xiiTransform::MakeIdentity()

Static Protected Attributes
static xiiGameState *	s_pActiveGameState = nullptr

Detailed Description

xiiGameState implements the xiiGameStateBase interface and adds several convenience features.

For an explanation what game states are, see the online documentation: https://xiiengine.net/pages/docs/runtime/application/game-state.html

The xiiGameState adds some default functionality:

Creation of a main window and render pipeline.
A main view handle.
A main camera object.
A main world that is currently active.
Background loading of scenes.
A separate world used as a loading screen.
automatic player prefab spawning if a xiiPlayerStartPointComponent is part of the scene.
automatically applies the state of the "Main View" xiiCameraComponent in the scene.
Many additional hooks to customize only specific parts, such as the window creation.

Typically you would derive from xiiGameState and then override functions like ProcessInput() and ConfigureMainCamera(). Take a look at xiiFallbackGameState for inspiration.

Member Function Documentation

◆ CancelBackgroundSceneLoading()

void xiiGameState::CancelBackgroundSceneLoading ( )

If a scene is currently being loaded in the background, cancel the loading.

Calls OnBackgroundSceneLoadingCanceled() if a scene was loading.

◆ ChangeMainWorld()

void xiiGameState::ChangeMainWorld	(	xiiWorld *	pNewMainWorld,
		xiiStringView	sStartPosition,
		const xiiTransform &	startPositionOffset )

Sets m_pMainWorld and updates m_pMainView to use that new world for rendering

Calls OnChangedMainWorld() afterwards, so that you can follow up on a scene change as needed. Calls ConfigureMainCamera() as well.

◆ ConfigureInputActions()

void xiiGameState::ConfigureInputActions ( )

protectedvirtual

Adds custom input actions, if necessary. Unless overridden OnActivation() will call this.

Reimplemented in xiiFallbackGameState.

◆ ConfigureMainCamera()

void xiiGameState::ConfigureMainCamera ( )

overrideprotectedvirtual

Searches for a "Main View" xiiCameraComponent in the world and uses that for the camera position, if available.

Override this for custom camera logic.

Reimplemented from xiiGameStateBase.

Reimplemented in xiiFallbackGameState.

◆ ConfigureMainWindowInputDevices()

void xiiGameState::ConfigureMainWindowInputDevices ( xiiWindow * pWindow )

protectedvirtual

Configures available input devices, e.g. sets mouse speed, cursor clipping, etc. Called by CreateWindows() with the result of CreateMainWindow().

◆ CreateLoadingScreenWorld()

xiiUniquePtr< xiiWorld > xiiGameState::CreateLoadingScreenWorld ( xiiStringView sTargetSceneFile )

protectedvirtual

Called by SwitchToLoadingScreen() to set up a new loading screen world.

A loading screen uses a separate xiiWorld. It can be fully set up in code or loaded from disk, but it should be very light-weight, so that it is quick to set up.

◆ CreateWindows()

void xiiGameState::CreateWindows ( )

protectedvirtual

Creates an actor with a default window (xiiGameStateWindow) adds it to the application

The base implementation calls CreateMainWindow(), CreateMainOutputTarget() and SetupMainView() to configure the main window.

◆ GetStartupOptions()

void xiiGameState::GetStartupOptions	(	xiiString &	out_sScene,
		xiiString &	out_sPreloadCollection )

protectedvirtual

Returns the path to the scene file and the corresponding preload collection to load at startup.

By default this is taken from the command line '-scene' option. Override this function to define a custom startup scene (e.g. for the main menu) or load a saved state.

◆ LoadScene()

void xiiGameState::LoadScene	(	xiiStringView	sSceneFile,
		xiiStringView	sPreloadCollection,
		xiiStringView	sStartPosition,
		const xiiTransform &	startPositionOffset )

Immediately switches to a loading screen and starts loading a level.

When the level is finished loading, OnBackgroundSceneLoadingFinished() is called, which switches to it immediately, unless overridden. If the scene was already fully preloaded, the switch happens immediately, without showing a loading screen.

◆ OnActivation()

void xiiGameState::OnActivation	(	xiiWorld *	pWorld,
		xiiStringView	sStartPosition,
		const xiiTransform &	startPositionOffset )

overridevirtual

Called upon game startup.

Calls CreateWindows() to create the game's main window and setup input devices. Calls ConfigureInputActions() to setup input actions. Finally switches to pWorld (if available) or starts loading the scene that GetStartupOptions() returns.

Override any of the above functions to customize them.

Implements xiiGameStateBase.

Reimplemented in xiiFallbackGameState.

◆ OnBackgroundSceneLoadingFailed()

void xiiGameState::OnBackgroundSceneLoadingFailed ( xiiStringView sReason )

protectedvirtual

Called by UpdateBackgroundSceneLoading() when a scene failed to load.

Reimplemented in xiiFallbackGameState.

◆ OnBackgroundSceneLoadingFinished()

void xiiGameState::OnBackgroundSceneLoadingFinished ( xiiUniquePtr< xiiWorld > && pWorld )

protectedvirtual

Called by UpdateBackgroundSceneLoading() when a scene is finished loading.

May switch to the scene immediately or wait, for example for a user to confirm.

Reimplemented in xiiFallbackGameState.

◆ OnChangedMainWorld()

void xiiGameState::OnChangedMainWorld	(	xiiWorld *	pPreviousWorld,
		xiiWorld *	pNewWorld,
		xiiStringView	sStartPosition,
		const xiiTransform &	startPositionOffset )

protectedvirtual

Executed when ChangeMainWorld() is used to switch to a new world.

Override this to be informed about scene changes. This happens right at startup (both for given worlds and custom created ones) and when the game needs to switch to a new level.

◆ OnDeactivation()

void xiiGameState::OnDeactivation ( )

overridevirtual

Cleans up the main window before the game is shut down.

Implements xiiGameStateBase.

◆ ProcessInput()

void xiiGameState::ProcessInput ( )

overridevirtual

The xiiGameState doesn't implement any input logic, but it forwards to UpdateBackgroundSceneLoading().

Reimplemented from xiiGameStateBase.

Reimplemented in xiiFallbackGameState.

◆ RequestQuit()

void xiiGameState::RequestQuit ( xiiStringView sRequestedBy )

overridevirtual

Simply stores that the game should stop.

Override this to add more elaborate logic, if necessary.

Implements xiiGameStateBase.

◆ SpawnPlayer()

xiiResult xiiGameState::SpawnPlayer	(	xiiStringView	sStartPosition,
		const xiiTransform &	startPositionOffset )

protectedvirtual

Overrideable function that may create a player object.

By default called by OnChangedMainWorld() when switching to a non-loading screen world. The default implementation will search the world for xiiPlayerStartComponent's and instantiate the given player prefab at one of those locations. If pStartPosition is not nullptr, it will be used as the spawn position for the player prefab, otherwise the location of the xiiPlayerStartComponent will be used.

sStartPosition allows to spawn the player at another named location, but there is no default implementation for such logic.

Returns XII_SUCCESS if a prefab was spawned, XII_FAILURE if nothing was done.

Reimplemented in xiiFallbackGameState.

◆ StartBackgroundSceneLoading()

void xiiGameState::StartBackgroundSceneLoading	(	xiiStringView	sSceneFile,
		xiiStringView	sPreloadCollection )

Starts loading a scene in the background.

If available, a collection can be provided. Resources referenced in the collection will be fully preloaded first and then the scene is loaded. This is the only way to get a proper estimation of loading progress and is necessary to get a smooth start, otherwise the engine will have to load resources on-demand, many of which will be needed during the first frame.

Once finished, one of these hooks is executed: OnBackgroundSceneLoadingFinished() OnBackgroundSceneLoadingFailed() OnBackgroundSceneLoadingCanceled()

◆ SwitchToLoadingScreen()

void xiiGameState::SwitchToLoadingScreen ( xiiStringView sTargetSceneFile )

Convenience function to switch to a loading screen.

Nothing actually gets loaded. Without further logic, the app will stay in the loading screen indefinitely. sTargetSceneFile is only passed in, so that the loading screen can be customized accordingly, for example it may show a screenshot of the target scene.

◆ UpdateBackgroundSceneLoading()

void xiiGameState::UpdateBackgroundSceneLoading ( )

protected

If a scene is being loaded in the background, this advanced the loading.

Upon success or failure, executes either of these: OnBackgroundSceneLoadingFinished() OnBackgroundSceneLoadingFailed()

◆ WasQuitRequested()

bool xiiGameState::WasQuitRequested ( ) const

overridevirtual

Whether WasQuitRequested() was called before.

Implements xiiGameStateBase.

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

/home/runner/work/XII/XII/Source/Engine/GameEngine/GameState/GameState.h
/home/runner/work/XII/XII/Source/Engine/GameEngine/GameState/Implementation/GameState.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ CancelBackgroundSceneLoading()

◆ ChangeMainWorld()

◆ ConfigureInputActions()

◆ ConfigureMainCamera()

◆ ConfigureMainWindowInputDevices()

◆ CreateLoadingScreenWorld()

◆ CreateWindows()

◆ GetStartupOptions()

◆ LoadScene()

◆ OnActivation()

◆ OnBackgroundSceneLoadingFailed()

◆ OnBackgroundSceneLoadingFinished()

◆ OnChangedMainWorld()

◆ OnDeactivation()

◆ ProcessInput()

◆ RequestQuit()

◆ SpawnPlayer()

◆ StartBackgroundSceneLoading()

◆ SwitchToLoadingScreen()

◆ UpdateBackgroundSceneLoading()

◆ WasQuitRequested()