Wait for popups when closing them

Fixes #35

.gitignore

@@ -8,3 +8,4 @@ build
 .cproject
 builtins
 .internal
+luacov.report.out

.luacov

@@ -0,0 +1,74 @@
+local reporter = require "luacov.reporter.defold"
+
+--- Default values for configuration options.
+-- For project specific configuration create '.luacov' file in your project
+-- folder. It should be a Lua script setting various options as globals
+-- or returning table of options.
+-- @class module
+-- @name deftest.coverage.configuration
+return {
+
+  --- Reporter class to use when creating a report. Default: DefaultReporter from reporter.lua
+  reporter = reporter,
+
+  --- Filename to store collected stats. Default: "luacov.stats.out".
+  statsfile = "luacov.stats.out",
+
+  --- Filename to store report. Default: "luacov.report.out".
+  reportfile = "luacov.report.out",
+
+  --- Enable saving coverage data after every `savestepsize` lines?
+  -- Setting this flag to `true` in config is equivalent to running LuaCov
+  -- using `luacov.tick` module. Default: false.
+  tick = false,
+
+  --- Stats file updating frequency for `luacov.tick`.
+  -- The lower this value - the more frequently results will be written out to the stats file.
+  -- You may want to reduce this value (to, for example, 2) to avoid losing coverage data in
+  -- case your program may terminate without triggering luacov exit hooks that are supposed
+  -- to save the data. Default: 100.
+  savestepsize = 100,
+
+  --- Run reporter on completion? Default: true.
+  runreport = true,
+
+  --- Delete stats file after reporting? Default: false.
+  deletestats = true,
+
+  --- Process Lua code loaded from raw strings?
+  -- That is, when the 'source' field in the debug info
+  -- does not start with '@'. Default: true.
+  codefromstrings = true,
+
+  --- Lua patterns for files to include when reporting.
+  -- All will be included if nothing is listed.
+  -- Do not include the '.lua' extension. Path separator is always '/'.
+  -- Overruled by `exclude`.
+  -- @usage
+  -- include = {
+  --    "mymodule$",      -- the main module
+  --    "mymodule%/.+$",  -- and everything namespaced underneath it
+  -- }
+  include = {},
+
+  --- Lua patterns for files to exclude when reporting.
+  -- Nothing will be excluded if nothing is listed.
+  -- Do not include the '.lua' extension. Path separator is always '/'.
+  -- Overrules `include`.
+  exclude = { "^test%/.+$", "^deftest%/.+$" },
+
+  --- Table mapping names of modules to be included to their filenames.
+  -- Has no effect if empty.
+  -- Real filenames mentioned here will be used for reporting
+  -- even if the modules have been installed elsewhere.
+  -- Module name can contain '*' wildcard to match groups of modules,
+  -- in this case corresponding path will be used as a prefix directory
+  -- where modules from the group are located.
+  -- @usage
+  -- modules = {
+  --    ["some_rock"] = "src/some_rock.lua",
+  --    ["some_rock.*"] = "src"
+  -- }
+  modules = {},
+
+}

.travis.yml

@@ -26,3 +26,6 @@ env:
 
 script:
   - "./.travis/run.sh"
+
+after_success:
+  - bash <(curl -s https://codecov.io/bash)

README.md

@@ -1,6 +1,7 @@
 ![](docs/logo.jpg)
 
 [![Build Status](https://travis-ci.org/britzl/monarch.svg?branch=master)](https://travis-ci.org/britzl/monarch)
+[![Code Coverage](https://codecov.io/gh/britzl/monarch/branch/master/graph/badge.svg)](https://codecov.io/gh/britzl/monarch)
 [![Latest Release](https://img.shields.io/github/release/britzl/monarch.svg)](https://github.com/britzl/monarch/releases)
 
 # Monarch
@@ -20,17 +21,39 @@ Using Monarch requires that screens are created in a certain way. Once you have
 
 
 ## Creating screens
-Monarch screens are created in individual collections and loaded through collection 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.script``` provided by Monarch. The ```screen.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 ```screen.script``` are correct:
+Monarch screens are created in individual collections and either loaded through collection proxies or created through collection factories.
+
+### Collection proxies
+For 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:
 
 * **Screen Proxy (url)** - The URL to the collection proxy component containing the actual screen. Defaults to ```#collectionproxy```.
 * **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.
 * **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).
 * **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
+* **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.
 * **Transition Url (url)** - Optional URL to call when the screen is about to be shown/hidden. Use this to trigger a transition (see the section on [transitions](#transitions)).
 * **Focus Url (url)** - Optional URL to call when the screen gains or loses focus (see the section on [screen focus](#screen-focus-gainloss)).
+* **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.
 
-![](docs/setup.png)
+![](docs/setup_proxy.png)
 
+### Collection factories
+For 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:
+
+* **Screen Factory (url)** - The URL to the collection factory component containing the actual screen. Defaults to ```#collectionfactory```.
+* **Screen Id (hash)** - A unique id that can be used to reference the screen when navigating your app.
+* **Popup (boolean)** - Check this if the screen should be treated as a [popup](#popups).
+* **Popup on Popup (boolean)** - Check this if the screen is a [popup](#popups) and it can be shown on top of other popups.
+* **Transition Id (url)** - 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)).
+* **Focus Id (url)** - 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)).
+* **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.
+
+![](docs/setup_factory.png)
+
+Note: Monarch supports dynamic collection factories (ie where the "Load Dynamically" checkbox is checked).
+
+## Nesting screens
+Sometimes 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.
 
 ## Navigating between screens
 The 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:
@@ -73,6 +96,15 @@ As opposed to if the ```clear``` flag was not set:
 * A call to ```monarch.show(B, { clear = false })``` is made
 * Stack is ```[A, B, C, D, B]``` - (B is on top)
 
+#### Showing a screen without adding it to the stack
+Monarch 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:
+
+	-- show the background without adding it to the stack
+	monarch.show(hash("background"), { no_stack = true })
+
+	-- hide the background
+	monarch.hide(hash("background"))
+
 ### Going back to a previous screen
 You navigate back in the screen hierarchy in one of two ways:
 
@@ -162,6 +194,8 @@ The predefined transitions provided by ```monarch.transitions.gui``` are:
 * ```slide_out_bottom```
 * ```scale_in```
 * ```scale_out```
+* ```fade_in``` - Set node alpha to fully transparent (i.e. 0.0) and fade to fully opaque (i.e. 1.0)
+* ```fade_out``` - Set node alpha to fully opaque (i.e. 1.0) and fade to fully transparent (i.e. 0.0)
 
 Additionally there's functionality to create a full set of transitions for common transition styles:
 
@@ -169,6 +203,7 @@ Additionally there's functionality to create a full set of transitions for commo
 * ```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])```
 
 **PARAMETERS**
 * ```node``` (node) - Gui node to animate.
@@ -261,13 +296,25 @@ Show a Monarch screen. Note that the screen must be registered before it can be
 
 The options table can contain the following fields:
 
-* ```clear``` (boolean) - If the clear flag is set Monarch will search the stack for the screen that is to be shown. 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.
+* ```clear``` (boolean) - If the `clear` flag is set Monarch will search the stack for the screen that is to be shown. 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.
-* ```reload``` (boolean) - If the reload flag is set Monarch will reload the collection proxy if it's already loaded (this can happen if the previous screen was a popup).
+* ```reload``` (boolean) - If the `reload` flag is set Monarch will reload the collection proxy if it's already loaded (this can happen if the previous screen was a popup).
+* ```no_stack``` (boolean) - If the `no_stack` flag is set Monarch will load the screen without adding it to the screen stack.
 
 **RETURN**
 * ```success``` (boolean) - True if the process of showing the screen was started successfully. False if already busy showing/hiding a screen.
 
 
+### monarch.hide(screen_id, [callback])
+Hide a screen that has been shown using the `no_stack` option. If used on a screen that was shown without the `no_stack` option it will only hide it if the screen is on top of the stack and the behavior will be exactly like if `monarch.back()` had been called.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to hide.
+* ```callback``` (function) - Optional function to call when the screen has been hidden.
+
+**RETURN**
+* ```success``` (boolean) - True if the process of hiding the screen was started successfully.
+
+
 ### monarch.back([data], [callback])
 Go back to a previous Monarch screen
 
@@ -284,7 +331,15 @@ Preload a Monarch screen. This will load but not enable the screen. This is usef
 
 **PARAMETERS**
 * ```screen_id``` (hash) - Id of the screen to preload.
-* ```callback``` (function) - Optional function to call when the new screen is preloaded.
+* ```callback``` (function) - Optional function to call when the screen is preloaded.
+
+
+### monarch.unload(screen_id, [callback])
+Unload a preloaded Monarch screen. A preloaded screen will automatically get unloaded when hidden, but this function can be useful if a screen has been preloaded and it needs to be unloaded again.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to unload.
+* ```callback``` (function) - Optional function to call when the screen is unloaded.
 
 
 ### monarch.top([offset])
@@ -334,6 +389,26 @@ Check if Monarch is busy showing and/or hiding a screen.
 * ```busy``` (boolean) - True if busy hiding and/or showing a screen.
 
 
+### monarch.is_top(id)
+Check if a Monarch screen is at the top of the view stack.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to check
+
+**RETURN**
+* ```exists``` (boolean) - True if the screen is at the top of the stack.
+
+
+### monarch.is_visible(id)
+Check if a Monarch screen is visible.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to check
+
+**RETURN**
+* ```exists``` (boolean) - True if the screen is visible.
+
+
 ### monarch.add_listener([url])
 Add a URL that will be notified of navigation events.
 

assets/logo.atlas

@@ -0,0 +1,6 @@
+images {
+  image: "/assets/images/logo.png"
+}
+margin: 0
+extrude_borders: 0
+inner_padding: 0

example/about.gui

@@ -48,7 +48,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -103,7 +103,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -172,7 +172,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "ok_reload_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -235,7 +235,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: true
   parent: "root"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -284,7 +284,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -353,7 +353,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "ok_clear_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -402,7 +402,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -471,7 +471,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: true
   parent: "ok_clearreload_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -520,7 +520,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -589,7 +589,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "ok_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -598,6 +598,12 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+layers {
+  name: "below"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/background.collection

@@ -0,0 +1,42 @@
+name: "background"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "embedded_components {\n"
+  "  id: \"sprite\"\n"
+  "  type: \"sprite\"\n"
+  "  data: \"tile_set: \\\"/assets/logo.atlas\\\"\\n"
+  "default_animation: \\\"logo\\\"\\n"
+  "material: \\\"/builtins/materials/sprite.material\\\"\\n"
+  "blend_mode: BLEND_MODE_ALPHA\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "}\n"
+  ""
+  position {
+    x: 320.0
+    y: 568.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}

example/confirm.gui

@@ -48,7 +48,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -103,7 +103,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -172,7 +172,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "yes_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -221,7 +221,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -290,7 +290,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "no_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -362,6 +362,12 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+layers {
+  name: "below"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/example.collection

@@ -3,8 +3,8 @@ scale_along_z: 0
 embedded_instances {
   id: "menu"
   data: "components {\n"
-  "  id: \"screen\"\n"
+  "  id: \"screen_factory\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_factory.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -22,21 +22,21 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_url\"\n"
+  "    id: \"transition_id\"\n"
-  "    value: \"menu:/go#menu\"\n"
+  "    value: \"/go\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
+  "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"focus_url\"\n"
+  "    id: \"focus_id\"\n"
-  "    value: \"menu:/go#menu\"\n"
+  "    value: \"/go\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
+  "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "}\n"
   "embedded_components {\n"
-  "  id: \"collectionproxy\"\n"
+  "  id: \"collectionfactory\"\n"
-  "  type: \"collectionproxy\"\n"
+  "  type: \"collectionfactory\"\n"
-  "  data: \"collection: \\\"/example/menu.collection\\\"\\n"
+  "  data: \"prototype: \\\"/example/menu.collection\\\"\\n"
-  "exclude: false\\n"
+  "load_dynamically: true\\n"
   "\"\n"
   "  position {\n"
   "    x: 0.0\n"
@@ -122,7 +122,7 @@ embedded_instances {
   id: "pregame"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -185,7 +185,7 @@ embedded_instances {
   id: "game"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -244,79 +244,11 @@ embedded_instances {
     z: 1.0
   }
 }
-embedded_instances {
-  id: "popup"
-  data: "components {\n"
-  "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
-  "  position {\n"
-  "    x: 0.0\n"
-  "    y: 0.0\n"
-  "    z: 0.0\n"
-  "  }\n"
-  "  rotation {\n"
-  "    x: 0.0\n"
-  "    y: 0.0\n"
-  "    z: 0.0\n"
-  "    w: 1.0\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"screen_id\"\n"
-  "    value: \"popup\"\n"
-  "    type: PROPERTY_TYPE_HASH\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"popup\"\n"
-  "    value: \"true\"\n"
-  "    type: PROPERTY_TYPE_BOOLEAN\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_url\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "}\n"
-  "embedded_components {\n"
-  "  id: \"collectionproxy\"\n"
-  "  type: \"collectionproxy\"\n"
-  "  data: \"collection: \\\"/example/popup.collection\\\"\\n"
-  "exclude: false\\n"
-  "\"\n"
-  "  position {\n"
-  "    x: 0.0\n"
-  "    y: 0.0\n"
-  "    z: 0.0\n"
-  "  }\n"
-  "  rotation {\n"
-  "    x: 0.0\n"
-  "    y: 0.0\n"
-  "    z: 0.0\n"
-  "    w: 1.0\n"
-  "  }\n"
-  "}\n"
-  ""
-  position {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-  }
-  rotation {
-    x: 0.0
-    y: 0.0
-    z: 0.0
-    w: 1.0
-  }
-  scale3 {
-    x: 1.0
-    y: 1.0
-    z: 1.0
-  }
-}
 embedded_instances {
   id: "about"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -339,10 +271,20 @@ embedded_instances {
   "    type: PROPERTY_TYPE_BOOLEAN\n"
   "  }\n"
   "  properties {\n"
+  "    id: \"popup_on_popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
   "    id: \"transition_url\"\n"
   "    value: \"about:/go#about\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
+  "  properties {\n"
+  "    id: \"preload\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
   "}\n"
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"
@@ -384,7 +326,7 @@ embedded_instances {
   id: "confirm"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -453,3 +395,61 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "background"
+  data: "components {\n"
+  "  id: \"screen_factory\"\n"
+  "  component: \"/monarch/screen_factory.script\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"screen_id\"\n"
+  "    value: \"background\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionfactory\"\n"
+  "  type: \"collectionfactory\"\n"
+  "  data: \"prototype: \\\"/example/background.collection\\\"\\n"
+  "load_dynamically: false\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "}\n"
+  ""
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}

example/game.gui

@@ -48,7 +48,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -103,7 +103,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -172,7 +172,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "win_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -235,7 +235,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "root"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -244,6 +244,12 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+layers {
+  name: "below"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/main.script

@@ -8,6 +8,8 @@ end
 
 function on_message(self, message_id, message, sender)
 	if message_id == hash("init_monarch") then
-		monarch.show(hash("menu"))
+		monarch.show(hash("background"), { no_stack = true }, nil, function()
+			monarch.show(hash("menu"))
+		end)
 	end
 end

example/menu.collection

@@ -35,3 +35,81 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "popup"
+  data: "components {\n"
+  "  id: \"screen\"\n"
+  "  component: \"/monarch/screen_factory.script\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"screen_id\"\n"
+  "    value: \"popup\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"popup_on_popup\"\n"
+  "    value: \"true\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"transition_id\"\n"
+  "    value: \"/go\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"focus_id\"\n"
+  "    value: \"/go\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionfactory\"\n"
+  "  type: \"collectionfactory\"\n"
+  "  data: \"prototype: \\\"/example/popup.collection\\\"\\n"
+  "load_dynamically: false\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "}\n"
+  ""
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}

example/menu.gui

@@ -48,7 +48,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -103,7 +103,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -172,7 +172,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "startgame_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -221,7 +221,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -290,7 +290,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "about_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -339,7 +339,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -408,7 +408,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "back_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -471,7 +471,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "root"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -480,6 +480,67 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 320.0
+    y: 272.0
+    z: 0.0
+    w: 1.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  size {
+    x: 40.0
+    y: 40.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.6
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "spinner"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: "below"
+  inherit_alpha: true
+  slice9 {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 0.0
+  }
+  clipping_mode: CLIPPING_MODE_NONE
+  clipping_visible: true
+  clipping_inverted: false
+  alpha: 1.0
+  template_node_child: false
+  size_mode: SIZE_MODE_MANUAL
+}
+layers {
+  name: "below"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 layouts {
   name: "Landscape"
@@ -523,7 +584,7 @@ layouts {
     pivot: PIVOT_CENTER
     adjust_mode: ADJUST_MODE_FIT
     parent: "root"
-    layer: ""
+    layer: "below"
     inherit_alpha: true
     slice9 {
       x: 0.0
@@ -579,7 +640,7 @@ layouts {
     pivot: PIVOT_CENTER
     adjust_mode: ADJUST_MODE_FIT
     parent: "root"
-    layer: ""
+    layer: "below"
     inherit_alpha: true
     slice9 {
       x: 0.0
@@ -635,7 +696,7 @@ layouts {
     pivot: PIVOT_CENTER
     adjust_mode: ADJUST_MODE_FIT
     parent: "root"
-    layer: ""
+    layer: "below"
     inherit_alpha: true
     slice9 {
       x: 0.0
@@ -705,7 +766,7 @@ layouts {
     adjust_mode: ADJUST_MODE_FIT
     line_break: false
     parent: "root"
-    layer: ""
+    layer: "text"
     inherit_alpha: true
     alpha: 1.0
     outline_alpha: 1.0

example/menu.gui_script

@@ -6,7 +6,9 @@ function init(self)
 
 	gui.set_text(gui.get_node("timestamp"), os.date())
 
-	self.transition = transitions.in_right_out_left(gui.get_node("root"), 0.6, 0)
+	gui.animate(gui.get_node("spinner"), gui.PROP_ROTATION, vmath.vector3(0, 0, -360), gui.EASING_INOUTQUAD, 2, 0, nil, gui.PLAYBACK_LOOP_FORWARD)
+
+	self.transition = transitions.fade_in_out(gui.get_node("root"), 0.6, 0)
 end
 
 function on_input(self, action_id, action)

example/popup.gui

@@ -48,7 +48,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -103,7 +103,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -172,7 +172,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "ok_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -221,7 +221,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -290,7 +290,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "cancel_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -339,7 +339,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -408,7 +408,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "about_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -417,6 +417,67 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 184.0
+    y: 136.0
+    z: 0.0
+    w: 1.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  size {
+    x: 10.0
+    y: 10.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "spinner"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: "below"
+  inherit_alpha: true
+  slice9 {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 0.0
+  }
+  clipping_mode: CLIPPING_MODE_NONE
+  clipping_visible: true
+  clipping_inverted: false
+  alpha: 1.0
+  template_node_child: false
+  size_mode: SIZE_MODE_MANUAL
+}
+layers {
+  name: "below"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/popup.gui_script

@@ -8,6 +8,8 @@ function init(self)
 	self.about = gui.get_node("about_button")
 	gui.set_render_order(14)
 
+	gui.animate(gui.get_node("spinner"), gui.PROP_ROTATION, vmath.vector3(0, 0, -360), gui.EASING_INOUTQUAD, 2, 0, nil, gui.PLAYBACK_LOOP_FORWARD)
+	
 	self.transition = transitions.create(gui.get_node("root"))
 		.show_in(transitions.scale_in, gui.EASING_OUTBACK, 0.3, 0)
 		.show_out(transitions.scale_out, gui.EASING_INBACK, 0.3, 0)

example/pregame.gui

@@ -48,7 +48,7 @@ nodes {
   yanchor: YANCHOR_NONE
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -103,7 +103,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -172,7 +172,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "play_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -221,7 +221,7 @@ nodes {
   pivot: PIVOT_CENTER
   adjust_mode: ADJUST_MODE_FIT
   parent: "root"
-  layer: ""
+  layer: "below"
   inherit_alpha: true
   slice9 {
     x: 0.0
@@ -290,7 +290,7 @@ nodes {
   adjust_mode: ADJUST_MODE_FIT
   line_break: false
   parent: "back_button"
-  layer: ""
+  layer: "text"
   inherit_alpha: true
   alpha: 1.0
   outline_alpha: 1.0
@@ -299,6 +299,12 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+layers {
+  name: "below"
+}
+layers {
+  name: "text"
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

game.project

@@ -1,10 +1,10 @@
 [project]
 title = Monarch
 version = 0.9
-dependencies = https://github.com/britzl/deftest/archive/2.3.0.zip
+dependencies = https://github.com/britzl/deftest/archive/2.4.3.zip
 
 [bootstrap]
-main_collection = /example/example.collectionc
+main_collection = /test/test.collectionc
 
 [input]
 game_binding = /input/game.input_bindingc

monarch/monarch.lua

@@ -11,6 +11,7 @@ local ACQUIRE_INPUT_FOCUS = hash("acquire_input_focus")
 local ASYNC_LOAD = hash("async_load")
 local UNLOAD = hash("unload")
 local ENABLE = hash("enable")
+local DISABLE = hash("disable")
 
 -- transition messages
 M.TRANSITION = {}
@@ -112,9 +113,34 @@ function M.is_top(id)
 end
 
 
---- Register a new screen
+--- Check if a screen is visible
--- This is done automatically by the screen.script. It is expected that the
+-- @param id (string|hash)
--- caller of this function is a script component attached to the same game
+-- @return true if the screen is visible
+function M.is_visible(id)
+	assert(id, "You must provide a screen id")
+	id = tohash(id)
+	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
+	return screens[id].loaded
+end
+
+
+local function register(id, settings)
+	assert(id, "You must provide a screen id")
+	id = tohash(id)
+	assert(not screens[id], ("There is already a screen registered with id %s"):format(tostring(id)))
+	screens[id] = {
+		id = id,
+		script = msg.url(),
+		popup = settings and settings.popup,
+		popup_on_popup = settings and settings.popup_on_popup,
+		timestep_below_popup = settings and settings.timestep_below_popup or 1,
+	}
+	return screens[id]
+end
+
+--- Register a new screen contained in a collection proxy
+-- This is done automatically by the screen_proxy.script. It is expected that
+-- the caller of this function is a script component attached to the same game
 -- object as the proxy. This is required since monarch will acquire and
 -- release input focus of the game object where the proxy is attached.
 -- @param id Unique id of the screen
@@ -127,21 +153,48 @@ end
 --		  screen transitions
 -- 		* focus_url - URL to a script that is to be notified of focus
 --		  lost/gained events
-function M.register(id, proxy, settings)
+--		* timestep_below_popup - Timestep to set on proxy when below a popup
-	assert(id, "You must provide a screen id")
+--		* auto_preload - true if the screen should be automatically preloaded
-	id = tohash(id)
+function M.register_proxy(id, proxy, settings)
-	assert(not screens[id], ("There is already a screen registered with id %s"):format(tostring(id)))
 	assert(proxy, "You must provide a collection proxy URL")
-	local url = msg.url(proxy)
+	local screen = register(id, settings)
-	screens[id] = {
+	screen.proxy = proxy
-		id = id,
+	screen.transition_url = settings and settings.transition_url
-		proxy = proxy,
+	screen.focus_url = settings and settings.focus_url
-		script = msg.url(),
+	screen.auto_preload = settings and settings.auto_preload
-		popup = settings and settings.popup,
+	if screen.auto_preload then
-		popup_on_popup = settings and settings.popup_on_popup,
+		M.preload(id)
-		transition_url = settings and settings.transition_url,
+	end
-		focus_url = settings and settings.focus_url,
+end
-	}
+M.register = M.register_proxy
+
+
+--- Register a new screen contained in a collection factory
+-- This is done automatically by the screen_factory.script. It is expected that
+-- the caller of this function is a script component attached to the same game
+-- object as the factory. This is required since monarch will acquire and
+-- release input focus of the game object where the factory is attached.
+-- @param id Unique id of the screen
+-- @param factory URL to the collection factory containing the screen
+-- @param settings Settings table for screen. Accepted values:
+-- 		* popup - true the screen is a popup
+--		* popup_on_popup - true if this popup can be shown on top of
+--		  another popup or false if an underlying popup should be closed
+-- 		* transition_id - Id of the game object in the collection that is responsible
+--		  for the screen transitions
+-- 		* focus_id - Id of the game object in the collection that is to be notified
+--		  of focus lost/gained events
+--		* auto_preload - true if the screen should be automatically preloaded
+function M.register_factory(id, factory, settings)
+	assert(factory, "You must provide a collection factory URL")
+	local screen = register(id, settings)
+	screen.factory = factory
+	screen.transition_id = settings and settings.transition_id
+	screen.focus_id = settings and settings.focus_id
+	screen.auto_preload = settings and settings.auto_preload
+	if screen.auto_preload then
+		M.preload(id)
+	end
 end
 
 --- Unregister a screen
@@ -157,7 +210,13 @@ end
 local function acquire_input(screen)
 	log("change_context()", screen.id)
 	if not screen.input then
-		msg.post(screen.script, ACQUIRE_INPUT_FOCUS)
+		if screen.proxy then
+			msg.post(screen.script, ACQUIRE_INPUT_FOCUS)
+		elseif screen.factory then
+			for id,instance in pairs(screen.factory_ids) do
+				msg.post(instance, ACQUIRE_INPUT_FOCUS)
+			end
+		end
 		screen.input = true
 	end
 end
@@ -165,7 +224,13 @@ end
 local function release_input(screen)
 	log("change_context()", screen.id)
 	if screen.input then
-		msg.post(screen.script, RELEASE_INPUT_FOCUS)
+		if screen.proxy then
+			msg.post(screen.script, RELEASE_INPUT_FOCUS)
+		elseif screen.factory then
+			for id,instance in pairs(screen.factory_ids) do
+				msg.post(instance, RELEASE_INPUT_FOCUS)
+			end
+		end
 		screen.input = false
 	end
 end
@@ -180,35 +245,111 @@ end
 
 local function unload(screen)
 	log("unload()", screen.id)
-	screen.wait_for = PROXY_UNLOADED
+
-	msg.post(screen.proxy, UNLOAD)
+	if screen.proxy then
-	coroutine.yield()
+		if screen.auto_preload then
-	screen.loaded = false
+			msg.post(screen.proxy, DISABLE)
-	screen.wait_for = nil
+			screen.loaded = false
+			screen.preloaded = true
+		else
+			screen.wait_for = PROXY_UNLOADED
+			msg.post(screen.proxy, UNLOAD)
+			coroutine.yield()
+			screen.loaded = false
+			screen.preloaded = false
+			screen.wait_for = nil
+		end
+	elseif screen.factory then
+		for id, instance in pairs(screen.factory_ids) do
+			go.delete(instance)
+		end
+		screen.factory_ids = nil
+		if screen.auto_preload then
+			screen.loaded = false
+			screen.preloaded = true
+		else
+			collectionfactory.unload(screen.factory)
+			screen.loaded = false
+			screen.preloaded = false
+		end
+	end
 end
 
-local function async_load(screen)
+
-	log("async_load()", screen.id)
+local function preload(screen)
-	screen.wait_for = PROXY_LOADED
+	log("preload() preloading screen", screen.id)
-	msg.post(screen.proxy, ASYNC_LOAD)
+	assert(screen.co, "You must assign a coroutine to the screen")
-	coroutine.yield()
+
-	msg.post(screen.proxy, ENABLE)
+	if screen.preloaded then
+		log("preload() screen already preloaded", screen.id)
+		return
+	end
+
+	if screen.proxy then
+		screen.wait_for = PROXY_LOADED
+		msg.post(screen.proxy, ASYNC_LOAD)
+		coroutine.yield()
+	elseif screen.factory then
+		if collectionfactory.get_status(screen.factory) == collectionfactory.STATUS_UNLOADED then
+			collectionfactory.load(screen.factory, function(self, url, result)
+				assert(coroutine.resume(screen.co))
+			end)
+			coroutine.yield()
+		end
+
+		if collectionfactory.get_status(screen.factory) ~= collectionfactory.STATUS_LOADED then
+			log("preload() error loading factory resources")
+			return
+		end
+	end
+	screen.preloaded = true
+end
+
+local function load(screen)
+	log("load()", screen.id)
+	assert(screen.co, "You must assign a coroutine to the screen")
+
+	if screen.loaded then
+		log("load() screen already loaded", screen.id)
+		return
+	end
+
+	preload(screen)
+
+	if not screen.preloaded then
+		log("load() screen wasn't preloaded", screen.id)
+		return
+	end
+
+	if screen.proxy then
+		msg.post(screen.proxy, ENABLE)
+	elseif screen.factory then
+		screen.factory_ids = collectionfactory.create(screen.factory)
+		screen.transition_url = screen.factory_ids[screen.transition_id]
+		screen.focus_url = screen.factory_ids[screen.focus_id]
+	end
 	screen.loaded = true
-	screen.wait_for = nil
+	screen.preloaded = false
 end
 
 local function transition(screen, message_id, message)
 	log("transition()", screen.id)
-	screen.wait_for = M.TRANSITION.DONE
+	if screen.transition_url then
-	msg.post(screen.transition_url, message_id, message)
+		screen.wait_for = M.TRANSITION.DONE
-	coroutine.yield()
+		msg.post(screen.transition_url, message_id, message)
-	screen.wait_for = nil
+		coroutine.yield()
+		screen.wait_for = nil
+	else
+		log("transition() no transition url - ignoring")
+	end
 end
 
 local function focus_gained(screen, previous_screen)
 	log("focus_gained()", screen.id)
 	if screen.focus_url then
 		msg.post(screen.focus_url, M.FOCUS.GAINED, { id = previous_screen and previous_screen.id })
+	else
+		log("focus_gained() no focus url - ignoring")
 	end
 end
 
@@ -216,6 +357,22 @@ local function focus_lost(screen, next_screen)
 	log("focus_lost()", screen.id)
 	if screen.focus_url then
 		msg.post(screen.focus_url, M.FOCUS.LOST, { id = next_screen and next_screen.id })
+	else
+		log("focus_lost() no focus url - ignoring")
+	end
+end
+
+local function change_timestep(screen)
+	if screen.proxy then
+		screen.changed_timestep = true
+		msg.post(screen.proxy, "set_time_step", { mode = 0, factor = screen.timestep_below_popup })
+	end
+end
+
+local function reset_timestep(screen)
+	if screen.proxy and screen.changed_timestep then
+		msg.post(screen.proxy, "set_time_step", { mode = 0, factor = 1 })
+		screen.changed_timestep = false
 	end
 end
 
@@ -227,10 +384,15 @@ local function disable(screen, next_screen)
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
+		if next_screen and next_screen.popup then
+			change_timestep(screen)
+		else
+			reset_timestep(screen)
+		end
 		screen.co = nil
 		if cb then cb() end
 	end)
-	coroutine.resume(co)
+	assert(coroutine.resume(co))
 end
 
 local function enable(screen, previous_screen)
@@ -241,10 +403,11 @@ local function enable(screen, previous_screen)
 		change_context(screen)
 		acquire_input(screen)
 		focus_gained(screen, previous_screen)
+		reset_timestep(screen)
 		screen.co = nil
 		if cb then cb() end
 	end)
-	coroutine.resume(co)
+	assert(coroutine.resume(co))
 end
 
 local function show_out(screen, next_screen, cb)
@@ -257,13 +420,16 @@ local function show_out(screen, next_screen, cb)
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
+		reset_timestep(screen)
 		-- if the next screen is a popup we want the current screen to stay visible below the popup
 		-- if the next screen isn't a popup the current one should be unloaded and transitioned out
-		local next_is_popup = next_screen and not next_screen.popup
+		local next_is_popup = next_screen and next_screen.popup
 		local current_is_popup = screen.popup
-		if (next_is_popup and not current_is_popup) or (current_is_popup) then
+		if (not next_is_popup and not current_is_popup) or (current_is_popup) then
 			transition(screen, M.TRANSITION.SHOW_OUT, { next_screen = next_screen.id })
 			unload(screen)
+		elseif next_is_popup then
+			change_timestep(screen)
 		end
 		screen.co = nil
 		active_transition_count = active_transition_count - 1
@@ -273,7 +439,7 @@ local function show_out(screen, next_screen, cb)
 	coroutine.resume(co)
 end
 
-local function show_in(screen, previous_screen, reload, cb)
+local function show_in(screen, previous_screen, reload, add_to_stack, cb)
 	log("show_in()", screen.id)
 	local co
 	co = coroutine.create(function()
@@ -285,20 +451,11 @@ local function show_in(screen, previous_screen, reload, cb)
 			log("show_in() reloading", screen.id)
 			unload(screen)
 		end
-		-- if the screen has been preloaded we need to enable it
+		load(screen)
-		if screen.preloaded then
+		if add_to_stack then
-			log("show_in() screen was preloaded", screen.id)
+			stack[#stack + 1] = screen
-			msg.post(screen.proxy, ENABLE)
-			screen.loaded = true
-			screen.preloaded = false
-		-- the screen could be loaded if the previous screen was a popup
-		-- and the popup asked to show this screen again
-		-- in that case we shouldn't attempt to load it again
-		elseif not screen.loaded then
-			log("show_in() loading screen", screen.id)
-			async_load(screen)
 		end
-		stack[#stack + 1] = screen
+		reset_timestep(screen)
 		transition(screen, M.TRANSITION.SHOW_IN, { previous_screen = previous_screen and previous_screen.id })
 		acquire_input(screen)
 		focus_gained(screen, previous_screen)
@@ -318,15 +475,8 @@ local function back_in(screen, previous_screen, cb)
 		notify_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 		screen.co = co
 		change_context(screen)
-		if screen.preloaded then
+		load(screen)
-			log("back_in() screen was preloaded", screen.id)
+		reset_timestep(screen)
-			msg.post(screen.proxy, ENABLE)
-			screen.preloaded = false
-			screen.loaded = true
-		elseif not screen.loaded then
-			log("back_in() loading screen", screen.id)
-			async_load(screen)
-		end
 		if previous_screen and not previous_screen.popup then
 			transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id })
 		end
@@ -344,18 +494,21 @@ local function back_out(screen, next_screen, cb)
 	log("back_out()", screen.id)
 	local co
 	co = coroutine.create(function()
-		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
+		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 		active_transition_count = active_transition_count + 1
 		screen.co = co
 		change_context(screen)
 		release_input(screen)
 		focus_lost(screen, next_screen)
+		if next_screen and screen.popup then
+			reset_timestep(next_screen)
+		end
 		transition(screen, M.TRANSITION.BACK_OUT, { next_screen = next_screen and next_screen.id })
 		unload(screen)
 		screen.co = nil
 		active_transition_count = active_transition_count - 1
 		if cb then cb() end
-		notify_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen.id })
+		notify_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen and next_screen.id })
 	end)
 	coroutine.resume(co)
 end
@@ -415,45 +568,88 @@ function M.show(id, options, data, cb)
 
 	log("show()", screen.id)
 
-	-- manipulate the current top
+	local co
-	-- close popup if needed
+	co = coroutine.create(function()
-	-- transition out
+		-- a screen can ignore the stack by setting the no_stack to true
-	local top = stack[#stack]
+		local add_to_stack = not options or not options.no_stack
-	if top then
+		if add_to_stack then
-		-- keep top popup visible if new screen can be shown on top of a popup
+			-- manipulate the current top
-		if top.popup and screen.popup_on_popup then
+			-- close popup(s) if needed
-			disable(top, screen)
+			-- transition out
-		else
+			local top = stack[#stack]
-			-- close all popups
+			if top then
-			while top.popup do
+				-- keep top popup visible if new screen can be shown on top of a popup
-				stack[#stack] = nil
+				if top.popup and screen.popup_on_popup then
-				show_out(top, screen, callbacks.track())
+					disable(top, screen)
-				top = stack[#stack]
+				else
-			end
+					-- close all popups, one by one
-			-- unload and transition out from top
+					while top.popup do
-			-- unless we're showing the same screen as is already visible
+						stack[#stack] = nil
-			if top and top.id ~= screen.id then
+						show_out(top, screen, function()
-				show_out(top, screen, callbacks.track())
+							coroutine.resume(co)
+						end)
+						coroutine.yield()
+						top = stack[#stack]
+					end
+					-- unload and transition out from top
+					-- unless we're showing the same screen as is already visible
+					if top and top.id ~= screen.id then
+						show_out(top, screen, callbacks.track())
+					end
+				end
 			end
 		end
+
+		-- if the screen we want to show is in the stack
+		-- already and the clear flag is set then we need
+		-- to remove every screen on the stack up until and
+		-- including the screen itself
+		if options and options.clear then
+			log("show() clearing")
+			while M.in_stack(id) do
+				table.remove(stack)
+			end
+		end
+
+		-- show screen
+		show_in(screen, top, options and options.reload, add_to_stack, callbacks.track())
+
+		if cb then callbacks.when_done(cb) end
+	end)
+	coroutine.resume(co)
+
+	return true
+end
+
+
+-- Hide a screen. The screen must either be at the top of the stack or
+-- visible but not added to the stack (through the no_stack option)
+-- @param id (string|hash) - Id of the screen to show
+-- @param cb (function) - Optional callback to invoke when the screen is hidden
+-- @return true if successfully hiding, false if busy performing another operation
+function M.hide(id, cb)
+	if M.is_busy() then
+		log("hide() monarch is busy, ignoring request")
+		return false
 	end
 	
-	-- if the screen we want to show is in the stack
+	id = tohash(id)
-	-- already and the clear flag is set then we need
+	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
-	-- to remove every screen on the stack up until and
+
-	-- including the screen itself
+	local screen = screens[id]
-	if options and options.clear then
+	if M.in_stack(id) then
-		log("show() clearing")
+		if not M.is_top(id) then
-		while M.in_stack(id) do
+			log("hide() you can only hide the screen at the top of the stack", id)
-			table.remove(stack)
+			return false
+		end
+		return M.back(id, cb)
+	else
+		if M.is_visible(id) then
+			back_out(screen, nil, cb)
+		elseif cb then
+			cb()
 		end
 	end
-
-	-- show screen
-	show_in(screen, top, options and options.reload, callbacks.track())
-
-	if cb then callbacks.when_done(cb) end
-
 	return true
 end
 
@@ -499,32 +695,69 @@ function M.back(data, cb)
 	return true
 end
 
+
 --- Preload a screen. This will load but not enable and show a screen. Useful for "heavier" screens
 -- that you wish to show without any delay.
 -- @param id (string|hash) - Id of the screen to preload
 -- @param cb (function) - Optional callback to invoke when screen is loaded
 function M.preload(id, cb)
+	if M.is_busy() then
+		log("preload() monarch is busy, ignoring request")
+		return false
+	end
+
 	assert(id, "You must provide a screen id")
 	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
 	local screen = screens[id]
+	log("preload()", screen.id)
 	if screen.preloaded or screen.loaded then
 		if cb then cb() end
-		return
+		return true
 	end
 	local co
 	co = coroutine.create(function()
 		screen.co = co
 		change_context(screen)
-		screen.wait_for = PROXY_LOADED
+		preload(screen)
-		msg.post(screen.proxy, ASYNC_LOAD)
+		log("preload() done", screen.id)
-		coroutine.yield()
-		screen.preloaded = true
-		screen.wait_for = nil
 		if cb then cb() end
 	end)
-	coroutine.resume(co)
+	assert(coroutine.resume(co))
+	return true
+end
+
+
+function M.unload(id, cb)
+	if M.is_busy() then
+		log("unload() monarch is busy, ignoring request")
+		return false
+	end
+	assert(id, "You must provide a screen id")
+	id = tohash(id)
+	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
+
+	if M.is_visible(id) then
+		log("You can't unload a visible screen")
+		return false
+	end
+
+	local screen = screens[id]
+	if not screen.preloaded and not screen.loaded then
+		log("unload() screen is not loaded", tostring(id))
+		if cb then cb() end
+		return true
+	end
+	local co
+	co = coroutine.create(function()
+		screen.co = co
+		change_context(screen)
+		unload(screen)
+		if cb then cb() end
+	end)
+	assert(coroutine.resume(co))
+	return true
 end
 
 

monarch/screen.script

@@ -1,26 +1,31 @@
 local monarch
 
 go.property("screen_proxy", msg.url("#collectionproxy"))
-go.property("screen_id", hash(""))
+go.property("screen_id", hash("UNIQUE ID HERE"))
 go.property("popup", false)
 go.property("popup_on_popup", false)
+go.property("timestep_below_popup", 1)
 go.property("transition_url", msg.url())
 go.property("focus_url", msg.url())
 
 
 function init(self)
+	print("WARNING - screen.script is deprecated. Please use screen_proxy.script")
 	monarch = require "monarch.monarch"
+	local url = msg.url()
 	assert(not self.popup_on_popup or (self.popup_on_popup and self.popup), "Popup on Popups can only be set if the Popup flag is set")
-	monarch.register(
+	assert(self.screen_proxy ~= url, "You must specify either a proxy URL")
-		self.screen_id,
+	assert(self.timestep_below_popup >= 0, "Timestep must be positive")
-		self.screen_proxy,
+
-		{
+	local settings = {
-			popup = self.popup,
+		popup = self.popup,
-			popup_on_popup = self.popup_on_popup,
+		popup_on_popup = self.popup_on_popup,
-			transition_url = self.transition_url,
+		transition_url = self.transition_url ~= url and self.transition_url or nil,
-			focus_url = self.focus_url
+		focus_url = self.focus_url ~= url and self.focus_url or nil,
-		}
+		timestep_below_popup = self.timestep_below_popup,
-	)
+	}
+
+	monarch.register_proxy(self.screen_id, self.screen_proxy, settings)
 end
 
 function final(self)
@@ -34,11 +39,6 @@ function on_message(self, message_id, message, sender)
 		monarch.back()
 	elseif message_id == hash("back") then
 		monarch.back()
-	elseif message_id == monarch.TRANSITION.SHOW_IN
-		or message_id == monarch.TRANSITION.SHOW_OUT
-		or message_id == monarch.TRANSITION.BACK_IN
-		or message_id == monarch.TRANSITION.BACK_OUT then
-			msg.post(sender, monarch.TRANSITION.DONE)
 	else
 		monarch.on_message(message_id, message, sender)
 	end

monarch/screen_factory.script

@@ -0,0 +1,41 @@
+local monarch
+
+go.property("screen_factory", msg.url("#collectionfactory"))
+go.property("screen_id", hash("UNIQUE ID HERE"))
+go.property("popup", false)
+go.property("popup_on_popup", false)
+go.property("transition_id", hash(""))
+go.property("focus_id", hash(""))
+go.property("preload", false)
+
+
+function init(self)
+	monarch = require "monarch.monarch"
+	assert(not self.popup_on_popup or (self.popup_on_popup and self.popup), "Popup on Popups can only be set if the Popup flag is set")
+	assert(self.screen_factory ~= msg.url(), "You must specify either a factory URL")
+	
+	local settings = {
+		popup = self.popup,
+		popup_on_popup = self.popup_on_popup,
+		transition_id = self.transition_id,
+		focus_id = self.focus_id,
+		auto_preload = self.preload,
+	}
+	monarch.register_factory(self.screen_id, self.screen_factory, settings)
+end
+
+function final(self)
+	monarch.unregister(self.screen_id)
+end
+
+function on_message(self, message_id, message, sender)
+	if message_id == hash("show") then
+		monarch.show(self.screen_id, { clear = message.clear })
+	elseif message_id == hash("hide") then
+		monarch.back()
+	elseif message_id == hash("back") then
+		monarch.back()
+	else
+		monarch.on_message(message_id, message, sender)
+	end
+end

monarch/screen_proxy.script

@@ -0,0 +1,46 @@
+local monarch
+
+go.property("screen_proxy", msg.url("#collectionproxy"))
+go.property("screen_id", hash("UNIQUE ID HERE"))
+go.property("popup", false)
+go.property("popup_on_popup", false)
+go.property("timestep_below_popup", 1)
+go.property("transition_url", msg.url())
+go.property("focus_url", msg.url())
+go.property("preload", false)
+
+
+function init(self)
+	monarch = require "monarch.monarch"
+	local url = msg.url()
+	assert(not self.popup_on_popup or (self.popup_on_popup and self.popup), "Popup on Popups can only be set if the Popup flag is set")
+	assert(self.screen_proxy ~= url, "You must specify either a proxy URL")
+	assert(self.timestep_below_popup >= 0, "Timestep must be positive")
+	
+	local settings = {
+		popup = self.popup,
+		popup_on_popup = self.popup_on_popup,
+		transition_url = self.transition_url ~= url and self.transition_url or nil,
+		focus_url = self.focus_url ~= url and self.focus_url or nil,
+		timestep_below_popup = self.timestep_below_popup,
+		auto_preload = self.preload,
+	}
+
+	monarch.register_proxy(self.screen_id, self.screen_proxy, settings)
+end
+
+function final(self)
+	monarch.unregister(self.screen_id)
+end
+
+function on_message(self, message_id, message, sender)
+	if message_id == hash("show") then
+		monarch.show(self.screen_id, { clear = message.clear })
+	elseif message_id == hash("hide") then
+		monarch.back()
+	elseif message_id == hash("back") then
+		monarch.back()
+	else
+		monarch.on_message(message_id, message, sender)
+	end
+end

monarch/transitions/gui.lua

@@ -88,6 +88,22 @@ function M.scale_out(node, from, easing, duration, delay, cb)
 	gui.animate(node, gui.PROP_SCALE, ZERO_SCALE, easing, duration, delay, cb)
 end
 
+function M.fade_out(node, from, easing, duration, delay, cb)
+	local to = gui.get_color(node)
+	to.w = 1
+	gui.set_color(node, to)
+	to.w = 0
+	gui.animate(node, gui.PROP_COLOR, to, easing, duration, delay, cb)
+end
+
+function M.fade_in(node, from, easing, duration, delay, cb)
+	local to = gui.get_color(node)
+	to.w = 0
+	gui.set_color(node, to)
+	to.w = 1
+	gui.animate(node, gui.PROP_COLOR, to, easing, duration, delay, cb)
+end
+
 --- Create a transition for a node
 -- @return Transition instance
 function M.create(node)
@@ -255,4 +271,16 @@ function M.in_left_out_left(node, duration, delay, easing)
 end
 
 
+function M.fade_in_out(node, duration, delay, easing)
+	assert(node, "You must provide a node")
+	assert(duration, "You must provide a duration")
+	easing = easing or easings.QUAD()
+	return M.create(node)
+	.show_in(M.fade_in, easing.OUT, duration, delay or 0)
+	.show_out(M.fade_out, easing.IN, duration, delay or 0)
+	.back_in(M.fade_in, easing.OUT, duration, delay or 0)
+	.back_out(M.fade_out, easing.IN, duration, delay or 0)
+end
+
+
 return M

test/data/background.collection

@@ -0,0 +1,22 @@
+name: "default"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: ""
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}

test/data/screens.collection

@@ -4,7 +4,7 @@ embedded_instances {
   id: "screen1"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -62,7 +62,7 @@ embedded_instances {
   id: "screen2"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_factory.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -81,10 +81,10 @@ embedded_instances {
   "  }\n"
   "}\n"
   "embedded_components {\n"
-  "  id: \"collectionproxy\"\n"
+  "  id: \"collectionfactory\"\n"
-  "  type: \"collectionproxy\"\n"
+  "  type: \"collectionfactory\"\n"
-  "  data: \"collection: \\\"/test/data/screen2.collection\\\"\\n"
+  "  data: \"prototype: \\\"/test/data/screen2.collection\\\"\\n"
-  "exclude: false\\n"
+  "load_dynamically: false\\n"
   "\"\n"
   "  position {\n"
   "    x: 0.0\n"
@@ -120,7 +120,7 @@ embedded_instances {
   id: "popup1"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -142,11 +142,6 @@ embedded_instances {
   "    value: \"true\"\n"
   "    type: PROPERTY_TYPE_BOOLEAN\n"
   "  }\n"
-  "  properties {\n"
-  "    id: \"popup_on_popup\"\n"
-  "    value: \"false\"\n"
-  "    type: PROPERTY_TYPE_BOOLEAN\n"
-  "  }\n"
   "}\n"
   "embedded_components {\n"
   "  id: \"collectionproxy\"\n"
@@ -188,7 +183,7 @@ embedded_instances {
   id: "popup2"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -256,7 +251,7 @@ embedded_instances {
   id: "transition1"
   data: "components {\n"
   "  id: \"screen\"\n"
-  "  component: \"/monarch/screen.script\"\n"
+  "  component: \"/monarch/screen_proxy.script\"\n"
   "  position {\n"
   "    x: 0.0\n"
   "    y: 0.0\n"
@@ -355,3 +350,61 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "background"
+  data: "components {\n"
+  "  id: \"screen_factory\"\n"
+  "  component: \"/monarch/screen_factory.script\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"screen_id\"\n"
+  "    value: \"background\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionfactory\"\n"
+  "  type: \"collectionfactory\"\n"
+  "  data: \"prototype: \\\"/test/data/background.collection\\\"\\n"
+  "load_dynamically: false\\n"
+  "\"\n"
+  "  position {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "  }\n"
+  "  rotation {\n"
+  "    x: 0.0\n"
+  "    y: 0.0\n"
+  "    z: 0.0\n"
+  "    w: 1.0\n"
+  "  }\n"
+  "}\n"
+  ""
+  position {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+  }
+  rotation {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  scale3 {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+  }
+}

test/test.script

@@ -5,5 +5,5 @@ local test_monarch = require "test.test_monarch"
 
 function init(self)
 	deftest.add(test_monarch)
-	deftest.run()
+	deftest.run({ coverage = { enabled = true }})
 end

test/test_monarch.lua

@@ -6,6 +6,7 @@ local monarch = require "monarch.monarch"
 local SCREEN1_STR = hash("screen1")
 local SCREEN1 = hash(SCREEN1_STR)
 local SCREEN2 = hash("screen2")
+local BACKGROUND = hash("background")
 local POPUP1 = hash("popup1")
 local POPUP2 = hash("popup2")
 local FOOBAR = hash("foobar")
@@ -16,11 +17,11 @@ return function()
 	local screens_instances = {}
 
 	local function is_shown(screen_id)
-		return monarch.is_top(screen_id)
+		return monarch.is_visible(screen_id)
 	end
 
 	local function is_hidden(screen_id)
-		return not monarch.is_top(screen_id)
+		return not monarch.is_visible(screen_id)
 	end
 
 	local function wait_timeout(fn, ...)
@@ -32,6 +33,9 @@ return function()
 		return fn(...)
 	end
 
+	local function wait_until_visible(screen_id)
+		return wait_timeout(is_visible, screen_id)
+	end
 	local function wait_until_shown(screen_id)
 		return wait_timeout(is_shown, screen_id)
 	end
@@ -60,9 +64,14 @@ return function()
 			mock_msg.mock()
 			monarch = require "monarch.monarch"
 			screens_instances = collectionfactory.create("#screensfactory")
+			monarch.debug()
 		end)
 
 		after(function()
+			while #monarch.get_stack() > 0 do
+				monarch.back()
+				wait_until_not_busy()
+			end
 			mock_msg.unmock()
 			unload.unload("monarch%..*")
 			for id,instance_id in pairs(screens_instances) do
@@ -99,6 +108,64 @@ return function()
 			assert_stack({ })
 		end)
 
+		it("should be able to tell if a screen is visible or not", function()
+			assert(not monarch.is_visible(SCREEN1))
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			assert(monarch.is_visible(SCREEN1))
+			
+			monarch.show(SCREEN2)
+			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			assert_stack({ SCREEN1, SCREEN2 })
+			assert(not monarch.is_visible(SCREEN1))
+			assert(monarch.is_visible(SCREEN2))
+			
+			monarch.show(POPUP1)
+			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert_stack({ SCREEN1, SCREEN2, POPUP1 })
+			assert(not monarch.is_visible(SCREEN1))
+			assert(monarch.is_visible(SCREEN2))
+			assert(monarch.is_visible(POPUP1))
+		end)
+
+		it("should be able to show a screen without adding it to the stack", function()
+			monarch.show(BACKGROUND, { no_stack = true })
+			assert(wait_until_shown(BACKGROUND), "Background was never shown")
+			assert_stack({ })
+
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+		end)
+
+		it("should be able to hide a screen not added to the stack", function()
+			monarch.show(BACKGROUND, { no_stack = true })
+			assert(wait_until_shown(BACKGROUND), "Background was never shown")
+			assert_stack({ })
+
+			monarch.hide(BACKGROUND)
+			assert(wait_until_hidden(BACKGROUND), "Background was never hidden")
+			assert_stack({ })
+		end)
+
+		it("should be able to hide the top screen", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+
+			monarch.show(SCREEN2)
+			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			assert_stack({ SCREEN1, SCREEN2 })
+
+			assert(monarch.hide(SCREEN1) == false)
+			assert(monarch.hide(SCREEN2) == true)
+			assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden")
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+		end)
 
 		it("should be able to pass data to a screen when showning it or going back to it", function()
 			local data1 = { foo = "bar" }
@@ -143,7 +210,7 @@ return function()
 		end)
 		
 
-		it("should be able to show one popup on top of another the Popup On Popup flag is set", function()
+		it("should be able to show one popup on top of another if the Popup On Popup flag is set", function()
 			monarch.show(SCREEN1)
 			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
 			assert_stack({ SCREEN1 })
@@ -234,6 +301,14 @@ return function()
 			assert(wait_until_not_busy())
 		end)
 
+		it("should ignore any preload calls while busy", function()
+			monarch.show(TRANSITION1)
+			-- previously a call to preload() while also showing a screen would
+			-- lock up monarch. See issue #32
+			monarch.preload(TRANSITION1)
+			assert(wait_until_shown(TRANSITION1), "Transition1 was never shown")
+		end)
+		
 		it("should be able to notify listeners of navigation events", function()
 			local URL1 = msg.url(screens_instances[hash("/listener1")])
 			local URL2 = msg.url(screens_instances[hash("/listener2")])
@@ -255,21 +330,30 @@ return function()
 			monarch.show(SCREEN2)
 			assert(wait_until_not_busy())
 
-			monarch.back()
+			assert(#mock_msg.messages(URL1) == 6)
-			assert(wait_until_not_busy())
-						
-			local messages_1 = mock_msg.messages(URL1)
-			local messages_2 = mock_msg.messages(URL2)
-			assert(#mock_msg.messages(URL1) == 10)
 			assert(#mock_msg.messages(URL2) == 2)
 			assert(mock_msg.messages(URL1)[3].message_id == monarch.SCREEN_TRANSITION_OUT_STARTED)
 			assert(mock_msg.messages(URL1)[3].message.screen == SCREEN1)
 			assert(mock_msg.messages(URL1)[4].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
 			assert(mock_msg.messages(URL1)[4].message.screen == SCREEN2)
-			assert(mock_msg.messages(URL1)[5].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
+			assert(mock_msg.messages(URL1)[5].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
-			assert(mock_msg.messages(URL1)[5].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[5].message.screen == SCREEN2)
-			assert(mock_msg.messages(URL1)[6].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[6].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
+			assert(mock_msg.messages(URL1)[6].message.screen == SCREEN1)
+						
+			monarch.back()
+			assert(wait_until_not_busy())
+						
+			assert(#mock_msg.messages(URL1) == 10)
+			assert(#mock_msg.messages(URL2) == 2)
+			assert(mock_msg.messages(URL1)[7].message_id == monarch.SCREEN_TRANSITION_OUT_STARTED)
 			assert(mock_msg.messages(URL1)[7].message.screen == SCREEN2)
+			assert(mock_msg.messages(URL1)[8].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL1)[8].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[9].message_id == monarch.SCREEN_TRANSITION_OUT_FINISHED)
+			assert(mock_msg.messages(URL1)[9].message.screen == SCREEN2)
+			assert(mock_msg.messages(URL1)[10].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[10].message.screen == SCREEN1)
 		end)
 	end)
 end