Monarch Screen Manager for Defold

By default, screen navigation in Monarch is instant. You can add optional transitions to make navigation smoother. When a transition is defined for a screen, Monarch will wait for the transition to complete before proceeding with the navigation sequence.

Transitions are configured using monarch.on_transition(screen_id, fn). The callback function fn must accept (message_id, message, sender) as arguments. The message_id determines which type of transition to start:

• monarch.TRANSITION_SHOW_IN
• monarch.TRANSITION_SHOW_OUT
• monarch.TRANSITION_BACK_IN
• monarch.TRANSITION_BACK_OUT

Crucial: Once your transition animation is finished, you must send a monarch.TRANSITION_DONE message back to the sender to notify Monarch that it can continue the navigation.

monarch.on_transition("my_screen", function(message_id, message, sender)
    -- Start animation based on message_id
    -- ... animation logic ...
    -- When finished:
    sender.send(monarch.TRANSITION_DONE, { transition = message_id })
end)

Monarch provides a monarch.transitions.gui module to easily set up common transitions for GUI nodes. You can create a transition instance and chain methods to define how a screen enters, exits, or returns.

To apply transitions to a specific screen, use monarch.on_transition(screen_id, transition_instance).

Predefined transition types:

• slide_in_right, slide_in_left, slide_in_top, slide_in_bottom
• slide_out_right, slide_out_left, slide_out_top, slide_out_bottom
• scale_in, scale_out
• fade_in (alpha 0.0 -> 1.0)
• fade_out (alpha 1.0 -> 0.0)

Common transition sets:

• transitions.in_right_out_left(node, duration, [delay], [easing])
• transitions.in_left_out_right(node, duration, [delay], [easing])
• transitions.in_left_out_left(node, duration, [delay], [easing])
• transitions.in_right_out_right(node, duration, [delay], [easing])
• transitions.fade_in_out(node, duration, [delay], [easing])

local transitions = require "monarch.transitions.gui"
local monarch = require "monarch.monarch"

function init(self)
    local transition = transitions.create(gui.get_node("root"))
        .show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
        .show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
        .back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
        .back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)

    monarch.on_transition("foobar", transition)
end

Manage navigation history and stack state using the following methods:

• monarch.back([options], [data], [callback]): Goes back to a previous screen. Supports sequential (boolean) in options to wait for the current screen to transition out. Can pass data to the previous screen.
• monarch.clear([callback]): Clears the entire stack. Visible screens are hidden by navigating back out of them.
• monarch.top([offset]): Returns the screen_id (string|hash) at the top of the stack. Use a negative offset (e.g., -1) to get the previous screen.
• monarch.bottom([offset]): Returns the screen_id (string|hash) at the bottom of the stack. Use an offset to get a screen relative to the bottom.
• monarch.is_top(screen_id): Returns true if the specified screen is at the top of the stack.

-- Go back to the previous screen
monarch.back({ sequential = true }, { return_reason = "exit_menu" })

-- Get the current top screen
local current = monarch.top()

-- Clear everything
monarch.clear()

To avoid loading delays for heavy content, you can preload screens into memory without making them visible.

monarch.preload(screen_id, [options], [callback])

Loads a screen but does not enable it.

• options: keep_loaded (boolean) - If true, Monarch keeps the screen preloaded even after a hide() or back() event that would normally unload it.
• callback: Called when preloading is complete.

monarch.is_preloading(screen_id)

Returns true if the screen is currently preloading.

monarch.when_preloaded(screen_id, callback)

Registers a callback to be invoked once a specific screen has finished preloading.

monarch.unload(screen_id, [callback])

Manually unloads a preloaded screen. Preloaded screens are automatically unloaded when hidden, but this allows manual unloading without hiding.

-- Preload a heavy level screen
monarch.preload("level_1", { keep_loaded = true }, function()
    print("Level 1 is ready in background")
end)

-- Wait for preloading to finish
monarch.when_preloaded("level_1", function()
    monarch.show("level_1")
end)