Abstract base class for game scenes. More...

#include <Scene.h>

Inheritance diagram for ime::Scene:

Public Types
using	Ptr = std::shared_ptr< Scene >
	Shared Scene pointer. More...

Public Member Functions
	Scene ()
	Constructor. More...

	Scene (Scene &&) noexcept
	Move constructor. More...

Scene &	operator= (Scene &&) noexcept
	Move assignment operator. More...

void	init (Engine &engine)

virtual void	onEnter ()=0
	Enter the scene. More...

virtual void	handleEvent (Event event)
	Handle a system event. More...

virtual void	update (Time deltaTime)
	Update the scene. More...

virtual void	fixedUpdate (Time deltaTime)
	Update the scene in fixed time steps. More...

virtual void	postUpdate (Time deltaTime)
	Post update the scene. More...

virtual void	onPause ()
	Pause the scene. More...

virtual void	onResume ()
	Resume scene. More...

virtual void	onExit ()
	Exit a scene. More...

std::string	getClassName () const override
	Get the name of the scene. More...

bool	isVisibleOnPause () const
	Check if the scene is visible when paused or not. More...

bool	isEntered () const
	Check if the scene has been entered or not. More...

template<typename ... Args>
int	on_ (const std::string &event, Callback< Args... > callback)

bool	unsubscribe_ (const std::string &event, int id)

	~Scene () override
	Destructor. More...

void	setTag (const std::string &tag)
	Assign the object an alias. More...

const std::string &	getTag () const
	Get the alias of the object. More...

unsigned int	getObjectId () const
	Get the id of the object. More...

virtual std::string	getClassType () const
	Get the name of the direct parent of an object instance. More...

int	onPropertyChange (const std::string &property, const Callback< Property > &callback)
	Add an event listener to a specific property change event. More...

void	onPropertyChange (const Callback< Property > &callback)
	Add an event listener to a property change event. More...

int	onEvent (const std::string &event, const Callback<> &callback)
	Add an event listener to an event. More...

bool	unsubscribe (const std::string &event, int id)
	Remove an event listener from an event. More...

int	onDestruction (const Callback<> &callback)
	Add a destruction listener. More...

bool	removeDestructionListener (int id)
	Remove a destruction listener form the object. More...

bool	operator== (const Object &rhs) const
	Check if two objects are the same object or not. More...

bool	operator!= (const Object &rhs) const
	Check if two objects are not the same object. More...

Protected Member Functions
void	setVisibleOnPause (bool show)
	Set whether or not the scene is hidden or rendered when it is paused. More...

void	setTimescale (float timescale)
	Set the scene timescale. More...

float	getTimescale () const
	Get the scenes timescale. More...

Engine &	engine () const
	Get a reference to the game engine. More...

Camera &	camera ()
	Get the scene camera. More...

World &	physics ()
	Get the physics simulation. More...

GridMoverContainer &	gridMovers ()
	Get the scenes grid mover container. More...

EventEmitter &	eventEmitter ()
	Get the scenes event event emitter. More...

EventDispatcher &	globalEventEmitter ()
	Get the global event emitter. More...

input::InputManager &	input ()
	Get the scenes input manager. More...

audio::AudioManager &	audio ()
	Get the scenes audio manager. More...

TimerManager &	timer ()
	Get the scenes timer manager. More...

PropertyContainer &	cache ()
	Get the global cache. More...

RenderLayerContainer &	renderLayers ()
	Get the scene render layers. More...

TileMap &	tilemap ()
	Get the scene Tilemap. More...

ui::GuiContainer &	gui ()
	Get the scene gui container. More...

ShapeContainer &	shapes ()
	Get the scene geometry shape container. More...

GameObjectContainer &	gameObjects ()
	Get the scene game object container. More...

SpriteContainer &	sprites ()
	Get the scene sprite container. More...

void	createWorld (Vector2f gravity)
	Create a physics simulation. More...

void	createTilemap (unsigned int tileWidth, unsigned int tileHeight)
	Create tilemap instance. More...

void	emitChange (const Property &property)
	Dispatch a property change event. More...

void	emit (const std::string &event)
	Dispatch an action event. More...

Friends
class	SceneManager
	Pre updates the scene. More...

Detailed Description

Abstract base class for game scenes.

A scene represents a distinct state of your game, for example loading, main menu, gameplay, paused and so on. All game scenes exist in isolation and have no knowledge of each other. Only one scene can be active at a time. For example, the game cannot be in a main menu state and a gameplay state at the same time.

The transition between scenes is managed using the Last In First Out (LIFO) technique (The same way std::stack works). Therefore you cannot transition between scenes at random. The order in which scenes are added to the Engine is important.

For example, if while in the "gameplay" scene, you push a "pause" scene to the game engine, the "gameplay" scene will be paused (onPause called) and the "pause" scene will be entered (onEnter called on the pause scene instance) and the "pause" scene will become the active scene (gets system events, updates and rendered). If you pop the "pause" scene, the engine will destroy it (onExit called on the pause scene instance) and return to the "gameplay" scene (onResume called on the gameplay scene instance). However, if you push (transition to) another scene while in the "pause" scene, the process repeats; the "pause" scene gets paused and the the new scene becomes active)

Definition at line 79 of file Scene.h.

Member Typedef Documentation

◆ Ptr

using ime::Scene::Ptr = std::shared_ptr<Scene>

Shared Scene pointer.

Definition at line 81 of file Scene.h.

Constructor & Destructor Documentation

◆ Scene() [1/2]

ime::Scene::Scene ( )

Constructor.

Parameters

engine A reference to the game engine

◆ Scene() [2/2]

ime::Scene::Scene ( Scene && )

noexcept

Move constructor.

◆ ~Scene()

ime::Scene::~Scene ( )

override

Destructor.

Member Function Documentation

◆ audio()

audio::AudioManager& ime::Scene::audio ( )

protected

Get the scenes audio manager.

Returns: The scenes audio manager

The audio manager is local the scene instance. For global audio, use the global audio manager in the Engine class

Warning: Do not keep the returned reference; Do not try to update the audio manager, it will be updated internally

◆ cache()

PropertyContainer& ime::Scene::cache ( )

protected

Get the global cache.

Returns: The global cache

Data stored in the cache persists from scene to scene. This means that another scene can access or modify data stored by another scene. The data can also be accessed using the engine instance

Note: The cache only stores data, while the engine is running. When the engine is shutdown, the data in the cache is destroyed

Warning: Do not keep the returned reference

See also: engine

◆ camera()

Camera& ime::Scene::camera ( )

protected

Get the scene camera.

Returns: The scene camera

◆ createTilemap()

void ime::Scene::createTilemap	(	unsigned int	tileWidth,
		unsigned int	tileHeight
	)

protected

Create tilemap instance.

Parameters

tileWidth	The width of the tilemap
tileHeight	The height of the tilemap

Note that this function only creates a tilemap instance so that it can be used. You still need to construct the tilemap using the appropriate member function

Warning: Only a single tilemap can be created, therefore calling this function will destroy the previous tilemap

See also: tilemap

◆ createWorld()

void ime::Scene::createWorld ( Vector2f gravity )

protected

Create a physics simulation.

Parameters

gravity Acceleration of bodies in the simulation due to gravity

This function should be called by scenes that require a physics simulation

See also: physics

◆ emit()

void ime::Object::emit ( const std::string & event )

protectedinherited

Dispatch an action event.

Parameters

event The name of the event to be dispatched

This function will invoke all event listeners of the specified event. The function should be used for events that represent an action, rather than those that represent a property change (Use emitChange for that)

See also: emitChange

◆ emitChange()

void ime::Object::emitChange ( const Property & property )

protectedinherited

Dispatch a property change event.

Parameters

property The property that changed

This function will invoke all the event listeners of the specified property

See also: emit

◆ engine()

Engine& ime::Scene::engine ( ) const

protected

Get a reference to the game engine.

Returns: A reference to the game engine

Warning: Do not keep the returned reference

◆ eventEmitter()

EventEmitter& ime::Scene::eventEmitter ( )

protected

Get the scenes event event emitter.

Returns: The scenes event event emitter

The event emitter is local to the scene instance. This means that events registered on it are only dispatched when the scene is active and de-registered when the scene is destroyed. For global events use the global event event emitter in the Engine class or the EventDispatcher

Warning: Do not keep the returned reference

◆ fixedUpdate()

virtual void ime::Scene::fixedUpdate ( Time deltaTime )

inlinevirtual

Update the scene in fixed time steps.

Parameters

deltaTime Time passed since last update

This function will be called by the game engine after the scene has handled system events and external inputs (Keyboard and mouse). The function may be called once per frame, multiple times per frame or not called at all. The delta passed to it is always the same and is independent of the games frame rate. The delta time is always 1.0f / FPS_LIMIT, where FPS_LIMIT is the games Frames Per Second limit

Updates that are frame-rate independent must be in this function. Note that implementing this function is optional and must be overridden if needed. IME will never put anything inside this function, therefore you don't have to call the base class method in your implementation

See also: update

Definition at line 180 of file Scene.h.

◆ gameObjects()

GameObjectContainer& ime::Scene::gameObjects ( )

protected

Get the scene game object container.

Returns: The scene game object container

This class stores game objects that belong to this scene

Warning: Do not keep the returned reference

◆ getClassName()

std::string ime::Scene::getClassName ( ) const

overridevirtual

Get the name of the scene.

Returns: The name of the scene

Implements ime::Object.

◆ getClassType()

virtual std::string ime::Object::getClassType ( ) const

virtualinherited

Get the name of the direct parent of an object instance.

Returns: The name of the direct parent of an object instance

In contrast to getClassName which returns the name of the concrete class, this function returns the name of the concrete class's base class. This function is implemented by all derived classes of Object which also serve as base classes for other Objects. For classes whose direct parent is this class, this function will return the name of this class

auto rectangle = ime::RectangleShape(); // RectangleShape is derived from Shape
std::cout << rectangle->getClassName(); // Prints "RectangleShape"
std::cout << rectangle->getClassType(); // Prints "Shape"

See also: getClassName

Reimplemented in ime::SpriteImage, ime::Shape, ime::Drawable, ime::GridMover, ime::Joint, ime::Collider, and ime::GameObject.

◆ getObjectId()

unsigned int ime::Object::getObjectId ( ) const

inherited

Get the id of the object.

Returns: The id of the object

Each object has a unique id

◆ getTag()

const std::string& ime::Object::getTag ( ) const

inherited

Get the alias of the object.

Returns: The alias of the object

See also: setTag and getObjectId

◆ getTimescale()

float ime::Scene::getTimescale ( ) const

protected

Get the scenes timescale.

Returns: The scenes timescale

◆ globalEventEmitter()

EventDispatcher& ime::Scene::globalEventEmitter ( )

protected

Get the global event emitter.

Returns: The global event emitter

The global event emitter is available to anything that needs it (a class, function etc...). Events registered to it are always dispatched regardless of the active scene. As a result you must remove event listeners that are local to the scene when the scene is destroyed. For example, a lambda that captures "this" will result in undefined behavior if not removed after the scene is destroyed

Warning: Always remove local event listeners

◆ gridMovers()

GridMoverContainer& ime::Scene::gridMovers ( )

protected

Get the scenes grid mover container.

Returns: The scenes grid mover container

Note that you can use this container to store a GridMover or you can use your own container. The advantage of using this container is that the grid mover is updated on your behalf

◆ gui()

ui::GuiContainer& ime::Scene::gui ( )

protected

Get the scene gui container.

Returns: The scene gui container

The gui container is provided here for convenience, you can manually instantiate as many gui containers as you desire. Note that the gui does not belong to any render layer and is always rendered on top

◆ handleEvent()

virtual void ime::Scene::handleEvent ( Event event )

inlinevirtual

Handle a system event.

Parameters

event System event to be handled

This function will be called by the game engine before the scene is updated. Override this function if you want to handle a window specific events such as window resize event. Do not use it to handle input related events. Use the scenes input manager or the global input manager found in the Engine. The function is called once per frame

Note that IME will never put anything inside this function, therefore you don't have to call the base class method in your implementation

Definition at line 138 of file Scene.h.

◆ input()

input::InputManager& ime::Scene::input ( )

protected

Get the scenes input manager.

Returns: The scenes input manager

The input manager is local to the scene instance. This means that input listeners registered on it are only invoked when the scene is active and de-registered when the scene is destroyed To register global inputs, use the global input manager in the Engine class

Warning: Do not keep the returned reference; Do not try to update the input manager, it will be updated internally

◆ isEntered()

bool ime::Scene::isEntered ( ) const

Check if the scene has been entered or not.

Returns: True if the scene has been entered, otherwise false

See also: onEnter

◆ isVisibleOnPause()

bool ime::Scene::isVisibleOnPause ( ) const

Check if the scene is visible when paused or not.

Returns: True if visible, otherwise false

See also: setVisibleOnPause

◆ onDestruction()

int ime::Object::onDestruction ( const Callback<> & callback )

inherited

Add a destruction listener.

Parameters

callback Function to be executed when the object is destroyed

Returns: The id of the destruction listener

Note that an object may have more than one destruction listeners, however, you have to keep the returned id if you may want to remove the callback at a later time

Warning: The callback is called when the object is destroyed. Do not try to access the object in the callback. Doing so is undefined behavior

See also: removeDestructionListener

◆ onEnter()

virtual void ime::Scene::onEnter ( )

pure virtual

Enter the scene.

This function will be called by the game engine when the scene is entered for the first time. Note that a scene cannot be entered more than once, in other words this function will only be called once

◆ onEvent()

int ime::Object::onEvent	(	const std::string &	event,
		const Callback<> &	callback
	)

inherited

Add an event listener to an event.

Parameters

event	The name of the event to add an an event listener to
callback	The function to be executed when the event takes place

Returns: The unique identification number of the event listener

Unlike onPropertyChange, this function registers event listeners to events that occur when something happens to the object, or when the object does something (action events). Usually the name of the event/action is the name of the function:

// Add event listeners to the object
object.onEvent("attachRigidBody", [] {
    std::cout << "Rigid body attached to object << std::endl;
});
 
object.onEvent("removeRigidBody", [] {
    std::cout << "Rigid body removed from object << std::endl;
});
 
// Invokes event listener(s)
object.attachRigidBody(body);
object.removeRigidBody();

See also: onPropertyChange and unsubscribe

◆ onExit()

virtual void ime::Scene::onExit ( )

inlinevirtual

Exit a scene.

This function will be called by the game engine before the scene is removed from the game. The function is optional and may be overridden if you want to perform cleanup or something before the scene is destroyed

Note that implementing this function is optional and must be overridden if you want to do something when the scene is resumed. IME will never put anything inside this function. therefore you don't have to call the base class method in your implementation

Warning: This function is not a replacement for the destructor, it will be called first, then the destructor immediately after

Definition at line 245 of file Scene.h.

◆ onPause()

virtual void ime::Scene::onPause ( )

inlinevirtual

Pause the scene.

This function will be called by the game engine if another scene is pushed while this scene is active

Note that implementing this function is optional and must be overridden if you want to do something when the scene is paused. IME will never put anything inside this function, therefore you don't have to call the base class method in your implementation

See also: onResume

Definition at line 211 of file Scene.h.

◆ onPropertyChange() [1/2]

void ime::Object::onPropertyChange ( const Callback< Property > & callback )

inherited

Add an event listener to a property change event.

Parameters

callback The function to be executed when the property changes

Returns: The unique id of the event listener

Note that only one callback function may be registered with this function. This means that adding a new event listener overwrites the previous event listener. To remove the callback, pass a nullptr as an argument. The function may be useful if you want to write the logic for property changes in one function.

See also: onPropertyChange(std::string, Callback)

◆ onPropertyChange() [2/2]

int ime::Object::onPropertyChange	(	const std::string &	property,
		const Callback< Property > &	callback
	)

inherited

Add an event listener to a specific property change event.

Parameters

property	The name of the property to listen for
callback	The function to be executed when the property changes

Returns: The unique id of the event listener

A property change event is triggered by any function that begins with set, where the the text after set is the name of the property. For example, for the setTag function, the property that the function modifies is Tag.

Note that when adding a property change event listener, the name of the property must be in lowercase:

// Prints the tag of the player object to the console everytime it changes
player.onPropertyChange("tag", [](const Property& property) {
     cout << "New tag: " <<  property.getValue<std::string>() << endl;
});
 
...
//Sets tag = "player1" and invokes event listener(s)
player.setTag("player1");

Unlike onPropertyChange(const Callback&) you can add multiple event listeners to the same property using this function. However you must store the unique id of the event listener if you wish to remove it at a later time

See also: unsubscribe and onPropertyChange(Callback)

◆ onResume()

virtual void ime::Scene::onResume ( )

inlinevirtual

Resume scene.

This function will be called by the game engine when the current active scene is removed and this scene was paused

Note that implementing this function is optional and must be overridden if you want to do something when the scene is resumed. IME will never put anything inside this function, therefore you don't have to call the base class method in your implementation

See also: onPause

Definition at line 227 of file Scene.h.

◆ operator!=()

bool ime::Object::operator!= ( const Object & rhs ) const

inherited

Check if two objects are not the same object.

Parameters

rhs	Object to compare against this object

Returns: True if rhs is NOT the same object as this object, otherwise false

Two objects are different from each other if they have different object id's

See also: getObjectId and operator==

◆ operator=()

Scene& ime::Scene::operator= ( Scene && )

noexcept

Move assignment operator.

◆ operator==()

bool ime::Object::operator== ( const Object & rhs ) const

inherited

Check if two objects are the same object or not.

Parameters

rhs	Object to compare against this object

Returns: True if rhs is the same object as this object, otherwise false

Two objects are the same object if they have the same object id. Recall that each object instance has a unique id

See also: getObjectId and operator!=

◆ physics()

World& ime::Scene::physics ( )

protected

Get the physics simulation.

Returns: The physics simulation

The physics simulation is responsible for creating, managing, colliding and updating all of the bodies within it.

Warning: The physics simulation must be created first before calling this function. Calling it before creating the simulation is undefined behaviour. In addition, do not attempt to update the simulation, it will be updated automatically by the scene; Do not keep the returned reference

See also: createWorld

◆ postUpdate()

virtual void ime::Scene::postUpdate ( Time deltaTime )

inlinevirtual

Post update the scene.

Parameters

deltaTime Time passed since last update

This function is called after fixed update and update but before the scene is rendered. It may be useful if you want to do something after all time updates (timer updates, physics updates, animation updates, gui updates etc...) have completed.

Note that implementing this function is optional and must be overridden if needed. IME will never put anything inside this function, therefore you don't have to call the base class method in your implementation

Definition at line 196 of file Scene.h.

◆ removeDestructionListener()

bool ime::Object::removeDestructionListener ( int id )

inherited

Remove a destruction listener form the object.

Parameters

The	id of the destruction listener to be removed

Returns: True if the destruction listener was removed or false if the listener with the given id does not exist

◆ renderLayers()

RenderLayerContainer& ime::Scene::renderLayers ( )

protected

Get the scene render layers.

Returns: The scene render layers

Render layers allow the scene to be rendered in separate layers which are then composed back together. By default the scene has a "default" layer at index 0. When a drawable object is added to the scene without an explicit layer, it will be added to the default layer. You can add objects to the "default" layer or even remove the "default" layer from the render layer container, however you mus not forget to reallocate the objects in the "default" layer to another layer, otherwise they will not be drawn to the screen

Note: When the scene contains a tilemap (createTilemap called), the scene uses the tilemap's render layers instead of its own. This means that drawables added using this function will not be rendered. Only use this function if the scene does not have a tilemap

◆ setTag()

void ime::Object::setTag ( const std::string & tag )

inherited

Assign the object an alias.

Parameters

name	The alias of the object

This function is useful if you want to refer to the object by tag instead of its id. Unlike an object id, multiple objects may have the same tag.

By default, the tag is an empty string

◆ setTimescale()

void ime::Scene::setTimescale ( float timescale )

protected

Set the scene timescale.

Parameters

timescale The new scene timescale

The timescale can be used to speed up or slow down the scene without changing the FPS limit. Values above 1.0f speed up the scene whilst values below 1.0f slow it down A timescale of zero freezes the scene.

Note: A scenes timescale affects everything that requires a time update. This includes timers, animations, dynamic bodies etc... For example, if the timescale is set to 2.0f, then scene timers will count twice as fast, animations will play twice as fast, dynamic bodies will move twice as fast etc..

By default the timescale is 1.0f (real-time)

◆ setVisibleOnPause()

void ime::Scene::setVisibleOnPause ( bool show )

protected

Set whether or not the scene is hidden or rendered when it is paused.

Parameters

True	to show or false to hide

When the scene is shown on pause, it is rendered behind the current active scene but it does not receive any events or updates. Note that the scene will only be rendered if it has been entered and it is the next scene (It is the scene that will run if the current one is popped)

By default the scene is hidden when it is paused

See also: onPause

◆ shapes()

ShapeContainer& ime::Scene::shapes ( )

protected

Get the scene geometry shape container.

Returns: The geometry shape container

You may use this class to create geometry shape instead of using their respective constructors. Consult the ShapeContainer class definition for more info

Warning: Do not keep the returned reference

◆ sprites()

SpriteContainer& ime::Scene::sprites ( )

protected

Get the scene sprite container.

Returns: The scene sprite container

This class stores the sprites in the scene. The sprite's animator will automatically be updated

◆ tilemap()

TileMap& ime::Scene::tilemap ( )

protected

Get the scene Tilemap.

Returns: The scene tilemap

Note that only one tilemap can be created per scene

Warning: The tilemap must be created before it is used. Calling this function before the tilemap is created is undefined behavior

See also: createTilemap

◆ timer()

TimerManager& ime::Scene::timer ( )

protected

Get the scenes timer manager.

Returns: The scenes timer manager

The timer manager is local to the scene instance. This means that callbacks scheduled on it will only be dispatched when the scene is active

Warning: Do not keep the returned reference; Do not try to update the timer manager, it will be updated internally

◆ unsubscribe()

bool ime::Object::unsubscribe	(	const std::string &	event,
		int	id
	)

inherited

Remove an event listener from an event.

Parameters

event	The name of the event to remove event listener from
id	The unique id of the event listener to be removed

Returns: True if the event listener was removed or false if the event or the event listener is does not exist

// Display the name of the object to console every time it changes
auto nameChangeId = object.onPropertyChange("name", [](Property name) {
     std::cout << name.getValue<std::string>() << std::endl;
});
 
// Stop displaying the name of the object when it changes
object.unsubscribe("name", id);

◆ update()

virtual void ime::Scene::update ( Time deltaTime )

inlinevirtual

Update the scene.

Parameters

deltaTime Time passed since last update

This function will be called by the game engine after the scene has handled system events and external inputs (Keyboard and mouse). The function is called once per frame and the delta passed to it is frame rate dependent. This means that it depends on how long the previous frame took to complete.

All updates that should be synced with the render fps must be in this function. Note that implementing this function is optional and must be overridden if needed. IME will never put anything inside this function, therefore you don't have to call the base class method in your implementation

See also: fixedUpdate

Definition at line 158 of file Scene.h.

Friends And Related Function Documentation

◆ SceneManager

friend class SceneManager

friend

Pre updates the scene.

Definition at line 601 of file Scene.h.

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

Scene.h

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Ptr

Constructor & Destructor Documentation

◆ Scene() [1/2]

◆ Scene() [2/2]

◆ ~Scene()

Member Function Documentation

◆ audio()

◆ cache()

◆ camera()

◆ createTilemap()

◆ createWorld()

◆ emit()

◆ emitChange()

◆ engine()

◆ eventEmitter()

◆ fixedUpdate()

◆ gameObjects()

◆ getClassName()

◆ getClassType()

◆ getObjectId()

◆ getTag()

◆ getTimescale()

◆ globalEventEmitter()

◆ gridMovers()

◆ gui()

◆ handleEvent()

◆ input()

◆ isEntered()

◆ isVisibleOnPause()

◆ onDestruction()

◆ onEnter()

◆ onEvent()

◆ onExit()

◆ onPause()

◆ onPropertyChange() [1/2]

◆ onPropertyChange() [2/2]

◆ onResume()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ physics()

◆ postUpdate()

◆ removeDestructionListener()

◆ renderLayers()

◆ setTag()

◆ setTimescale()

◆ setVisibleOnPause()

◆ shapes()

◆ sprites()

◆ tilemap()

◆ timer()

◆ unsubscribe()

◆ update()

Friends And Related Function Documentation

◆ SceneManager