{"id":15722644,"url":"https://github.com/britzl/monarch","last_synced_at":"2026-04-23T23:05:49.978Z","repository":{"id":42618297,"uuid":"102347067","full_name":"britzl/monarch","owner":"britzl","description":"Monarch is a Defold screen manager with transition support and a straight forward API","archived":false,"fork":false,"pushed_at":"2024-09-27T06:58:51.000Z","size":2230,"stargazers_count":177,"open_issues_count":4,"forks_count":27,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-04T09:26:33.416Z","etag":null,"topics":["defold","defold-library"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/britzl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-04T10:00:39.000Z","updated_at":"2025-04-03T03:55:54.000Z","dependencies_parsed_at":"2024-01-30T11:26:13.784Z","dependency_job_id":"d8ced3f3-e51a-4d2c-bd15-4b701e9e8ead","html_url":"https://github.com/britzl/monarch","commit_stats":null,"previous_names":[],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fmonarch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fmonarch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fmonarch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/britzl%2Fmonarch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/britzl","download_url":"https://codeload.github.com/britzl/monarch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767237,"owners_count":20992548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["defold","defold-library"],"created_at":"2024-10-03T22:08:45.391Z","updated_at":"2026-04-23T23:05:42.885Z","avatar_url":"https://github.com/britzl.png","language":"Lua","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![](docs/logo.jpg)\n\n[![Build Status](https://travis-ci.com/britzl/monarch.svg?branch=master)](https://travis-ci.org/britzl/monarch)\n[![Code Coverage](https://codecov.io/gh/britzl/monarch/branch/master/graph/badge.svg)](https://codecov.io/gh/britzl/monarch)\n[![Latest Release](https://img.shields.io/github/release/britzl/monarch.svg)](https://github.com/britzl/monarch/releases)\n\n# Monarch\nMonarch is a screen manager for the [Defold](https://www.defold.com) game engine.\n\n\n# Installation\nYou can use Monarch in your own project by adding this project as a [Defold library dependency](http://www.defold.com/manuals/libraries/). Open your game.project file and in the dependencies field under project add:\n\nhttps://github.com/britzl/monarch/archive/master.zip\n\nOr point to the ZIP file of a [specific release](https://github.com/britzl/monarch/releases).\n\n\n# Usage\nUsing Monarch requires that screens are created in a certain way. Once you have one or more screens created you can start navigating between the screens.\n\n## Editor Script\nRight click in on a`.gui` file in the outline and selected the menu item, it creates a `.collection` and a `.gui_script` with the same name as the `.gui` file. It adds the file with some basic setup done to them, adding the selected gui script to the created gui scene and in turns adds the gui scene to the newly created collection.\n\n\u003cimg src=\"/docs/editor_script.gif\" width=\"200px\"\u003e\n\n## Creating screens\nMonarch screens are created in individual collections and either loaded through collection proxies or created through collection factories.\n\n### Collection proxies\nFor proxies the recommended setup is to create one game object per screen and per game object attach a collection proxy component and an instance of the `screen_proxy.script` provided by Monarch. The `screen_proxy.script` will take care of the setup of the screen. All you need to do is to make sure that the script properties on the script are correct:\n\n* **Screen Proxy (url)** - The URL to the collection proxy component containing the actual screen. Defaults to `#collectionproxy`.\n* **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.\n* **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).\n* **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.\n* **Timestep below Popup (number)** - Timestep to set on screen proxy when it is below a popup. This is useful when pausing animations and gameplay while a popup is open.\n* **Screen Keeps Input Focus When Below Popup (boolean)** - Check this if the screen should keep input focus when it is below a popup.\n* **Others Keep Input Focus When Below Screen (boolean)** - Check this if other screens should keep input focus when below this screen.\n* **Transition Url (url)** - **DEPRECATED** Optional URL to post messages to when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).\n* **Focus Url (url)** - **DEPRECATED** Optional URL to post messages to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).\n* **Receiver Url (url)** - **DEPRECATED** Optional URL to post messages to using `monarch.post()`.\n* **Preload (boolean)** - Check this if the screen should be preloaded and kept loaded at all times. For a collection proxy it means that it will be async loaded but not enabled at all times while not visible. This can also temporarily be achieved through the `monarch.preload()` function.\n\n![](docs/setup_proxy.png)\n\n### Collection factories\nFor factories the recommended setup is to create one game object per screen and per game object attach a collection factory component and an instance of the `screen_factory.script` provided by Monarch. The `screen_factory.script` will take care of the setup of the screen. All you need to do is to make sure that the script properties on the script are correct:\n\n* **Screen Factory (url)** - The URL to the collection factory component containing the actual screen. Defaults to `#collectionfactory`.\n* **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.\n* **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).\n* **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.\n* **Screen Keeps Input Focus When Below Popup (boolean)** - Check this if the screen should keep input focus when it is below a popup.\n* **Others Keep Input Focus When Below Screen (boolean)** - Check this if other screens should keep input focus when below this screen.\n* **Transition Id (hash)** - **DEPRECATED** Optional id of the game object to send a message to when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).\n* **Focus Id (hash)** - **DEPRECATED** Optional id of the game object to send a message to when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).\n* **Preload (boolean)** - Check this if the screen should be preloaded and kept loaded at all times. For a collection factory this means that its resources will be dynamically loaded at all times. This can also temporarily be achieved through the `monarch.preload()` function.\n\n![](docs/setup_factory.png)\n\nNote: Monarch supports dynamic collection factories (ie where the \"Load Dynamically\" checkbox is checked).\n\n## Nesting screens\nSometimes it might be desirable to have a screen that contains one or more sub-screens or children, for instance popups that are used only by that screen. Monarch supports nested screens only when the parent screen is created via a collection factory. If the parent screen is loaded via a collection proxy the sub/child-screens won't be able to receive any input.\n\n## Navigating between screens\nThe navigation in Monarch is based around a stack of screens. When a screen is shown it is pushed to the top of the stack. When going back to a previous screen the topmost screen on the stack is removed. Example:\n\n* Showing screen A\n* Stack is `[A]`\n* Showing screen B\n* Stack is `[A, B]` - (B is on top)\n* Going back\n* Stack is `[A]`\n\n### Showing a new screen\nYou show a screen in one of two ways:\n\n1. Post a `show` message to the screen script (either `screen_proxy.script` or `screen_factory.script`)\n2. Call `monarch.show()` (see below)\n\nShowing a screen will push it to the top of the stack and trigger an optional transition. The previous screen will be hidden (with an optional transition) unless the screen to be shown is a [popup](#popups).\n\nNOTE: You must ensure that the `init()` function of the screen script (either `screen_proxy.script` or `screen_factory.script`) has run. The `init()` function is responsible for registering the screen and it's not possible to show it until this has happened. A good practice is to delay the first call by posting a message to a controller script or similar before calling `monarch.show()` the first time:\n\n\tfunction init(self)\n\t\tmsg.post(\"#\", \"show_first_screen\")\n\tend\n\n\tfunction on_message(self, message_id, message, sender)\n\t\tmonarch.show(hash(\"first_screen\"))\n\tend\n\n#### Preventing duplicates in the stack\nYou can pass an optional `clear` flag when showing a screen (either as a key value pair in the options table when calling `monarch.show()` or in the message). If the clear flag is set Monarch will search the stack for the screen in question. If the screen already exists in the stack and the `clear` flag is set Monarch will remove all screens between the current top and the screen in question. Example:\n\n* Stack is `[A, B, C, D]` - (D is on top)\n* A call to `monarch.show(B, { clear = true })` is made\n* Stack is `[A, B]`\n\nAs opposed to if the `clear` flag was not set:\n\n* Stack is `[A, B, C, D]` - (D is on top)\n* A call to `monarch.show(B, { clear = false })` is made\n* Stack is `[A, B, C, D, B]` - (B is on top)\n\n#### Showing a screen without adding it to the stack\nMonarch can also show a screen without adding it to the stack. This can be used to for instance load a collection containing a background that you want to have visible at all times. You show and hide such a screen like this:\n\n\t-- show the background without adding it to the stack\n\tmonarch.show(hash(\"background\"), { no_stack = true })\n\n\t-- hide the background\n\tmonarch.hide(hash(\"background\"))\n\n### Going back to a previous screen\nYou navigate back in the screen hierarchy in one of two ways:\n\n1. Post a `back` message to the screen script (either `screen_proxy.script` or `screen_factory.script`)\n2. Call `monarch.back()` (see below)\n\n\n## Input focus\nMonarch will acquire and release input focus on the game objects containing the proxies to the screens and ensure that only the top-most screen will ever have input focus. The screen settings above provide a `Screen Keeps Input Focus When Below Popup` and `Others Keep Input Focus When Below Screen` setting to override this behavior so that a screen can continue to have focus. This is useful when you have for instance a tabbed popup where the tabs are in a root screen and the content of the individual tabs are separate screens. In this case you want the tabs to have input as well as the tab content.\n\n\n## Popups\nA screen that is flagged as a popup (see [list of screen properties](#creating-screens) above) will be treated slightly differently when it comes to navigation.\n\n### Popup on normal screen\nIf a popup is shown on top of a non-popup the current top screen will not be unloaded and instead remain visible in the background:\n\n* Stack is `[A, B]`\n* A call to `monarch.show(C)` is made and C is a popup\n* Stack is `[A, B, C]` and B will still be visible\n\n### Popup on popup\nIf a popup is at the top of the stack and another popup is shown the behavior will depend on if the new popup has the Popup on Popup flag set or not. If the Popup on Popup flag is set the underlying popup will remain visible.\n\n* Stack is `[A, B, C]` and C is a popup\n* A call to `monarch.show(D)` is made and D is a popup with the popup on popup flag set\n* Stack is `[A, B, C, D]`\n\nIf the Popup on Popup flag is not set then the underlying popup will be closed, just as when showing a normal screen on top of a popup (see above).\n\n* Stack is `[A, B, C]` and C is a popup\n* A call to `monarch.show(D)` is made and D is a popup without the popup on popup flag set\n* Stack is `[A, B, D]`\n\n### Screen on popup\nIf a screen is shown on top of one or more popups they will all be removed from the stack:\n\n* Stack is `[A, B, C, D]` and C and D are popups\n* A call to `monarch.show(E)` is made and E is not a popup\n* Stack is `[A, B, E]`\n\n\n## Transitions\nYou can add optional transitions when navigating between screens. This is [described in detail here](/README_TRANSITIONS.md).\n\n\n## Screen focus gain/loss\nMonarch will send focus gain and focus loss messages if a focus change listener has been set using `monarch.on_focus_change(screen_id, fn)` \n\nDEPRECATED: ~~Monarch will send focus gain and focus loss messages if a `Focus Url` (proxy) or `Focus Id` (collectionfactory) was provided when the screen was created.~~\n\nThe focus gained message will contain the id of the previous screen and the focus loss message will contain the id of the next screen. Example:\n\n```lua\n\tlocal monarch = require \"monarch.monarch\"\n\n\tfunction init(self)\n\t\tmonarch.on_focus_changed(\"foobar\", function(message_id, message, sender)\n\t\t\tif message_id == monarch.FOCUS.GAINED then\n\t\t\t\tprint(\"Focus gained, previous screen: \", message.id)\n\t\t\telseif message_id == monarch.FOCUS.LOST then\n\t\t\t\tprint(\"Focus lost, next screen: \", message.id)\n\t\t\tend\n\t\tend)\n\tend\n\n\tfunction on_message(self, message_id, message, sender)\n\t\tmonarch.on_message(message_id, message, sender)\n\tend\n```\n\n\n## Callbacks\nBoth the `monarch.show()` and `monarch.back()` functions take an optional callback function that will be invoked when the `transition_show_in` (or the `transition_back_in` in the case of a `monarch.back()` call) transition is completed. The transition is considered completed when a `transition_done` message has been received (see section on [transitions](#transitions) above).\n\n\n## Monarch API\nThe full [Monarch API is documented here](/README_API.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbritzl%2Fmonarch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbritzl%2Fmonarch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbritzl%2Fmonarch/lists"}