Ubiquitousse

• Index

Contents

• Scene objects
• Module

Modules

• ubiquitousse
• asset
• ecs
• input
• ldtk
• scene
• signal
• timer
• util

Topics

• README
• LICENSE

Module scene

Scene management for Lua game development.

You can use use scenes to seperate the different states of your game: for example, a menu scene and a game scene. This module is fully implemented in Ubiquitousse and is mostly a “recommended way” of organising an Ubiquitousse-based game. However, you don’t have to use this if you don’t want to. ubiquitousse.scene handles all the differents Ubiquitousse-states and make them scene-independent, for example by creating a scene-specific TimerRegistry (TimedFunctions that are keept accross states are generally a bad idea). Theses scene-specific states should be created and available in the table returned by ubiquitousse.scene.new.

The expected code-organisation is:

• each scene is in a file, identified by its module name (scenes will be loaded using require(“modulename”))
• each scene file create a new scene table using ubiquitousse.scene.new and returns it at the end of the file

Order of callbacks:

• all scene change callbacks are called after setting scene.current to the new scene but before changing scene.stack
• all scene exit/suspend callbacks are called before scene enter/resume callbacks

No mendatory dependency. Optional dependencies:

• ubiquitousse.timer (to provide each scene a timer registry).
• ubiquitousse.signal (to bind to update and draw signal in signal.event).

Usage:

TODO

Scene objects

Scene.name	The scene name.
Scene.timer	Scene-specific timer.TimerRegistry, if uqt.time is available.
Scene.signal	Scene-specific signal.SignalRegistry, if uqt.signal is available.
Scene:enter (...) [callback]	Called when entering a scene.
Scene:exit () [callback]	Called when exiting a scene, and not expecting to come back (scene may be unloaded).
Scene:suspend () [callback]	Called when suspending a scene, and expecting to come back (scene won’t be unloaded).
Scene:resume () [callback]	Called when resuming a suspended scene (after calling suspend).
Scene:update (dt, ...) [callback]	Called on each update on the current scene.
Scene:draw (...) [callback]	Called on each draw on the current scene.

Module

current	The current Scene object.
timer	Shortcut for scene.current.timer, the current scene timer.TimerRegistry.
signal	Shortcut for scene.current.signal, the current scene timer.SignalRegistry.
stack	The scene stack: list of scene, from the farest one to the nearest.
prefix	A prefix for scene modules names.
new ([name="unamed"])	Creates and returns a new Scene object.
switch (scenePath, ...)	Switch to a new scene.
push (scenePath, ...)	Push a new scene to the scene stack.
pop ()	Pop the current scene from the scene stack.
popAll ()	Pop all scenes.
update (dt, ...)	Update the current scene.
draw (...)	Draw the current scene.

Scene objects

Scene.name

The scene name.

Type:

string

Scene.timer

Scene-specific timer.TimerRegistry, if uqt.time is available.

Type:

• TimerRegistry
• nil if uqt.time unavailable

Scene.signal

Scene-specific signal.SignalRegistry, if uqt.signal is available.

Type:

• SignalRegistry
• nil if uqt.signal unavailable

Scene:enter (...) ^[callback]

Called when entering a scene.

Parameters:

• ... additional arguments passed to scene:switch or scene:push

Scene:exit () ^[callback]

Called when exiting a scene, and not expecting to come back (scene may be unloaded).

Scene:suspend () ^[callback]

Called when suspending a scene, and expecting to come back (scene won’t be unloaded).

Scene:resume () ^[callback]

Called when resuming a suspended scene (after calling suspend).

Scene:update (dt, ...) ^[callback]

Called on each update on the current scene.

Parameters:

• dt number the delta time
• ... additional arguments passed to scene:update

Scene:draw (...) ^[callback]

Called on each draw on the current scene.

Parameters:

• ... additional arguments passed to scene:draw

Module

current

The current Scene object.

Type:

Scene

timer

Shortcut for scene.current.timer, the current scene timer.TimerRegistry.

Type:

• TimerRegistry
• nil if uqt.time unavailable

signal

Shortcut for scene.current.signal, the current scene timer.SignalRegistry.

Type:

• SignalRegistry
• nil if uqt.signal unavailable

stack

The scene stack: list of scene, from the farest one to the nearest.

Type:

{Scene,...}

prefix

A prefix for scene modules names. Will search in the “scene” directory by default (prefix="scene."). Redefine it to fit your own ridiculous filesystem.

Type:

string

new ([name="unamed"])

Creates and returns a new Scene object.

Parameters:

• name string the new scene name (default "unamed")

Returns:

Scene

switch (scenePath, ...)

Switch to a new scene. The new scene will be required() and the current scene will be replaced by the new one, then the previous scene exit function will be called, then the enter callback is called on the new scence. Then the stack is changed to replace the old scene with the new one.

Parameters:

• scenePath string/table the new scene module name, or the scene table directly
• ... arguments to pass to the scene’s enter function

push (scenePath, ...)

Push a new scene to the scene stack. Similar to ubiquitousse.scene.switch, except suspend is called on the current scene instead of exit, and the current scene is not replaced: when the new scene call ubiquitousse.scene.pop, the old scene will be reused.

Parameters:

• scenePath string/table the new scene module name, or the scene table directly
• ... arguments to pass to the scene’s enter function

pop ()

Pop the current scene from the scene stack. The previous scene will be set as the current scene, then the current scene exit function will be called, then the previous scene resume function will be called, and then the current scene will be removed from the stack.

popAll ()

Pop all scenes.

update (dt, ...)

Update the current scene. Should be called at every game update. If ubiquitousse.signal is available, will be bound to the “update” signal in signal.event.

Parameters:

• dt number the delta-time
• ... arguments to pass to the scene’s update function after dt

draw (...)

Draw the current scene. Should be called every time the game is draw. If ubiquitousse.signal is available, will be bound to the “draw” signal in signal.event.

Parameters:

• ... arguments to pass to the scene’s draw function