Organizing Screens and Popups with Monarch

Prerequisite: Verify Monarch Dependency

Before applying any guidance from this skill, you MUST confirm that the project actually uses Monarch. Check the game.project file in the project root for a dependency URL containing britzl/monarch (e.g. dependencies#N = https://github.com/britzl/monarch/archive/...). Alternatively, check for the presence of a monarch/monarch.lua file in the project tree.

If neither a Monarch dependency in game.project nor a local monarch/monarch.lua module is found, do NOT apply this skill. Inform the user that the project does not appear to use Monarch and suggest adding the dependency to game.project if they want to use it:

[project]
dependencies#N = https://github.com/britzl/monarch/archive/refs/tags/5.2.0.zip

---

This skill describes the conventions for creating and managing screens (via collectionproxy) and popups (via collectionfactory) in a Defold project using the Monarch library.

Naming Rules

• All screen and popup names use snake_case.
• Screen and popup names MUST be unique across the entire project because Monarch registers them in a single shared registry (screens table in monarch.lua). Duplicate ids cause an assertion error.
• Recommended pattern: prefix popup names distinctly (e.g. settings_popup, reward_popup) so they never collide with screen names (e.g. main_menu, gameplay).

Directory Layout

project/
├── main/
│   ├── main.collection          -- bootstrap collection (set in game.project [bootstrap])
│   └── main.script              -- main controller script: waits for registration, shows first screen
├── screens/
│   └── <screen_name>/
│       ├── <screen_name>.collection   -- IMPORTANT: collection name MUST be unique (see below)
│       ├── <screen_name>.gui
│       └── <screen_name>.gui_script
├── popups/
│   └── <popup_name>/
│       ├── <popup_name>.collection
│       ├── <popup_name>.gui
│       └── <popup_name>.gui_script

Creating a Screen (collectionproxy)

A screen is a full-screen view loaded via collectionproxy. Only ONE screen should be active at a time. When switching screens, always use { clear = true } to avoid stacking multiple screens.

Required files for a screen (e.g. gameplay)

1. screens/gameplay/gameplay.collection

• The collection name property MUST be unique across the project (Defold uses it for URL addressing within the loaded world).
• Contains a game object with a camera component.

name: "gameplay"
scale_along_z: 0
embedded_instances {
  id: "camera"
  data: "embedded_components {\n"
  "  id: \"camera\"\n"
  "  type: \"camera\"\n"
  "  data: \"aspect_ratio: 1.0\\n"
  "fov: 0.7854\\n"
  "near_z: -1.0\\n"
  "far_z: 1.0\\n"
  "orthographic_projection: 1\\n"
  "orthographic_mode: ORTHO_MODE_AUTO_COVER\\n"
  "\"\n"
  "}\n"
  ""
}

Registering a screen in main.collection

In main.collection, for each screen create a game object (e.g. id gameplay) with:

1. A component screen_proxy referencing /monarch/screen_proxy.script with properties:
   • screen_id = gameplay (hash, must match the id you use in monarch.show())
   • popup = false
   • popup_on_popup = false
2. An embedded component collectionproxy of type collectionproxy pointing to /screens/gameplay/gameplay.collection.

The screen_proxy.script will call monarch.register_proxy() in its init(), registering the screen automatically.

Showing a screen (single-screen stack pattern)

ALWAYS use { clear = true } when showing a screen so the stack is cleared down to any existing instance and then replaced. This ensures only 1 screen is ever in the stack:

monarch.show("gameplay", { clear = true })

Do NOT call monarch.show("gameplay") without clear = true for screens -- that would push onto the stack and create confusing multi-screen stacks.

To navigate between screens:

-- from main_menu to gameplay:
monarch.show("gameplay", { clear = true })

-- from gameplay to main_menu:
monarch.show("main_menu", { clear = true })

Do NOT use monarch.back() for screen-to-screen navigation. back() is for closing popups.

Creating a Popup (collectionfactory)

A popup is an overlay that pauses/dims screens beneath it. Popups are created via collectionfactory so multiple popup instances can coexist (popup on popup).

Required files for a popup (e.g. settings_popup)

1. popups/settings_popup/settings_popup.collection

• Contains a game object with a referenced GUI component.

name: "settings_popup"
scale_along_z: 0
embedded_instances {
  id: "go"
  data: "components {\n"
  "  id: \"gui\"\n"
  "  component: \"/popups/settings_popup/settings_popup.gui\"\n"
  "}\n"
  ""
}

2. popups/settings_popup/settings_popup.gui

• Standard Defold GUI file with the popup's UI nodes.

3. popups/settings_popup/settings_popup.gui_script

• To close itself, call monarch.back().

local monarch = require("monarch.monarch")

function init(self)
end

function final(self)
end

function on_message(self, message_id, message, sender)
end

function on_input(self, action_id, action)
    if action_id == hash("touch") and action.pressed then
        -- example: close popup on a button press
        -- (check node picking for your close button here)
        monarch.back()
    end
end

Registering a popup in main.collection

In main.collection, for each popup create a game object (e.g. id settings_popup) with:

1. A component screen_factory referencing /monarch/screen_factory.script with properties:
   • screen_id = settings_popup (hash)
   • popup = true
   • popup_on_popup = true (set to true if this popup can appear on top of another popup)
   • screen_factory = URL to the collectionfactory component (see step 2)
2. An embedded component collectionfactory of type collectionfactory pointing to /popups/settings_popup/settings_popup.collection.

The screen_factory.script will call monarch.register_factory() in its init(), registering the popup automatically.

Showing and closing a popup

-- Open a popup (it stacks on top of the current screen):
monarch.show("settings_popup")

-- Open a popup on top of another popup (requires popup_on_popup = true):
monarch.show("confirm_popup")

-- Close the topmost popup:
monarch.back()

Popup timestep behavior

When a popup is shown on top of a screen, Monarch automatically sets timestep_below_popup on the underlying screen's proxy. The default value is 1 (normal speed). Set it to 0 in the screen's screen_proxy.script properties to pause the screen beneath a popup:

• timestep_below_popup = 0

Waiting for All Screens to Register Before Starting

Do NOT call monarch.show() directly in init() of main.script -- at that point other scripts' init() has not yet run and screens are not registered. This causes an assertion error.

The solution: post a message to self from init(). By the time the message is processed, all init() functions in the collection have completed and all screens/popups are registered.

Example: main/main.script

local monarch = require("monarch.monarch")

function init(self)
    msg.post(".", "acquire_input_focus")
    msg.post("#", "start")
end

function on_message(self, message_id, message, sender)
    if message_id == hash("start") then
        monarch.show("main_menu", { clear = true })
    end
end

Quick Reference

Action	Code
Show a screen (clear stack)	monarch.show("screen_name", { clear = true })
Show a popup	monarch.show("popup_name")
Close topmost popup	monarch.back()
Check screen registered	monarch.screen_exists("screen_name")
Check if busy (transitioning)	monarch.is_busy()
Get screen data	monarch.data("screen_name")
Pass data to screen	monarch.show("screen_name", { clear = true }, { key = "value" })
Pass data to popup	monarch.show("popup_name", nil, { key = "value" })
Check if popup	monarch.is_popup("popup_name")
Get current top screen	monarch.top()