#include <game/bases/d_scene.hpp>

Inheritance diagram for dScene_c:

Description

The minimum required implementation for a scene base.

Overview

Scene bases act as overall managers for specific parts of the game. As such, only one scene can be active at any given time. All bases are created as children of the currently active scene, which allows a scene switch to act as a garbage collection mechanism by deleting every other active base.

Scene execution (and therefore every other base's) cannot begin until the scene has finished initializing.

The game's initial scene is dScBoot_c (which performs various initialization tasks), while dScRestartCrsin_c is used for soft resets to return to the title screen.

Switching Scenes

To switch from the current scene to another, use the setNextScene function, providing the new scene's profile name and parameters. The creation of the next scene is handled automatically.

Note

Scene switches during resets are typically disallowed. However, this restriction can be bypassed by setting the forceChange parameter to true in the setNextScene call.
A scene switch cannot occur until the existing scene has completed its initialization, regardless of the aforementioned parameter.
Consecutive calls to set the next scene will have no effect.

Scene Initialization

An initialization phase can be provided to set up the scene step by step. Typical actions include:

Loading additional resources (such as archives, layouts or effects) not linked to a specific base (e.g. the worldmap model in the worldmap scene). Checks must be added to ensure these resources have finished loading before initialization ends.
Loading additional sound objects (see below).
Creating specific bases necessary for the scene's functionality (e.g. the game interface for the scene).
Note
The LASTACTOR base is created automatically.
Setting the scene's paint function, which must always be the final step in initialization.
In earlier development stages, any base used by the scene was dynamically linked in the first initialization step.

Failure to complete initialization (e.g. due to missing resources) will cause the game to softlock.

Hint: Existing scene initialization phases are a good reference point for implementing custom scenes.

Audio Initialization

The following sound objects are automatically created and deleted; other sound objects must be managed manually:

SndObjctCmnEmy_c
SndObjctCmnMap_c
NonPosSndObjctAmb_c

Todo
Expand this section when dAudio and the related classes are decompiled.

Scene Fading

The fader to be used for a scene transition can be set with dFader_c::setFader. The fade-in and fade-out durations can be set using setFadeInFrame and setFadeOutFrame respectively. Both can be set simultaneously with setFadeInOutFrame).

The previous scene is automatically deleted once the fade-out completes. The next scene will fade in automatically unless m_isAutoFadeIn is set to false (in that case, the fade-in must be started manually by calling dFader_c::startFadeIn and audio must be reinitialized with dAudio::requestStartScene).

Definition at line 66 of file d_scene.hpp.

Public Member Functions
	dScene_c ()
	Creates a new scene.

	~dScene_c ()
	Destroys the scene.

virtual int	preCreate ()
	`pre` method for the `create` operation.

virtual void	postCreate (fBase_c::MAIN_STATE_e status)
	`post` method for the `create` operation.

virtual int	preDelete ()
	`pre` method for the `delete` operation.

virtual void	postDelete (fBase_c::MAIN_STATE_e status)
	`post` method for the `delete` operation.

virtual int	preExecute ()
	`pre` method for the `execute` operation.

virtual void	postExecute (fBase_c::MAIN_STATE_e status)
	`post` method for the `execute` operation.

virtual int	preDraw ()
	`pre` method for the `draw` operation.

virtual void	postDraw (fBase_c::MAIN_STATE_e status)
	`post` method for the `draw` operation.

Public Member Functions inherited from dBase_c
	dBase_c ()
	Constructs a new base.

virtual	~dBase_c ()
	Destroys the base.

virtual const char *	getKindString () const
	Gets the base's kind string.

Public Member Functions inherited from fBase_c
	fBase_c ()
	Constructs a new base.

void	deleteRequest ()
	Requests deletion of the base.

fBase_c *	getConnectParent () const
	Gets the base's parent.

fBase_c *	getConnectChild () const
	Gets the base's first child.

fBase_c *	getConnectBrNext () const
	Gets the base's next sibling.

bool	checkChildProcessCreateState () const
	Checks if the base has at least one child in the CREATING state.

Public Member Functions inherited from cOwnerSetMg_c
	cOwnerSetMg_c ()
	Constructs a new set container.

	~cOwnerSetMg_c ()
	Destroys the set.

void	add (cOwnerSetNd_c nd, void owner)
	Adds a node to the set.

void	remove (cOwnerSetNd_c nd, void owner)
	Removes a node from the set.

Static Public Member Functions
static void	setStartScene ()
	Sets up the scene to be shown when the game boots up.

static void	setResetScene ()
	Sets up the scene to be shown after a game reset.

static dScene_c *	createNextScene ()
	Creates and returns a root base for the next scene.

static void	setNextScene (ProfileName nextScene, unsigned long param, bool forceChange)
	Attempts to prepare the transition to a new scene.

static void	setFadeInFrame (unsigned short length)
	Sets the duration of the next fade-in transition to `length`.

static void	setFadeOutFrame (unsigned short length)
	Sets the duration of the next fade-out transition to `length`.

static void	setFadeInOutFrame (unsigned short length)
	Sets the duration of the next fade-in and fade-out transitions to `length`.

Static Public Member Functions inherited from dBase_c
static dBase_c *	searchBaseByProfName (ProfileName profile, const dBase_c *parent)
	Searches for a base with a given profile name, optionally under a given parent.

static void	initLoader ()
	[Unused]. Sets the callbacks for the scrapped relocatable profile system.

static dBase_c *	createBase (ProfileName profName, dBase_c *parent, unsigned long param, u8 groupType)
	Creates a child base under the given parent.

static dBase_c *	createRoot (ProfileName profName, unsigned long param, u8 groupType)
	Creates a root base.

Static Public Member Functions inherited from fBase_c
static void *	operator new (size_t)
	`new` operator override for all bases.

static void	operator delete (void *)
	`delete` operator override for all bases.

static fBase_c *	createChild (ProfileName profName, fBase_c *parent, unsigned long param, u8 groupType)
	Creates a child base under the given parent.

static fBase_c *	createRoot (ProfileName profName, unsigned long param, u8 groupType)
	Creates a root base.

Public Attributes
sPhase_c *	mpPhase
	The phase used for scene initialization.

Public Attributes inherited from fBase_c
fBaseID_e	mUniqueID
	The base's unique identifier.

u32	mParam
	A bitfield that configures the base's behaviour. Its usage varies from profile to profile.

ProfileName	mProfName
	The base's profile name.

Static Public Attributes
static u32	mPara
	The parameters for the next scene.

static ProfileName	m_nextScene = fProfile::INVALID
	The profile name of the next scene.

static ProfileName	m_nowScene = fProfile::INVALID
	The profile name of the current scene.

static ProfileName	m_oldScene = fProfile::INVALID
	The profile name of the previous scene.

static bool	m_otherSceneFlg = true
	Whether the next scene has already been created.

static u16	m_fadeInFrame = 30
	The duration of the next fade-in.

static u16	m_fadeOutFrame = 30
	The duration of the next fade-out.

static bool	m_isAutoFadeIn = true
	If a fade-in should automatically be performed on scene load.

Additional Inherited Members
Public Types inherited from fBase_c
enum	LIFECYCLE_e { CREATING , ACTIVE , DELETING }
	The possible lifecycle states. More...

enum	GROUP_TYPE_e { OTHER , SCENE , ACTOR }
	The possible group types. More...

enum	MAIN_STATE_e { CANCELED , ERROR , SUCCESS , WAITING }
	The possible operation results. More...

enum	PACK_RESULT_e { NOT_READY , SUCCEEDED , FAILED }
	The possible operation step results. More...

enum	PROC_DISABLE_e { ROOT_DISABLE_EXECUTE = BIT_FLAG(0) , DISABLE_EXECUTE = BIT_FLAG(1) , ROOT_DISABLE_DRAW = BIT_FLAG(2) , DISABLE_DRAW = BIT_FLAG(3) }
	Controls if the `execute` and `draw` operations should be skipped. More...

Protected Member Functions inherited from fBase_c
bool	isProcControlFlag (u8 flag) const
	Checks if a flag is set in mProcControl.

void	setProcControlFlag (u8 flag)
	Sets a flag in mProcControl.

void	clearProcControlFlag (u8 flag)
	Clears a flag in mProcControl.

virtual int	create ()
	`do` method for the `create` operation.

virtual int	doDelete ()
	`do` method for the `delete` operation.

virtual int	execute ()
	`do` method for the `execute` operation.

virtual int	draw ()
	`do` method for the `draw` operation.

virtual void	deleteReady ()
	Informs the base that it's about to be deleted.

virtual bool	entryFrmHeap (unsigned long size, EGG::Heap *parentHeap)
	[Unused]. Creates a heap of the given size for the base.

virtual bool	entryFrmHeapNonAdjust (unsigned long size, EGG::Heap *parentHeap)
	[Unused]. Creates a heap of the given size for the base.

virtual bool	createHeap ()
	[Unused]. [Does nothing].

virtual	~fBase_c ()
	Destroys the base.

Protected Attributes inherited from fBase_c
u8	mLifecycleState
	The base's lifecycle state. Value is a LIFECYCLE_e.

bool	mDeleteRequested
	If deletion of the base was requested, but the `delete` operation has not been scheduled yet.

bool	mDeferExecute
	If the `create` operation was completed, but scheduling the `execute` and `draw` operations isn't possible at this time.

bool	mDeferRetryCreate
	If the `create` operation has not been completed, and rescheduling it isn't possible at this time.

u8	mGroupType
	The base's group type. Value is a GROUP_TYPE_e.

u8	mProcControl
	The operations to be skipped. Value is a PROC_DISABLE_e.

fManager_c	mMng
	The base's process manager.

fBaHelper_c *	mpUnusedHelper
	[Unused]. See Unused Content.

fLiMgBa_c	mUnusedList
	[Unused]. See Unused Content.

EGG::FrmHeap *	mHeap
	[Unused]. The base's dedicated heap.

Static Protected Attributes inherited from fBase_c
static int(*	sLoadAsyncCallback )()
	[Unused]. See Unused Content.

static void(*	sUnloadCallback )()
	[Unused]. See Unused Content.

Constructor & Destructor Documentation

◆ dScene_c()

dScene_c::dScene_c ( )

Creates a new scene.

Definition at line 23 of file d_scene.cpp.

◆ ~dScene_c()

dScene_c::~dScene_c ( )

Destroys the scene.

Definition at line 37 of file d_scene.cpp.

Member Function Documentation

◆ preCreate()

int dScene_c::preCreate ( )

virtual

pre method for the create operation.

Returns: A PACK_RESULT_e value.

Reimplemented from dBase_c.

Definition at line 44 of file d_scene.cpp.

◆ postCreate()

void dScene_c::postCreate ( fBase_c::MAIN_STATE_e status )

virtual

post method for the create operation.

Appends a LASTACTOR child base to this scene.

Reimplemented from dBase_c.

Definition at line 53 of file d_scene.cpp.

◆ preDelete()

int dScene_c::preDelete ( )

virtual

pre method for the delete operation.

Returns: A PACK_RESULT_e value.

Reimplemented from dBase_c.

Definition at line 62 of file d_scene.cpp.

◆ postDelete()

void dScene_c::postDelete ( fBase_c::MAIN_STATE_e state )

virtual

post method for the delete operation.

Reimplemented from dBase_c.

Definition at line 69 of file d_scene.cpp.

◆ preExecute()

int dScene_c::preExecute ( )

virtual

pre method for the execute operation.

If m_nextScene is set, prepares to transition to the next scene. Once all initial child bases have been added, the execute and draw operations are enabled on this base and its children.

Reimplemented from dBase_c.

Definition at line 77 of file d_scene.cpp.

◆ postExecute()

void dScene_c::postExecute ( fBase_c::MAIN_STATE_e state )

virtual

post method for the execute operation.

Reimplemented from dBase_c.

Definition at line 115 of file d_scene.cpp.

◆ preDraw()

int dScene_c::preDraw ( )

virtual

pre method for the draw operation.

Returns: A PACK_RESULT_e value.

Reimplemented from dBase_c.

Definition at line 122 of file d_scene.cpp.

◆ postDraw()

void dScene_c::postDraw ( fBase_c::MAIN_STATE_e state )

virtual

post method for the draw operation.

Reimplemented from dBase_c.

Definition at line 129 of file d_scene.cpp.

◆ setStartScene()

void dScene_c::setStartScene ( )

static

Sets up the scene to be shown when the game boots up.

Definition at line 133 of file d_scene.cpp.

◆ setResetScene()

void dScene_c::setResetScene ( )

static

Sets up the scene to be shown after a game reset.

Definition at line 141 of file d_scene.cpp.

◆ createNextScene()

dScene_c * dScene_c::createNextScene ( )

static

Creates and returns a root base for the next scene.

Definition at line 145 of file d_scene.cpp.

◆ setNextScene()

void dScene_c::setNextScene	(	ProfileName	nextScene,
		unsigned long	param,
		bool	forceChange )

static

Attempts to prepare the transition to a new scene.

If the game is resetting, the transition is not performed unless forceChange is true.

Parameters

nextScene	The next scene's profile name.
param	The next scene's parameters.
forceChange	If the transition should always be performed.

Definition at line 162 of file d_scene.cpp.

◆ setFadeInFrame()

void dScene_c::setFadeInFrame ( unsigned short length )

static

Sets the duration of the next fade-in transition to length.

Definition at line 184 of file d_scene.cpp.

◆ setFadeOutFrame()

void dScene_c::setFadeOutFrame ( unsigned short length )

static

Sets the duration of the next fade-out transition to length.

Definition at line 188 of file d_scene.cpp.

◆ setFadeInOutFrame()

void dScene_c::setFadeInOutFrame ( unsigned short length )

static

Sets the duration of the next fade-in and fade-out transitions to length.

Definition at line 192 of file d_scene.cpp.

Member Data Documentation

◆ mpPhase

sPhase_c* dScene_c::mpPhase

The phase used for scene initialization.

Definition at line 110 of file d_scene.hpp.

◆ mPara

u32 dScene_c::mPara

static

The parameters for the next scene.

Definition at line 112 of file d_scene.hpp.

◆ m_nextScene

ProfileName dScene_c::m_nextScene = fProfile::INVALID

static

The profile name of the next scene.

Definition at line 113 of file d_scene.hpp.

◆ m_nowScene

ProfileName dScene_c::m_nowScene = fProfile::INVALID

static

The profile name of the current scene.

Definition at line 114 of file d_scene.hpp.

◆ m_oldScene

ProfileName dScene_c::m_oldScene = fProfile::INVALID

static

The profile name of the previous scene.

Definition at line 115 of file d_scene.hpp.

◆ m_otherSceneFlg

bool dScene_c::m_otherSceneFlg = true

static

Whether the next scene has already been created.

Definition at line 116 of file d_scene.hpp.

◆ m_fadeInFrame

u16 dScene_c::m_fadeInFrame = 30

static

The duration of the next fade-in.

Definition at line 118 of file d_scene.hpp.

◆ m_fadeOutFrame

u16 dScene_c::m_fadeOutFrame = 30

static

The duration of the next fade-out.

Definition at line 119 of file d_scene.hpp.

◆ m_isAutoFadeIn

bool dScene_c::m_isAutoFadeIn = true

static

If a fade-in should automatically be performed on scene load.

Definition at line 120 of file d_scene.hpp.

Description

Overview

Switching Scenes

Scene Initialization

Audio Initialization

Scene Fading

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ dScene_c()

◆ ~dScene_c()

Member Function Documentation

◆ preCreate()

◆ postCreate()

◆ preDelete()

◆ postDelete()

◆ preExecute()

◆ postExecute()

◆ preDraw()

◆ postDraw()

◆ setStartScene()

◆ setResetScene()

◆ createNextScene()

◆ setNextScene()

◆ setFadeInFrame()

◆ setFadeOutFrame()

◆ setFadeInOutFrame()

Member Data Documentation

◆ mpPhase

◆ mPara

◆ m_nextScene

◆ m_nowScene

◆ m_oldScene

◆ m_otherSceneFlg

◆ m_fadeInFrame

◆ m_fadeOutFrame

◆ m_isAutoFadeIn