The singleton object responsible for game execution. More...

Inheritance diagram for Engine:

Public Types
enum	Phase { LOGICS_PHASE = 0, BEFORE_PHYSICS_PHASE, PHYSICS_PHASE, AFTER_PHYSICS_PHASE, CAMERA_PHASE, RENDERING_PHASE }
	The phases of Engine execution. More...

Public Slots
void	pause ()
	Respond to game pause. More...

void	resume ()
	Respond to game resume. More...

void	onPlayLevelRequested ()
	Respond to request to play the current level. More...

void	onQuitRequested ()
	Respond to quit request. More...

void	onSignedIntoCloudChanged (bool signedIntoCloud)
	Respond to state of cloud sign-in changed. More...

void	onCloudDataLoaded (int statusCode, const QString &data)
	Respond to cloud data being loaded. More...

void	onOpeningCinematicCompleted (const QString &menuBGMTrack)
	Respond to opening cinematic finishing. More...

Android Device Lifecycle slots
The calling of these methods is not guaranteed but rather contingent upon initialization of the Engine. E.g. "onDeviceCreate" will likely not be called since the Engine may not yet have been initialized in a thread separate from the main device thread, as the thread we just spawned, but we leave it here for completion.
void	onDeviceCreate ()
	Respond to Android onCreate(). More...

void	onDeviceStart ()
	Respond to Android onStart(). More...

void	onDeviceResume ()
	Respond to Android onResume(). More...

void	onDevicePause ()
	Respond to Android onPause(). More...

void	onDeviceStop ()
	Respond to Android onStop(). More...

void	onDeviceDestroy ()
	Respond to Android onDestroy(). More...

Signals
void	levelChanged (const QString &levelName, int completionThreshold, int activationThreshold)
	Emitted when a new level is finished loading a level. More...

void	signedIntoCloudChanged (bool signedIntoCloud)
	Emitted when cloud sign-in has changed. More...

void	cloudDataLoaded (int statusCode, const QString &data)
	Emitted when the cloud data is loaded. More...

void	beforeUpdate ()
	Emitted at the start of the update() call. More...

void	afterUpdate ()
	Emitted at the end of the update() call. More...

void	deviceDestroy ()
	Signal for when the device has reached the end of its application lifecycle. More...

Android Device Lifecycle
These signals are all emitted when each of their respective slots are called.
void	deviceCreate ()
	Emitted at end of onDeviceCreate(). More...

void	deviceStart ()
	Emitted at end of onDeviceStart(). More...

void	deviceResume ()
	Emitted at end of onDeviceResume(). More...

void	devicePause ()
	Emitted at end of onDevicePause(). More...

void	deviceStop ()
	Emitted at end of onDeviceStop(). More...

Public Member Functions
void	init ()
	Initialize the Engine. More...

bool	isInitialized () const
	Returns `true` if the Engine has been initialized. More...

Q_INVOKABLE bool	isPaused () const
	Returns `true` if engine is paused, e.g. when the in-game menu is open. More...

b2World *	getWorld () const
	Returns the Box2D world object. More...

long long	getWorldStepCount () const
	Returns the number of physics steps since last level loaded. More...

QQmlEngine *	getQmlEngine () const
	Returns the QQmlEngine being used by the Engine. More...

QQuickItem *	getRoot () const
	Returns the root item, as defined in the main QML file. More...

Camera *	getCamera () const
	Returns the Camera object. More...

Renderer *	getRenderer () const
	Returns the `Renderer` object, the game-specific renderer. More...

Q_INVOKABLE SoundManager *	getSoundManager () const
	Returns the SoundManager object. More...

TextureManager *	getTextureManager () const
	Returns the `TextureManager` object. More...

TerrainMaterials *	getTerrainMaterials () const
	Returns the `TerrainMaterials` object. More...

ContactListener *	getContactListener () const
	Returns ContactListener, the Engine's implementation of the b2ContactListener. More...

Phase	getPhase () const
	Return the phase of execution. More...

void	addChildItem (QQuickItem *item)
	Add a child item to the QQuickItem scene graph. More...

Q_INVOKABLE Level *	getLevel () const
	Returns the current Level being displayed and executed. More...

Q_INVOKABLE void	setTrackerScreenName (const QString &screenName, bool sendScreenView=true)
	Sets the Google Analytics screen name and optionally sends a screen view hit. More...

Q_INVOKABLE void	sendTrackerEvent (const QString &category, const QString &action)
	Sends an event hit to Google Analytics. More...

Q_INVOKABLE void	sendTrackerEvent (const QString &category, const QString &action, const QString &label)
	Sends an event hit to Google Analytics. More...

Q_INVOKABLE void	sendTrackerEvent (const QString &category, const QString &action, const QString &label, long value)
	Sends an event hit to Google Analytics. More...

Q_INVOKABLE void	sendTrackerEvent (const QString &category, const QString &action, long value)
	Sends an event hit to Google Analytics. More...

void	loadLevel (LevelInfo *levelInfo)
	Emits the signal to load level/start game. More...

void	deleteCurrentLevel ()
	Mark the current level for deletion and remove it from the scene graph to avoid continuing rendering of the current level. More...

QObject Traversal Functions
These functions help in the traversal of the QObject scene graph.
template<typename T >
void	forEach (const std::function< void(T *)> &func) const
	Recursively traverses scene graph and call `func` on each QObject of type T. More...

template<typename T >
void	invalidateSceneGraphObjectCache ()
	Invalidates the cache of scene graph objects of the specified type. More...

void	invalidateSceneGraphObjectCaches ()
	Invalidates the caches of all scene graph objects, regardless of type. More...

template<typename T >
void	forEach (QObject root, const std::function< void(T )> &func) const
	Recursively traverses scene graph and call func on each QObject of type T, starting at the given root. More...

Public Member Functions inherited from QObject
	QObject (QObject *parent)

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

virtual const QMetaObject *	metaObject () const

QString	objectName () const

void	setObjectName (const QString &name)

bool	isWidgetType () const

bool	isWindowType () const

bool	signalsBlocked () const

bool	blockSignals (bool block)

QThread *	thread () const

void	moveToThread (QThread *targetThread)

int	startTimer (int interval, Qt::TimerType timerType)

void	killTimer (int id)

T	findChild (const QString &name, QFlags< Qt::FindChildOption > options) const

QList< T >	findChildren (const QString &name, QFlags< Qt::FindChildOption > options) const

QList< T >	findChildren (const QRegExp &regExp, QFlags< Qt::FindChildOption > options) const

QList< T >	findChildren (const QRegularExpression &re, QFlags< Qt::FindChildOption > options) const

const QObjectList &	children () const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const

bool	disconnect (const char signal, const QObject receiver, const char *method) const

bool	disconnect (const QObject receiver, const char method) const

void	dumpObjectTree ()

void	dumpObjectInfo ()

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const

QList< QByteArray >	dynamicPropertyNames () const

void	destroyed (QObject *obj)

void	objectNameChanged (const QString &objectName)

QObject *	parent () const

bool	inherits (const char *className) const

void	deleteLater ()

Static Public Member Functions
static Engine *	getInstance (bool createIfNecessary=true)
	Returns the global singleton instance of Engine. More...

Static Public Member Functions inherited from QObject
QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

Static Public Attributes
static const float	UPDATE_FREQUENCY
	The target frame rate. More...

static const float	TIME_STEP_S
	The fixed simulation time step between frames, in seconds. More...

static const float	TIME_STEP_MS
	The fixed simulation time step between frames, in milliseconds. More...

static const int	VELOCITY_ITERATIONS
	LiquidFun velocity iterations, controlling world substepping. More...

static const int	POSITION_ITERATIONS
	LiquidFun position iterations, controlling world substepping. More...

static const int	PARTICLE_ITERATIONS
	LiquidFun particle solve iterations, controlling world substepping. More...

Friends
class	Level

Additional Inherited Members
Protected Member Functions inherited from QObject
QObject *	sender () const

int	senderSignalIndex () const

int	receivers (const char *signal) const

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

Properties inherited from QObject
	objectName

Detailed Description

The singleton object responsible for game execution.

This is the main object for execution and rendering of the game. It is responsible for:

Loading/unloading of levels
Loading of overlays such as UI
Execution of the game physics
Registration and execution of Logic objects
Maintaining Google Analytics

It is also the parent object for the numerous sub-objects that are required for engine interaction.

Not Quite a Game Engine

This Engine object is about as close as the VoltAir code comes to defining a game engine. Just to be certain it's not misleading, the Engine object should not be misconstrued into being considered a full engine. It was just separated out to diagram out the beginnings of one.

Game Execution

VoltAir is built on QtQuick, which provides a multi-threaded system for execution and rendering. Please see the section on "Threaded Render Loop" in the Qt Quick Scene Graph documentation.

In the context of this, the "mainline" of the engine is implemented in the private update() slot, which is connected to the QQuickView::afterAnimating() signal, which occurs in the UI thread after all QQuickItem properties are updated.

Within that update() call, there are three phases of execution. In order:

Logics phase: All the Logic objects' update() functions are called.
Physics phase: The Box2D physics are executed.
Camera phase: The camera is updated, having potentially changed due to QML/Logics execution.

Please see the Phase enum below for more information on the phases.

After the update() is executed, the system is ready to draw the current frame's graphics, through a combination of QtQuick's scene graph for the UI, and VoltAir's Renderer for the game world.

Member Enumeration Documentation

enum Engine::Phase

The phases of Engine execution.

This enum describes the possible phases that the engine is in during an update() call.

Enumerator
LOGICS_PHASE	Engine is executing the Logic::update() calls. These contain a majority of the game's gameplay logic, including player input processing and triggers.
BEFORE_PHYSICS_PHASE	Engine is executing the Body::updateBeforePhysics() calls. This allows the Bodys to synchronize their internal physics body positions and transforms to the Actor, if the Actor's was changed due to some external action such as Logics.
PHYSICS_PHASE	Engine is executing the Box2D/LiquidFun physics. This causes dynamic Bodys to update position.
AFTER_PHYSICS_PHASE	Engine is executing the Body::updateAfterPhysics() calls. This allows Bodys to synchronize with their associated Actors and Graphics with their internal physics body positions and transforms.
CAMERA_PHASE	Engine is adjusting the camera relative to the state of the world. In this phase, the Camera's properties are applied to the environment's view. It's important to note this as it implies that before this phase, for instance in the LOGICS_PHASE, the Camera actually contains the previous frame's view, not the current frame's.
RENDERING_PHASE	Engine is rendering. Note It remains in this state until it returns to the `LOGICS_PHASE`.

Member Function Documentation

void Engine::addChildItem ( QQuickItem * item )

Add a child item to the QQuickItem scene graph.

This is used, for instance, to add UI and HUD elements to the QQuickView.

void Engine::afterUpdate ( )

signal

Emitted at the end of the update() call.

void Engine::beforeUpdate ( )

signal

Emitted at the start of the update() call.

void Engine::cloudDataLoaded	(	int	statusCode,
		const QString &	data
	)

signal

Emitted when the cloud data is loaded.

Parameters

statusCode	The returned status code from the data load
data	String describing the data loaded.

void Engine::deleteCurrentLevel ( )

Mark the current level for deletion and remove it from the scene graph to avoid continuing rendering of the current level.

void Engine::deviceCreate ( )

signal

Emitted at end of onDeviceCreate().

void Engine::deviceDestroy ( )

signal

Signal for when the device has reached the end of its application lifecycle.

Note: Only attach to this signal using Qt::DirectConnection since the application is exiting, but, as a result, also note that any code executed from this signal will likely be running in a device thread different from the Qt Ui thread.

void Engine::devicePause ( )

signal

Emitted at end of onDevicePause().

void Engine::deviceResume ( )

signal

Emitted at end of onDeviceResume().

void Engine::deviceStart ( )

signal

Emitted at end of onDeviceStart().

void Engine::deviceStop ( )

signal

Emitted at end of onDeviceStop().

template<typename T >

void Engine::forEach ( const std::function< void(T *)> & func ) const

inline

Recursively traverses scene graph and call func on each QObject of type T.

Note: Matches are cached and can be flushed with a call to invalidateSceneGraphObjectCache() or invalidateSceneGraphObjectCaches(). See Below

Template Parameters

T	Subclass of QObject to search for.

Parameters

func	Function to call on each node of type T

template<typename T >

void Engine::forEach	(	QObject *	root,
		const std::function< void(T *)> &	func
	)		const

inline

Recursively traverses scene graph and call func on each QObject of type T, starting at the given root.

Note: Matches are not cached in this version.

Template Parameters

T	Subclass of QObject to search for.

Parameters

root	Object at which to start the traversal
func	Function to call on each node of type T

Camera* Engine::getCamera ( ) const

inline

Returns the Camera object.

ContactListener* Engine::getContactListener ( ) const

inline

Returns ContactListener, the Engine's implementation of the b2ContactListener.

static Engine* Engine::getInstance ( bool createIfNecessary = true )

static

Returns the global singleton instance of Engine.

Parameters

createIfNecessary Whether or not to create the singleton if it does not exist

Q_INVOKABLE Level* Engine::getLevel ( ) const

inline

Returns the current Level being displayed and executed.

Phase Engine::getPhase ( ) const

inline

Return the phase of execution.

See also: Phase

QQmlEngine* Engine::getQmlEngine ( ) const

Returns the QQmlEngine being used by the Engine.

Renderer* Engine::getRenderer ( ) const

inline

Returns the Renderer object, the game-specific renderer.

QQuickItem* Engine::getRoot ( ) const

Returns the root item, as defined in the main QML file.

Q_INVOKABLE SoundManager* Engine::getSoundManager ( ) const

inline

Returns the SoundManager object.

TerrainMaterials* Engine::getTerrainMaterials ( ) const

inline

Returns the TerrainMaterials object.

TextureManager* Engine::getTextureManager ( ) const

inline

Returns the TextureManager object.

b2World* Engine::getWorld ( ) const

Returns the Box2D world object.

long long Engine::getWorldStepCount ( ) const

inline

Returns the number of physics steps since last level loaded.

void Engine::init ( )

Initialize the Engine.

This includes:

Constructing and displaying the QQuickView "window"
Setting up the game-specific renderer

It is intended to only be called once and will ignore all subsequent calls.

template<typename T >

void Engine::invalidateSceneGraphObjectCache ( )

inline

Invalidates the cache of scene graph objects of the specified type.

This function should be used whenever the scene graph is dynamically changed.

Note: This function is dangerous if not used correctly due to polymorphism. For now, prefer total invalidation of all scene graph object caches unless you are certain the scene graph has only been altered for specific types.

void Engine::invalidateSceneGraphObjectCaches ( )

inline

Invalidates the caches of all scene graph objects, regardless of type.

This function should be used whenever the scene graph is dynamically changed.

bool Engine::isInitialized ( ) const

inline

Returns true if the Engine has been initialized.

Q_INVOKABLE bool Engine::isPaused ( ) const

inline

Returns true if engine is paused, e.g. when the in-game menu is open.

void Engine::levelChanged	(	const QString &	levelName,
		int	completionThreshold,
		int	activationThreshold
	)

signal

Emitted when a new level is finished loading a level.

Parameters

levelName	Name of the level
completionThreshold	Total number of collectibles in this level
activationThreshold	Number of collectibles before the level's Teleporter is opened

void Engine::loadLevel ( LevelInfo * levelInfo )

Emits the signal to load level/start game.

void Engine::onCloudDataLoaded	(	int	statusCode,
		const QString &	data
	)

slot

Respond to cloud data being loaded.

void Engine::onDeviceCreate ( )

slot

Respond to Android onCreate().

void Engine::onDeviceDestroy ( )

slot

Respond to Android onDestroy().

void Engine::onDevicePause ( )

slot

Respond to Android onPause().

void Engine::onDeviceResume ( )

slot

Respond to Android onResume().

void Engine::onDeviceStart ( )

slot

Respond to Android onStart().

void Engine::onDeviceStop ( )

slot

Respond to Android onStop().

void Engine::onOpeningCinematicCompleted ( const QString & menuBGMTrack )

slot

Respond to opening cinematic finishing.

void Engine::onPlayLevelRequested ( )

slot

Respond to request to play the current level.

void Engine::onQuitRequested ( )

slot

Respond to quit request.

void Engine::onSignedIntoCloudChanged ( bool signedIntoCloud )

slot

Respond to state of cloud sign-in changed.

void Engine::pause ( )

slot

Respond to game pause.

void Engine::resume ( )

slot

Respond to game resume.

Q_INVOKABLE void Engine::sendTrackerEvent	(	const QString &	category,
		const QString &	action
	)

Sends an event hit to Google Analytics.

Parameters

category	Category in which the event will be filed
action	Action associated with the event

Note: This function only has an effect on an Android device.

Q_INVOKABLE void Engine::sendTrackerEvent	(	const QString &	category,
		const QString &	action,
		const QString &	label
	)

Sends an event hit to Google Analytics.

Parameters

category	Category in which the event will be filed
action	Action associated with the event
label	Descriptive label used for further differentiation of categorical actions

Note: This function only has an effect on an Android device.

Q_INVOKABLE void Engine::sendTrackerEvent	(	const QString &	category,
		const QString &	action,
		const QString &	label,
		long	value
	)

Sends an event hit to Google Analytics.

Parameters

category	Category in which the event will be filed
action	Action associated with the event
label	Descriptive label used for further differentiation of categorical actions
value	Value to be logged with the event

Note: This function only has an effect on an Android device.

Q_INVOKABLE void Engine::sendTrackerEvent	(	const QString &	category,
		const QString &	action,
		long	value
	)

Sends an event hit to Google Analytics.

Parameters

category	Category in which the event will be filed
action	Action associated with the event
value	Value to be logged with the event

Note: This function only has an effect on an Android device.

Q_INVOKABLE void Engine::setTrackerScreenName	(	const QString &	screenName,
		bool	sendScreenView = `true`
	)

Sets the Google Analytics screen name and optionally sends a screen view hit.

Parameters

screenName	Name of screen to be set
sendScreenView	`true` if a screen view hit should be sent

Note: This function only has an effect on an Android device.

void Engine::signedIntoCloudChanged ( bool signedIntoCloud )

signal

Emitted when cloud sign-in has changed.

Parameters

signedIntoCloud True if signed in, false if signed out

Member Data Documentation

const int Engine::PARTICLE_ITERATIONS

static

LiquidFun particle solve iterations, controlling world substepping.

const int Engine::POSITION_ITERATIONS

static

LiquidFun position iterations, controlling world substepping.

const float Engine::TIME_STEP_MS

static

The fixed simulation time step between frames, in milliseconds.

const float Engine::TIME_STEP_S

static

The fixed simulation time step between frames, in seconds.

const float Engine::UPDATE_FREQUENCY

static

The target frame rate.

const int Engine::VELOCITY_ITERATIONS

static

LiquidFun velocity iterations, controlling world substepping.

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Additional Inherited Members

Detailed Description

Not Quite a Game Engine

Game Execution

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation