The Scene class

The scene class wraps together game logic, asset loading draw calls & properties that all belong to one part of your game. A scene could be a menu screen, or a single game level, or a score board, or an intro video.

For an example on how to use the scene class in your game. See game.set_scene(scene)

Scene(name)

This is a constructor function used for creating new scenes. Use it like this:

local scene = Scene("My Scene")

The first argument is optional, and is the display name of the scene, not to be confused with scene which is the variable name.

Note

The examples below use scene... to demonstrate various techniques. However this assumes you have created a “scene” variable like the one above.

scene.name

This property lets you get or set an optional display name of the scene.

scene.on(event)

The on method allows you to subscribe to a named built-in or custom event. The built in events are really useful as these allow you to hook in and control scene game logic, drawing etc…

Here are some code examples for key events you should be aware of:

The init event

scene.on('init', function()
    -- do something here
end)

The init event is called when the scene is ready to start loading assets for your scene. It can only be fired once, and it’s called when game.set_scene is used, however you can also trigger the event manually by using [instance].trigger('init').

The shown event

scene.on('shown', function(dt)
    -- do something here
end)

As a scene can be shown more than once, an event called shown is made available to allow you to handle what happens when a specific scene is selected as the active one. If a previous scene was active, a hidden event is fired on the previous scene before hand.

The hidden event

scene.on('hidden', function(dt)
    -- do something here
end)

The scene system also provides an event to let a scene know it has lost focus. This event is called before the shown event.

The update event

scene.on('update', function(dt)
    -- do something here
end)

The update event is called to give your scene the opportunity to update game logic. This callback provides a dt argument which is a float representing the delta time since update was last called, useful for timing animations, or game logic.

The draw event

scene.on('draw', function()
        renderer.clear()
    renderer.begin()
    -- do something here
    renderer.present()
end)

The draw event is called to give your scene the opportunity to draw graphics specific to the scene.

scene.trigger(event)

Trigger allows you to trigger custom events throughout your code. These events can be handled by the on method shown above. To trigger an event, simply write something like this:

scene.trigger('my_custom_event')

The first argument is the name of the event to trigger. The base trigger method does not support passing additional arguments.