Example

Note: These examples use the LOVE2D framework, but they should work for any Lua-based program.

Setup:

Start by downloading this file and requiring it inside your main program file (usually main.lua). Then add custom event triggers to each area you'd like to use within your scenes. I've included some common events below, but you can trigger events anywhere within your program.

You will also need to load and register your scenes with Scene Man. You can also pass values into the load method, which will be passed into each scene that you register.

Finally, you must push or insert a scene onto the stack to get everything started. In this example, I've pushed two scenes onto the stack, which we will define in just a moment.

--- main.lua

local sceneMan = require ("sceneMan")

function love.load ()
    local initialRectW = 300 -- Initial size of the gameplay rectangle

    sceneMan:newScene ("game", require ("gameScene"), initialRectW) -- Here we pass the initial rectangle width into the scene
    sceneMan:newScene ("menu", require ("menuScene")) -- This scene doesn't need any extra values, so we don't pass anything
    
    
-- This is where the fun begins!
    sceneMan:push ("game")
    sceneMan:push ("menu")
end


function love.update (dt)
    -- We pass dt from love.update into each scene
    sceneMan:event ("update", dt)
end


function love.draw ()
    local rng = math.random ()
    
    -- We can pass any values we desire into these events
    sceneMan:event ("draw", rng)
end


function love.keypressed (key)
    -- The event name can also be anything we want, so long as we use the same name inside the scenes we define
    sceneMan:event ("key", key)
end

Defining scenes:

Before we can run our game, we must define the behavior for each of our scenes. Start by creating a new file for each scene (the blank scene file may be helpful to you). After that, you should add all the event callbacks that your scene should support. Several callbacks are sent by Scene Man (load, delete, whenAdded, and whenRemoved), while others are custom callbacks sent by your program (update, draw, and key).

Let's define a scene that will contain our gameplay logic. This example will draw a rectangle on the screen and print to the console when you push a key.

--- gameScene.lua

-- Contains the scene, its callback functions, and its attribtue
local thisScene = {}

-- Declares variables that will be initialized when the scene is first loaded
-- Make sure you declare them up here so the other callback functions have access to them!
local sceneMan, rectW

function thisScene:load (...)
    -- Scene Man is always the first item in the vararg (...)
    sceneMan, rectW = ...
end

function thisScene:delete ()
    print ("Help! I've been deleted from memory!")
end

function thisScene:whenAdded ()
    print ("I have been added to the stack!")
end

function thisScene:whenRemoved ()
    print ("I was banished from the stack...")
end

function thisScene:update (dt)
    -- We won't be using dt in this scene
end

function thisScene:draw (rng)
    love.graphics.setColor (1, 1, 1, 1)
    love.graphics.rectangle ("fill", 100, 100, rectW * rng, 100) -- Draws a rectangle of a random size

    sceneMan.shared.rngValue = rng -- Saves a value to the table shared between all the scenes
end

function thisScene:key (key)
    print ("Hey! This key was just pressed: " .. key)
end

return thisScene

Let's also define a scene that will contain some GUI stuff. This example will simply print some data to the screen and pop itself off the scene stack when you push the “r” key.

--- menuScene.lua

-- Contains the scene, its callback functions, and its attribtue
local thisScene = {}

-- Declares variables that will be initialized when the scene is first loaded
-- Make sure you declare them up here so the other callback functions have access to them!
local sceneMan

local dt = 0

function thisScene:load (...)
    -- Scene Man is always the first item in the vararg (...)
    sceneMan = ...
end

function thisScene:delete ()
    print ("Help! I've been deleted from memory too!")
end

function thisScene:whenAdded ()
    print ("I have also been added to the stack!")
end

function thisScene:whenRemoved ()
    print ("I too was banished from the stack...")
end

function thisScene:update (dt)
    dt = dt -- Saves delta time to a local variable so it can be used inside the draw callback
end

function thisScene:draw (rng)
    -- Renders some GUI items
    love.graphics.setColor (1, 1, 1, 1)
    love.graphics.print ("Hello world! This is a GUI!", 400, 400)
    love.graphics.print ("Delta Time: " .. dt, 400, 425)
    love.graphics.print ("RNG: " .. sceneMan.shared.rngValue, 400, 450)
end

function thisScene:key (key)
    -- Pops a scene from the stack when R is pressed
    if key == "r" then
        print ("I'm getting removed from the stack now...")
        sceneMan:pop ()
    end
end

return thisScene

Result:

This will produce a small “game” with a rectangle that will constantly change its size and a simple GUI.

When we push the R key, the topmost scene (in this case, menuScene.lua) is removed from the stack. We know this works because the GUI has stopped rendering.