Added Timestep below Popup

Fixes #25

.luacheckrc

@@ -0,0 +1,42 @@
+std = "max"
+files['.luacheckrc'].global = false
+unused_args = false
+
+globals = {
+  "sys",
+  "go",
+  "gui",
+  "label",
+  "render",
+  "crash",
+  "sprite",
+  "sound",
+  "tilemap",
+  "spine",
+  "particlefx",
+  "physics",
+  "factory",
+  "collectionfactory",
+  "iac",
+  "msg",
+  "vmath",
+  "url",
+  "http",
+  "image",
+  "json",
+  "zlib",
+  "iap",
+  "push",
+  "facebook",
+  "hash",
+  "hash_to_hex",
+  "pprint",
+  "init",
+  "final",
+  "update",
+  "on_input",
+  "on_message",
+  "on_reload",
+  "window",
+  "unityads"
+}

.travis.yml

@@ -0,0 +1,28 @@
+sudo: required
+
+script:
+  - sudo unlink /usr/bin/gcc && sudo ln -s /usr/bin/gcc-5 /usr/bin/gcc
+  - gcc --version
+
+addons:
+  apt:
+    sources:
+    - ubuntu-toolchain-r-test
+    packages:
+    - gcc-5
+    - g++-5
+
+language: java
+
+jdk:
+  - oraclejdk8
+
+#DEFOLD_AUTH=auth token
+env:
+  global:
+    - secure: "1rVLsDcb7dFdgyB9D1JQDr4JhWSosoMvgYgrqZNPxJ/Du3qtY3bk6dgQim+g2fDMQpDOPCQ/EhmhtrLJrIgBhhvOcsrVKT8gl9ZnATw5tHGI6XTw3eod8WgsU8owlc7CaT3XaUgwVshmW3oB/257SDf6kHwsCv/gAJuCEL5RZp76BhTWsfyeDCgz5XXgWx4a21tcIWz96jxEsrYQKLLV2ne55CxU5Hw9IMU7Ig7pkGoYCf1g+iUEA39NC8nIrQibUoJj3yNB2u3ZFwGf2LuDjjkSIsyYWn1LzA2fQYw5uAcjiQ/aDkj6sAEvwrWsIsJhOon5cQBFIU6cIIN2oK3A7BA0zJj0EsTFPUMIeryyoqiuLUDoIvHD/eEqouNduP6Kml02Ql0pDZnjDy/+nzp2e7VA5Sd9Xg1XKd1mmHKx4nc2U+IcIDZWAerFKcqQqeZSwzz5igv07w5zYZ99KCSBMH2K/2H/CNekHa6SQQ29mC8D3lDXOfwEq3fAhsabgUGe2uAgUY1nKwJBKEi7r+KEROBr5ydkWenzbCXv3GNNsuCHKpNFuoZv3QMyjUjlPBxZVndNLSv85juhkBx6wXAh8CxTt78Y8GV0xI8oazSM065gpDmENGVqyO1bUn2CZF8YRC4MLfHK+245QN82ui+YOqVudTX8RGWnX0GFUncjaRQ="
+    - DEFOLD_USER=bjorn.ritzl@king.com
+    - DEFOLD_BOOSTRAP_COLLECTION=/test/test.collectionc
+
+script:
+  - "./.travis/run.sh"

.travis/run.sh

@@ -0,0 +1,43 @@
+
+if [ $# -eq 0 ]; then
+	PLATFORM="x86_64-linux"
+else
+	PLATFORM="$1"
+fi
+
+
+echo "${PLATFORM}"
+
+# {"version": "1.2.89", "sha1": "5ca3dd134cc960c35ecefe12f6dc81a48f212d40"}
+# Get SHA1 of the current Defold stable release
+SHA1=$(curl -s http://d.defold.com/stable/info.json | sed 's/.*sha1": "\(.*\)".*/\1/')
+echo "Using Defold dmengine_headless version ${SHA1}"
+
+# Create dmengine_headless and bob.jar URLs
+DMENGINE_URL="http://d.defold.com/archive/${SHA1}/engine/${PLATFORM}/dmengine_headless"
+BOB_URL="http://d.defold.com/archive/${SHA1}/bob/bob.jar"
+
+# Download dmengine_headless
+echo "Downloading ${DMENGINE_URL}"
+curl -o dmengine_headless ${DMENGINE_URL}
+chmod +x dmengine_headless
+
+# Download bob.jar
+echo "Downloading ${BOB_URL}"
+curl -o bob.jar ${BOB_URL}
+
+# Fetch libraries if DEFOLD_AUTH and DEFOLD_USER are set
+if [ -n "${DEFOLD_AUTH}" ] && [ -n "${DEFOLD_USER}" ]; then
+	echo "Running bob.jar - resolving dependencies"
+	java -jar bob.jar --auth "${DEFOLD_AUTH}" --email "${DEFOLD_USER}" resolve
+fi
+
+echo "Running bob.jar - building"
+java -jar bob.jar --debug build --keep-unused
+
+echo "Starting dmengine_headless"
+if [ -n "${DEFOLD_BOOSTRAP_COLLECTION}" ]; then
+	./dmengine_headless --config=bootstrap.main_collection=${DEFOLD_BOOSTRAP_COLLECTION}
+else
+	./dmengine_headless
+fi

CHANGELOG.md

@@ -0,0 +1,60 @@
+## Monarch 2.8.0 [britzl released 2018-06-10]
+NEW: Prevent show/hide operations while busy showing/hiding another screen  
+FIX: Make sure to properly finish active transitions when layout changes
+
+## Monarch 2.7.0 [britzl released 2018-06-04]
+NEW: Added monarch.top([offset]) and monarch.bottom([offset]) to get screen id of top and bottom screens (w. optional offset)  
+NEW: Transition messages now contain `next_screen` or `previous_screen`
+
+## Monarch 2.6.1 [britzl released 2018-06-04]
+FIX: Check if screen has already been preloaded before trying to preload it again (the callback will still be invoked).
+
+## Monarch 2.6.0 [britzl released 2018-06-03]
+NEW: monarch.preload() to load but not show a screen. Useful for content heavy screens that you wish to show without delay.
+
+## Monarch 2.5.0 [britzl released 2018-06-01]
+NEW: Transitions will send a `transition_done` message to the creator of the transition to notify that the transition has finished. The `message` will contain which transition that was finished.
+
+## Monarch 2.4.0 [britzl released 2018-05-26]
+NEW: Screen transitions are remembered so that they can be replayed when the screen layout changes.
+
+## Monarch 2.3.0 [britzl released 2018-03-24]
+CHANGE: The functions in monarch.lua that previously only accepted a hash as screen id now also accepts strings (and does the conversion internally)
+
+## Monarch 2.2.0 [britzl released 2018-03-19]
+NEW: Transitions now handle layout changes (via `layout_changed` message)  
+NEW: Transitions can now be notified of changes in window size using transition.window_resize(width, height)
+
+## Monarch 2.1 [britzl released 2017-12-27]
+NEW: Added Popup on Popup flag that allows a popup to be shown on top of another popup
+
+## Monarch 2.0 [britzl released 2017-12-08]
+BREAKING CHANGE: If you are using custom screen transitions (ie your own transition functions) you need to make a change to the function. The previous function signature was ```(node, to, easing, duration, delay, url)``` where ```url``` was the URL  to where the ```transition_done``` message was supposed to be posted. The new function signature for a transition function is: ```(node, to, easing, duration, delay, cb)``` where ```cb``` is a function that should be invoked when the transition is completed.  
+  
+FIX: Fixed issues related to screen transitions.  
+FIX: Code cleanup to reduce code duplication.  
+FIX: Improved documentation regarding transitions.
+
+## Monarch 1.4 [britzl released 2017-12-06]
+FIX: Several bugfixes for specific corner cases.
+
+## Monarch 1.3 [britzl released 2017-12-01]
+FIX: monarch.back(data, cb) set the data on the previous screen not the new current screen.  
+NEW: monarch.is_top(id)  
+NEW: monarch.get_stack()  
+NEW: monarch.in_stack(id)
+
+## Monarch 1.2 [britzl released 2017-11-28]
+NEW: Message id constants exposed from the Monarch module  
+NEW: Focus lost/gained contains id of next/previous screen
+
+## Monarch 1.1 [britzl released 2017-11-22]
+FIX: Bugfixes for transitions and state under certain circumstances  
+NEW: Added 'reload' option to show() command.
+
+## Monarch 1.0 [britzl released 2017-09-28]
+First public stable release
+
+## Monarch 0.9 [britzl released 2017-09-17]
+
+

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Björn Ritzl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,81 +1,136 @@
+![](docs/logo.jpg)
+
+[![Build Status](https://travis-ci.org/britzl/monarch.svg?branch=master)](https://travis-ci.org/britzl/monarch)
+[![Latest Release](https://img.shields.io/github/release/britzl/monarch.svg)](https://github.com/britzl/monarch/releases)
+
 # Monarch
 Monarch is a screen manager for the [Defold](https://www.defold.com) game engine.
 
+
 # Installation
 You 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:
 
 https://github.com/britzl/monarch/archive/master.zip
 
+Or point to the ZIP file of a [specific release](https://github.com/britzl/monarch/releases).
+
+
 # Usage
 Using 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.
 
-## 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:
 
-* **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)
-* **Transition Show In (url)** - Optional URL to call when the screen is about to be shown. Use this to trigger a transition (see the section on [transitions](#transitions))
-* **Transition Show Out (url)** - Optional URL to call when the screen is about to be hidden. Use this to trigger a transition (see the section on [transitions](#transitions))
-* **Transition Back In (url)** - Optional URL to call when the screen is about to be shown when navigating back in the screen hierarchy. Use this to trigger a transition (see the section on [transitions](#transitions))
-* **Transition Back Out (url)** - Optional URL to call when the screen is about to be hidden when navigating back in the screen hierarchy. Use this to trigger a transition (see the section on [transitions](#transitions))
+## 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:
+
+* **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)).
+
+![](docs/setup.png)
 
 
 ## 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:
 
 * Showing screen A
-* Stack is [A]
+* Stack is ```[A]```
 * Showing screen B
-* Stack is [A, B] - (B is on top)
+* Stack is ```[A, B]``` - (B is on top)
 * Going back
-* Stack is [A]
+* Stack is ```[A]```
 
 ### Showing a new screen
 You show a screen in one of two ways:
 
-1. Post a ````show```` message to the ````screen.script````
-2. Call ````monarch.show(screen_id, [options], [callback])````
+1. Post a ```show``` message to the ```screen.script```
+2. Call ```monarch.show()``` (see below)
 
 Showing 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).
 
-#### Preventing duplicates in the stack
-You 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:
+NOTE: You must ensure that the ```init()``` function of the ```screen.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:
 
-* Stack is [A, B, C, D] - (D is on top)
-* A call to ````monarch.show(B, { clear = true })```` is made
-* Stack is [A, B]
+	function init(self)
+		msg.post("#", "show_first_screen")
+	end
+
+	function on_message(self, message_id, message, sender)
+		monarch.show(hash("first_screen"))
+	end
+
+#### Preventing duplicates in the stack
+You 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:
+
+* Stack is ```[A, B, C, D]``` - (D is on top)
+* A call to ```monarch.show(B, { clear = true })``` is made
+* Stack is ```[A, B]```
+
+As opposed to if the ```clear``` flag was not set:
+
+* Stack is ```[A, B, C, D]``` - (D is on top)
+* A call to ```monarch.show(B, { clear = false })``` is made
+* Stack is ```[A, B, C, D, B]``` - (B is on top)
 
 ### Going back to a previous screen
 You navigate back in the screen hierarchy in one of two ways:
 
-1. Post a ````back```` message to the ````screen.script````
-2. Call ````monarch.back()````
+1. Post a ```back``` message to the ```screen.script```
+2. Call ```monarch.back()``` (see below)
 
 
 ## Input focus
-Monarch will acquire and release input focus on the screens and ensure that only the top-most screen will ever have input focus.
+Monarch 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.
 
 ## Popups
-A screen that is flagged as a popup (see list of screen properties above) will be treated slightly differently when it comes to navigation. If a popup is at the top of the stack (ie currently shown) and another screen or popup is shown then the current popup will be removed from the stack. This means that it is not possible to have a popup anywhere in the stack but the top. This also means that you cannot navigate back to a popup since popups can only exist on the top of the stack. Another important difference between normal screens and popups is that when 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.
+A 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.
+
+### Popup on normal screen
+If 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:
+
+* Stack is ```[A, B]```
+* A call to ```monarch.show(C)``` is made and C is a popup
+* Stack is ```[A, B, C]``` and B will still be visible
+
+### Popup on popup
+If 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.
+
+* Stack is ```[A, B, C]``` and C is a popup
+* A call to ```monarch.show(D)``` is made and D is a popup with the popup on popup flag set
+* Stack is ```[A, B, C, D]```
+
+If 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).
+
+* Stack is ```[A, B, C]``` and C is a popup
+* A call to ```monarch.show(D)``` is made and D is a popup without the popup on popup flag set
+* Stack is ```[A, B, D]```
+
+### Screen on popup
+If a screen is shown on top of one or more popups they will all be removed from the stack:
+
+* Stack is ```[A, B, C, D]``` and C and D are popups
+* A call to ```monarch.show(E)``` is made and E is not a popup
+* Stack is ```[A, B, E]```
 
-* Stack is [A, B]
-* A call to ````monarch.show(C)```` is made and C is a popup
-* Stack is [A, B, C]
-* A call to ````monarch.show(D)````
-* Stack is [A, B, D]
 
 ## Transitions
-You can add optional transitions when navigating between screens. The default behavior is that screen navigation is instant but if you have defined a transition for a screen Monarch will wait until the transition is completed before proceeding. The Transition Show In/Out and Transition Back In/Out properties described above should be URLs to one or more scripts with on_message handlers for the following messages:
+You can add optional transitions when navigating between screens. The default behavior is that screen navigation is instant but if you have defined a transition for a screen Monarch will wait until the transition is completed before proceeding. The Transition Url property described above should be the URL to a script with an ```on_message``` handlers for the following messages:
 
-* ````transition_show_in````
-* ````transition_show_out````
-* ````transition_back_in````
-* ````transition_back_out````
+* ```transition_show_in``` (constant defined as ```monarch.TRANSITION.SHOW_IN```)
+* ```transition_show_out``` (constant defined as ```monarch.TRANSITION.SHOW_OUT```)
+* ```transition_back_in``` (constant defined as ```monarch.TRANSITION.BACK_IN```)
+* ```transition_back_out``` (constant defined as ```monarch.TRANSITION.BACK_OUT```)
 
-When a transition is completed it is up to the developer to send a ````transition_done```` message back to the sender to indicate that the transition is completed and that Monarch can continue the navigation sequence. Monarch comes with a system for setting up transitions easily in a gui_script. Example:
+When a transition is completed it is up to the developer to send a ```transition_done``` (constant ```monarch.TRANSITION.DONE```) message back to the sender to indicate that the transition is completed and that Monarch can continue the navigation sequence.
+
+
+### Predefined transitions
+Monarch comes with a system for setting up transitions easily in a gui_script using the ```monarch.transitions.gui``` module. Example:
 
 	local transitions = require "monarch.transitions.gui"
+	local monarch = require "monarch.monarch"
 
 	function init(self)
 		-- create transitions for the node 'root'
@@ -90,7 +145,244 @@ When a transition is completed it is up to the developer to send a ````transitio
 
 	function on_message(self, message_id, message, sender)
 		self.transition.handle(message_id, message, sender)
+		-- you can also check when a transition has completed:
+		if message_id == monarch.TRANSITION.DONE and message.transition == monarch.TRANSITION.SHOW_IN then
+			print("Show in done!")
+		end
 	end
 
+The predefined transitions provided by ```monarch.transitions.gui``` are:
+
+* ```slide_in_right```
+* ```slide_in_left```
+* ```slide_in_top```
+* ```slide_in_bottom```
+* ```slide_out_right```
+* ```slide_out_left```
+* ```slide_out_top```
+* ```slide_out_bottom```
+* ```scale_in```
+* ```scale_out```
+* ```fade_in``` - 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:
+
+* ```transitions.in_right_out_left(node, duration, [delay], [easing])```
+* ```transitions.in_left_out_right(node, duration, [delay], [easing])```
+* ```transitions.in_left_out_left(node, duration, [delay], [easing])```
+* ```transitions.in_right_out_right(node, duration, [delay], [easing])```
+* ```transitions.fade_in_out(node, duration, [delay], [easing])```
+
+**PARAMETERS**
+* ```node``` (node) - Gui node to animate.
+* ```duration``` (number) - Transition duration in seconds.
+* ```delay``` (number) - Transition delay in seconds.
+* ```easing``` (table) - Easing table, created from a function provided by ```monarch.transitions.easings```
+
+**RETURN**
+* ```instance``` - The created transition instance
+
+
+### Custom transitions
+You can create and use your own transition as long as the provided transition function has the following function signature:
+
+	custom_transition(node, to, easing, duration, delay, cb)
+
+**PARAMETERS**
+* ```node``` (node) - Gui node to animate.
+* ```to``` (vector3) - Target position.
+* ```easing``` (number) - One of gui.EASING_* constants.
+* ```duration``` (number) - Transition duration in seconds.
+* ```delay``` (number) - Transition delay in seconds.
+* ```cb``` (function) - This function must be called when the transition is completed.
+
+
+### Dynamic orientation and resized windows
+When using dynamic screen orientation together with gui layouts or using transitions on a platform where the window can be resized it's important to make sure that the created transitions adapt to the change in orientation or window size. The transition system takes care of layout changes automatically, but when it comes to changes in window size you need to notify the transition manually:
+
+	local transitions = require "monarch.transitions.gui"
+
+	function init(self)
+		self.transition = transitions.create(gui.get_node("root"))
+	end
+
+	function on_message(self, message_id, message, sender)
+		if message_id == hash("my_resize_message") then
+			self.transition.window_resized(message.width, message.height)
+		end
+	end
+
+
+### Screen stack info and transitions
+The transition message sent to the Transition Url specified in the screen configuration contains additional information about the transition. For the ```transition_show_in``` and ```transition_back_out``` messages the message contains the previous screen id:
+
+	function on_message(self, message_id, message, sender)
+		if message_id == hash("transition_show_in") or message_id == hash("transition_back_out") then
+			print(message.previous_screen)
+		end
+	end
+
+For the ```transition_show_out``` and ```transition_back_in``` messages the message contains the next screen id:
+
+	function on_message(self, message_id, message, sender)
+		if message_id == hash("transition_show_out") or message_id == hash("transition_back_in") then
+			print(message.next_screen)
+		end
+	end
+
+This information can be used to create dynamic transitions where the direction of the transition depends on the previous/next screen
+
+
+## Screen focus gain/loss
+Monarch will send focus gain and focus loss messages if a Focus Url was provided when the screen was created. The 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:
+
+	local monarch = require "monarch.monarch"
+
+	function on_message(self, message_id, message, sender)
+		if message_id == monarch.FOCUS.GAINED then
+			print("Focus gained, previous screen: ", message.id)
+		elseif message_id == monarch.FOCUS.LOST then
+			print("Focus lost, next screen: ", message.id)
+		end
+	end
+
+
 ## Callbacks
-Both the ```monarch.show()``` and ```monarch.back()``` functions take an optional callback function that will be invoked when the transition is completed. Note that this will not take into account when custom transitions are completed. The callback will be invoked immediately when the loading and unloading of collections are done and when the internal state of Monarch has completed the navigation.
+Both 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).
+
+
+## Monarch API
+
+### monarch.show(screen_id, [options], [data], [callback])
+Show a Monarch screen. Note that the screen must be registered before it can be shown. The ```init()``` function of the ```screen.script``` takes care of registration.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to show.
+* ```options``` (table) - Options when showing the new screen (see below).
+* ```data``` (table) - Optional data to associate with the screen.  Retrieve using ```monarch.data()```.
+* ```callback``` (function) - Optional function to call when the new screen is visible.
+
+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.
+* ```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).
+
+**RETURN**
+* ```success``` (boolean) - True if the process of showing the screen was started successfully. False if already busy showing/hiding a screen.
+
+
+### monarch.back([data], [callback])
+Go back to a previous Monarch screen
+
+**PARAMETERS**
+* ```data``` (table) - Optional data to associate with the screen you are going back to.  Retrieve using ```monarch.data()```.
+* ```callback``` (function) - Optional function to call when the previous screen is visible.
+
+**RETURN**
+* ```success``` (boolean) - True if the process of going back to a previous screen was started successfully. False if already busy showing/hiding a screen.
+
+
+### monarch.preload(screen_id, [callback])
+Preload a Monarch screen. This will load but not enable the screen. This is useful for content heavy screens that you wish to be able to show without having to wait for it load.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to preload.
+* ```callback``` (function) - Optional function to call when the new screen is preloaded.
+
+
+### monarch.top([offset])
+Get the id of the screen at the top of the stack.
+
+**PARAMETERS**
+* ```offset``` (number) - Optional offset from the top of the stack, ie -1 to get the previous screen
+
+**RETURN**
+* ```screen_id``` (hash) - Id of the requested screen
+
+
+### monarch.bottom([offset])
+Get the id of the screen at the bottom of the stack.
+
+**PARAMETERS**
+* ```offset``` (number) - Optional offset from the bottom of the stack
+
+**RETURN**
+* ```screen_id``` (hash) - Id of the requested screen
+
+
+### monarch.data(screen_id)
+Get the data associated with a screen (from a call to ```monarch.show()``` or ```monarch.back()```).
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to get data for
+
+**RETURN**
+* ```data``` (table) - Data associated with the screen.
+
+
+### monarch.screen_exists(screen_id)
+Check if a Monarch screen exists.
+
+**PARAMETERS**
+* ```screen_id``` (hash) - Id of the screen to get data for
+
+**RETURN**
+* ```exists``` (boolean) - True if the screen exists.
+
+
+### monarch.is_busy()
+Check if Monarch is busy showing and/or hiding a screen.
+
+**RETURN**
+* ```busy``` (boolean) - True if busy hiding and/or showing a screen.
+
+
+### monarch.add_listener([url])
+Add a URL that will be notified of navigation events.
+
+**PARAMETERS**
+* ```url``` (url) - URL to send navigation events to. Will use current URL if omitted.
+
+
+### monarch.remove_listener([url])
+Remove a previously added listener.
+
+**PARAMETERS**
+* ```url``` (url) - URL to remove. Will use current URL if omitted.
+
+
+### monarch.debug()
+Enable verbose logging of the internals of Monarch.
+
+
+### monarch.SCREEN_TRANSITION_IN_STARTED
+Message sent to listeners when a screen has started to transition in.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```previous_screen``` (hash) - Id of the previous screen (if any)
+
+
+### monarch.SCREEN_TRANSITION_IN_FINISHED
+Message sent to listeners when a screen has finished to transition in.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```previous_screen``` (hash) - Id of the previous screen (if any)
+
+
+### monarch.SCREEN_TRANSITION_OUT_STARTED
+Message sent to listeners when a screen has started to transition out.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```next_screen``` (hash) - Id of the next screen (if any)
+
+
+### monarch.SCREEN_TRANSITION_OUT_FINISHED
+Message sent to listeners when a screen has finished to transition out.
+
+**PARAMETERS**
+* ```screen``` (hash) - Id of the screen
+* ```next_screen``` (hash) - Id of the next screen (if any)

example/about.collection

@@ -0,0 +1,37 @@
+name: "about"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"about\"\n"
+  "  component: \"/example/about.gui\"\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/about.gui

@@ -0,0 +1,603 @@
+script: "/example/about.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.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: 400.0
+    y: 300.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.3019608
+    y: 0.3019608
+    z: 0.3019608
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "root"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 120.0
+    y: -112.414
+    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: 110.0
+    y: 50.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: "ok_reload_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "OK, reload"
+  font: "example"
+  id: "ok_reload_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "ok_reload_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 380.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "When clicking OK the menu will be shown again using monarch.show()"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: true
+  parent: "root"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: -0.0
+    y: -112.414
+    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: 110.0
+    y: 50.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: "ok_clear_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "OK, clear"
+  font: "example"
+  id: "ok_clear_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "ok_clear_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: -120.0
+    y: -112.414
+    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: 110.0
+    y: 50.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: "ok_clearreload_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 100.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "OK, clear and reload"
+  font: "example"
+  id: "ok_clearreload_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: true
+  parent: "ok_clearreload_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: 120.0
+    y: -54.414
+    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: 110.0
+    y: 50.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: "ok_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "OK"
+  font: "example"
+  id: "ok_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "ok_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

example/about.gui_script

@@ -0,0 +1,31 @@
+local monarch = require "monarch.monarch"
+local transitions = require "monarch.transitions.gui"
+
+function init(self)
+	msg.post(".", "acquire_input_focus")
+	gui.set_render_order(15)
+
+	self.transition = transitions.create(gui.get_node("root"))
+		.show_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
+		.show_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
+		.back_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
+		.back_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
+end
+
+function on_input(self, action_id, action)
+	if action_id == hash("touch") and action.released then
+		if gui.pick_node(gui.get_node("ok_reload_button"), action.x, action.y) then
+			monarch.show(hash("menu"), { reload = true })
+		elseif gui.pick_node(gui.get_node("ok_clear_button"), action.x, action.y) then
+			monarch.show(hash("menu"), { clear = true })
+		elseif gui.pick_node(gui.get_node("ok_clearreload_button"), action.x, action.y) then
+			monarch.show(hash("menu"), { clear = true, reload = true })
+		elseif gui.pick_node(gui.get_node("ok_button"), action.x, action.y) then
+			monarch.show(hash("menu"))
+		end
+	end
+end
+
+function on_message(self, message_id, message, sender)
+	self.transition.handle(message_id, message, sender)
+end

example/confirm.collection

@@ -0,0 +1,37 @@
+name: "confirm"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"confirm\"\n"
+  "  component: \"/example/confirm.gui\"\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/confirm.gui

@@ -0,0 +1,367 @@
+script: "/example/confirm.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.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: 350.0
+    y: 200.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.4
+    y: 0.4
+    z: 0.4
+    w: 1.0
+  }
+  type: TYPE_BOX
+  blend_mode: BLEND_MODE_ALPHA
+  texture: ""
+  id: "root"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 85.0
+    y: -65.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: 150.0
+    y: 50.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: "yes_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 50.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "YES"
+  font: "example"
+  id: "yes_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "yes_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: -85.0
+    y: -65.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: 150.0
+    y: 50.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: "no_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 50.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "NO"
+  font: "example"
+  id: "no_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "no_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "Are you sure?"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "root"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

example/confirm.gui_script

@@ -0,0 +1,35 @@
+local monarch = require "monarch.monarch"
+local transitions = require "monarch.transitions.gui"
+
+function init(self)
+	msg.post(".", "acquire_input_focus")
+	self.yes = gui.get_node("yes_button")
+	self.no = gui.get_node("no_button")
+	gui.set_render_order(15)
+
+	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)
+		.back_in(transitions.scale_in, gui.EASING_OUTBACK, 0.3, 0)
+		.back_out(transitions.scale_out, gui.EASING_INBACK, 0.3, 0)
+end
+
+function on_input(self, action_id, action)
+	if action_id == hash("touch") and action.released then
+		if gui.pick_node(self.yes, action.x, action.y) then
+			print("yes")
+			monarch.show(monarch.data(hash("confirm")).next, nil, nil, function()
+				print("next screen show done")
+			end)
+		elseif gui.pick_node(self.no, action.x, action.y) then
+			print("no")
+			monarch.back(function()
+				print("back from popup done")
+			end)
+		end
+	end
+end
+
+function on_message(self, message_id, message, sender)
+	self.transition.handle(message_id, message, sender)
+end

example/example.collection

@@ -1,4 +1,4 @@
-name: "main"
+name: "example"
 scale_along_z: 0
 embedded_instances {
   id: "menu"
@@ -22,22 +22,17 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
+  "    id: \"timestep_below_popup\"\n"
+  "    value: \"0.0\"\n"
+  "    type: PROPERTY_TYPE_NUMBER\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"transition_url\"\n"
   "    value: \"menu:/go#menu\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"menu:/go#menu\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"menu:/go#menu\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"focus_url\"\n"
   "    value: \"menu:/go#menu\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -96,7 +91,7 @@ embedded_instances {
   "  }\n"
   "}\n"
   "components {\n"
-  "  id: \"main1\"\n"
+  "  id: \"gui\"\n"
   "  component: \"/example/debug.gui\"\n"
   "  position {\n"
   "    x: 0.0\n"
@@ -150,22 +145,7 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"pregame:/go#pregame\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"pregame:/go#pregame\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"pregame:/go#pregame\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"pregame:/go#pregame\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -228,22 +208,7 @@ embedded_instances {
   "    type: PROPERTY_TYPE_HASH\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"game:/go#game\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"game:/go#game\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"game:/go#game\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"game:/go#game\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -311,22 +276,12 @@ embedded_instances {
   "    type: PROPERTY_TYPE_BOOLEAN\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_in\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
+  "    id: \"timestep_below_popup\"\n"
+  "    value: \"0.0\"\n"
+  "    type: PROPERTY_TYPE_NUMBER\n"
   "  }\n"
   "  properties {\n"
-  "    id: \"transition_show_out\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_in\"\n"
-  "    value: \"popup:/go#popup\"\n"
-  "    type: PROPERTY_TYPE_URL\n"
-  "  }\n"
-  "  properties {\n"
-  "    id: \"transition_back_out\"\n"
+  "    id: \"transition_url\"\n"
   "    value: \"popup:/go#popup\"\n"
   "    type: PROPERTY_TYPE_URL\n"
   "  }\n"
@@ -367,3 +322,144 @@ embedded_instances {
     z: 1.0
   }
 }
+embedded_instances {
+  id: "about"
+  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: \"about\"\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: \"about:/go#about\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/example/about.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: "confirm"
+  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: \"confirm\"\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_url\"\n"
+  "    value: \"confirm:/go#confirm\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/example/confirm.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
+  }
+}

example/example.display_profiles

@@ -0,0 +1,14 @@
+profiles {
+  name: "Landscape"
+  qualifiers {
+    width: 1136
+    height: 640
+  }
+}
+profiles {
+  name: "Portrait"
+  qualifiers {
+    width: 640
+    height: 1136
+  }
+}

example/game.gui

@@ -181,6 +181,69 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 320.0
+    y: 1050.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "<text>"
+  font: "example"
+  id: "level"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "root"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/game.gui_script

@@ -4,17 +4,16 @@ local transitions = require "monarch.transitions.gui"
 function init(self)
 	msg.post(".", "acquire_input_focus")
 	
-	self.transition = transitions.create(gui.get_node("root"))
-		.show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
-		.show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
-		.back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
-		.back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)
+	local data = monarch.data(hash("game"))
+	gui.set_text(gui.get_node("level"), tostring(data.level))
+
+	self.transition = transitions.in_right_out_left(gui.get_node("root"), 0.6, 0)
 end
 
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(gui.get_node("win_button"), action.x, action.y) then
-			monarch.show(hash("menu"), { clear = true }, function()
+			monarch.show(hash("menu"), { clear = true }, nil, function()
 				print("showing menu done")
 			end)
 		end

example/main.script

@@ -1,6 +1,13 @@
 local monarch = require "monarch.monarch"
 
 function init(self)
-	monarch.show(hash("menu"))
+	monarch.debug()
 	msg.post("@render:/", "clear_color", { color = vmath.vector4(0.4, 0.6, 0.8,1.0) })
+	msg.post("#", "init_monarch") -- wait until init() has been called for all screen.script instances
+end
+
+function on_message(self, message_id, message, sender)
+	if message_id == hash("init_monarch") then
+		monarch.show(hash("menu"))
+	end
 end

example/menu.gui

@@ -181,6 +181,598 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 499.0
+    y: 1078.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: 200.0
+    y: 50.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: "about_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "ABOUT"
+  font: "example"
+  id: "about_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "about_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: 138.0
+    y: 1078.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: 200.0
+    y: 50.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: "back_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "BACK"
+  font: "example"
+  id: "back_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "back_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 1024.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "<text>"
+  font: "example"
+  id: "timestamp"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "root"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  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: ""
+  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
+}
 material: "/builtins/materials/gui.material"
+layouts {
+  name: "Landscape"
+  nodes {
+    position {
+      x: 568.0
+      y: 320.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: 200.0
+      y: 50.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: "startgame_button"
+    xanchor: XANCHOR_NONE
+    yanchor: YANCHOR_NONE
+    pivot: PIVOT_CENTER
+    adjust_mode: ADJUST_MODE_FIT
+    parent: "root"
+    layer: ""
+    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
+    overridden_fields: 1
+    template_node_child: false
+    size_mode: SIZE_MODE_MANUAL
+  }
+  nodes {
+    position {
+      x: 977.0
+      y: 570.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: 200.0
+      y: 50.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: "about_button"
+    xanchor: XANCHOR_NONE
+    yanchor: YANCHOR_NONE
+    pivot: PIVOT_CENTER
+    adjust_mode: ADJUST_MODE_FIT
+    parent: "root"
+    layer: ""
+    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
+    overridden_fields: 1
+    template_node_child: false
+    size_mode: SIZE_MODE_MANUAL
+  }
+  nodes {
+    position {
+      x: 150.0
+      y: 570.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: 200.0
+      y: 50.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: "back_button"
+    xanchor: XANCHOR_NONE
+    yanchor: YANCHOR_NONE
+    pivot: PIVOT_CENTER
+    adjust_mode: ADJUST_MODE_FIT
+    parent: "root"
+    layer: ""
+    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
+    overridden_fields: 1
+    template_node_child: false
+    size_mode: SIZE_MODE_MANUAL
+  }
+  nodes {
+    position {
+      x: 568.0
+      y: 570.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: 200.0
+      y: 100.0
+      z: 0.0
+      w: 1.0
+    }
+    color {
+      x: 1.0
+      y: 1.0
+      z: 1.0
+      w: 1.0
+    }
+    type: TYPE_TEXT
+    blend_mode: BLEND_MODE_ALPHA
+    text: "<text>"
+    font: "example"
+    id: "timestamp"
+    xanchor: XANCHOR_NONE
+    yanchor: YANCHOR_NONE
+    pivot: PIVOT_CENTER
+    outline {
+      x: 1.0
+      y: 1.0
+      z: 1.0
+      w: 1.0
+    }
+    shadow {
+      x: 1.0
+      y: 1.0
+      z: 1.0
+      w: 1.0
+    }
+    adjust_mode: ADJUST_MODE_FIT
+    line_break: false
+    parent: "root"
+    layer: ""
+    inherit_alpha: true
+    alpha: 1.0
+    outline_alpha: 1.0
+    shadow_alpha: 1.0
+    overridden_fields: 1
+    template_node_child: false
+    text_leading: 1.0
+    text_tracking: 0.0
+  }
+}
+layouts {
+  name: "Portrait"
+}
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/menu.gui_script

@@ -4,23 +4,32 @@ local transitions = require "monarch.transitions.gui"
 function init(self)
 	msg.post(".", "acquire_input_focus")
 
-	self.transition = transitions.create(gui.get_node("root"))
-		.show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
-		.show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
-		.back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
-		.back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)
+	gui.set_text(gui.get_node("timestamp"), os.date())
+
+	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)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(gui.get_node("startgame_button"), action.x, action.y) then
-			monarch.show(hash("popup"), nil, function()
+			monarch.show(hash("popup"), nil, nil, function()
 				print("showing popup done")
 			end)
+		elseif gui.pick_node(gui.get_node("about_button"), action.x, action.y) then
+			monarch.show(hash("about"), nil, nil, function()
+			print("showing about done")
+			end)
+		elseif gui.pick_node(gui.get_node("back_button"), action.x, action.y) then
+			monarch.back()
 		end
 	end
 end
 
 function on_message(self, message_id, message, sender)
 	self.transition.handle(message_id, message, sender)
+	if message_id == monarch.FOCUS.GAINED then
+		gui.set_text(gui.get_node("timestamp"), os.date())
+	end
 end

example/popup.gui

@@ -299,6 +299,179 @@ nodes {
   text_leading: 1.0
   text_tracking: 0.0
 }
+nodes {
+  position {
+    x: 2.419
+    y: -14.414
+    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: 150.0
+    y: 50.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: "about_button"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  parent: "root"
+  layer: ""
+  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
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "ABOUT"
+  font: "example"
+  id: "about_text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "about_button"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  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: ""
+  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
+}
 material: "/builtins/materials/gui.material"
 adjust_reference: ADJUST_REFERENCE_PARENT
 max_nodes: 512

example/popup.gui_script

@@ -5,27 +5,35 @@ function init(self)
 	msg.post(".", "acquire_input_focus")
 	self.ok = gui.get_node("ok_button")
 	self.cancel = gui.get_node("cancel_button")
-	gui.set_render_order(16)
+	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.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
-		.show_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
-		.back_in(transitions.slide_in_top, gui.EASING_OUTQUAD, 0.6, 0)
-		.back_out(transitions.slide_out_top, gui.EASING_INQUAD, 0.6, 0)
+		.show_in(transitions.scale_in, gui.EASING_OUTBACK, 0.3, 0)
+		.show_out(transitions.scale_out, gui.EASING_INBACK, 0.3, 0)
+		.back_in(transitions.scale_in, gui.EASING_OUTBACK, 0.3, 0)
+		.back_out(transitions.scale_out, gui.EASING_INBACK, 0.3, 0)
 end
 
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(self.ok, action.x, action.y) then
 			print("ok")
-			monarch.show(hash("pregame"), nil, function()
-				print("pregame show done")
+			monarch.show(hash("confirm"), nil, { next = hash("pregame") }, function()
+				print("confirm show done")
 			end)
 		elseif gui.pick_node(self.cancel, action.x, action.y) then
 			print("cancel")
 			monarch.back(function()
 				print("back from popup done")
 			end)
+		elseif gui.pick_node(self.about, action.x, action.y) then
+			print("about")
+			monarch.show(hash("about"), { clear = true, reload = true }, nil, function()
+				print("about show done")
+			end)
 		end
 	end
 end

example/pregame.gui_script

@@ -6,18 +6,14 @@ function init(self)
 	self.play = gui.get_node("play_button")
 	self.back = gui.get_node("back_button")
 	
-	self.transition = transitions.create(gui.get_node("root"))
-		.show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
-		.show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
-		.back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
-		.back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)
+	self.transition = transitions.in_right_out_left(gui.get_node("root"), 0.6, 0)
 end
 
 function on_input(self, action_id, action)
 	if action_id == hash("touch") and action.released then
 		if gui.pick_node(self.play, action.x, action.y) then
 			print("play")
-			monarch.show(hash("game"), nil, function()
+			monarch.show(hash("game"), nil, { level = 1 }, function()
 				print("showing game done")
 			end)
 		elseif gui.pick_node(self.back, action.x, action.y) then

game.project

@@ -1,9 +1,10 @@
 [project]
 title = Monarch
 version = 0.9
+dependencies = https://github.com/britzl/deftest/archive/2.3.0.zip
 
 [bootstrap]
-main_collection = /example/main.collectionc
+main_collection = /example/example.collectionc
 
 [input]
 game_binding = /input/game.input_bindingc
@@ -11,6 +12,8 @@ game_binding = /input/game.input_bindingc
 [display]
 width = 640
 height = 1136
+dynamic_orientation = 1
+display_profiles = /example/example.display_profilesc
 
 [script]
 shared_state = 1
@@ -24,3 +27,6 @@ bundle_identifier = com.example.todo
 [library]
 include_dirs = monarch
 
+[physics]
+world_count = 5
+

monarch/monarch.lua

@@ -1,12 +1,74 @@
+local callback_tracker = require "monarch.utils.callback_tracker"
+
 local M = {}
 
+local CONTEXT = hash("monarch_context")
+local PROXY_LOADED = hash("proxy_loaded")
+local PROXY_UNLOADED = hash("proxy_unloaded")
+
+local RELEASE_INPUT_FOCUS = hash("release_input_focus")
+local ACQUIRE_INPUT_FOCUS = hash("acquire_input_focus")
+local ASYNC_LOAD = hash("async_load")
+local UNLOAD = hash("unload")
+local ENABLE = hash("enable")
+
+-- transition messages
+M.TRANSITION = {}
+M.TRANSITION.DONE = hash("transition_done")
+M.TRANSITION.SHOW_IN = hash("transition_show_in")
+M.TRANSITION.SHOW_OUT = hash("transition_show_out")
+M.TRANSITION.BACK_IN = hash("transition_back_in")
+M.TRANSITION.BACK_OUT = hash("transition_back_out")
+
+-- focus messages
+M.FOCUS = {}
+M.FOCUS.GAINED = hash("monarch_focus_gained")
+M.FOCUS.LOST = hash("monarch_focus_lost")
+
+-- listener messages
+M.SCREEN_TRANSITION_IN_STARTED = hash("monarch_screen_transition_in_started")
+M.SCREEN_TRANSITION_IN_FINISHED = hash("monarch_screen_transition_in_finished")
+M.SCREEN_TRANSITION_OUT_STARTED = hash("monarch_screen_transition_out_started")
+M.SCREEN_TRANSITION_OUT_FINISHED = hash("monarch_screen_transition_out_finished")
+
+
+-- all registered screens
 local screens = {}
 
+-- the current stack of screens
 local stack = {}
 
+-- navigation listeners
+local listeners = {}
+
+-- the number of active transitions
+-- monarch is considered busy while there are active transitions
+local active_transition_count = 0
+
+
+local function log(...) end
+
+function M.debug()
+	log = print
+end
+
+-- use a lookup table for so we don't have to do "return (type(s) == "string" and hash(s) or s)"
+-- every time
+local hash_lookup = {}
+local function tohash(s)
+	hash_lookup[s] = hash_lookup[s] or (type(s) == "string" and hash(s) or s)
+	return hash_lookup[s]
+end
+
+local function notify_listeners(message_id, message)
+	log("notify_listeners()", message_id)
+	for _,url in pairs(listeners) do
+		msg.post(url, message_id, message or {})
+	end
+end
 
 local function screen_from_proxy(proxy)
-	for id,screen in pairs(screens) do
+	for _,screen in pairs(screens) do
 		if screen.proxy == proxy then
 			return screen
 		end
@@ -15,15 +77,21 @@ end
 
 local function screen_from_script()
 	local url = msg.url()
-	for id,screen in pairs(screens) do
+	for _,screen in pairs(screens) do
 		if screen.script == url then
 			return screen
 		end
 	end
 end
 
-local function in_stack(id)
-	for i=1,#stack do
+
+--- Check if a screen exists in the current screen stack
+-- @param id (string|hash)
+-- @return true of the screen is in the stack
+function M.in_stack(id)
+	assert(id, "You must provide a screen id")
+	id = tohash(id)
+	for i = 1, #stack do
 		if stack[i].id == id then
 			return true
 		end
@@ -31,28 +99,152 @@ local function in_stack(id)
 	return false
 end
 
-function M.register(id, proxy, popup, transitions)
-	assert(not screens[id], ("There is already a screen registered with id %s"):format(tostring(id)))
-	screens[id] = { id = id, proxy = proxy, script = msg.url(), popup = popup, transitions = transitions }
+
+--- Check if a screen is at the top of the stack
+-- (primarily used for unit tests, but could have a usecase outside tests)
+-- @param id (string|hash)
+-- @return true if the screen is at the top of the stack
+function M.is_top(id)
+	assert(id, "You must provide a screen id")
+	id = tohash(id)
+	local top = stack[#stack]
+	return top and top.id == id or false
 end
 
+
+--- Register a new screen
+-- This is done automatically by the screen.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
+-- @param proxy URL to the collection proxy 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_url - URL to a script that is responsible for the
+--		  screen transitions
+-- 		* focus_url - URL to a script that is to be notified of focus
+--		  lost/gained events
+--		* timestep_below_popup - Timestep to set on proxy when below a popup
+function M.register(id, proxy, 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)))
+	assert(proxy, "You must provide a collection proxy URL")
+	local url = msg.url(proxy)
+	screens[id] = {
+		id = id,
+		proxy = proxy,
+		script = msg.url(),
+		popup = settings and settings.popup,
+		popup_on_popup = settings and settings.popup_on_popup,
+		transition_url = settings and settings.transition_url,
+		focus_url = settings and settings.focus_url,
+		timestep_below_popup = settings and settings.timestep_below_popup or 1,
+	}
+end
+
+--- Unregister a screen
+-- This is done automatically by the screen.script
+-- @param id Id of the screen to unregister
 function M.unregister(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)))
 	screens[id] = nil
 end
 
-local function show_out(screen, next_screen, cb)
+local function acquire_input(screen)
+	log("change_context()", screen.id)
+	if not screen.input then
+		msg.post(screen.script, ACQUIRE_INPUT_FOCUS)
+		screen.input = true
+	end
+end
+
+local function release_input(screen)
+	log("change_context()", screen.id)
+	if screen.input then
+		msg.post(screen.script, RELEASE_INPUT_FOCUS)
+		screen.input = false
+	end
+end
+
+local function change_context(screen)
+	log("change_context()", screen.id)
+	screen.wait_for = CONTEXT
+	msg.post(screen.script, CONTEXT)
+	coroutine.yield()
+	screen.wait_for = nil
+end
+
+local function unload(screen)
+	log("unload()", screen.id)
+	screen.wait_for = PROXY_UNLOADED
+	msg.post(screen.proxy, UNLOAD)
+	coroutine.yield()
+	screen.loaded = false
+	screen.wait_for = nil
+end
+
+local function async_load(screen)
+	log("async_load()", screen.id)
+	screen.wait_for = PROXY_LOADED
+	msg.post(screen.proxy, ASYNC_LOAD)
+	coroutine.yield()
+	msg.post(screen.proxy, ENABLE)
+	screen.loaded = true
+	screen.wait_for = nil
+end
+
+local function transition(screen, message_id, message)
+	log("transition()", screen.id)
+	screen.wait_for = M.TRANSITION.DONE
+	msg.post(screen.transition_url, message_id, message)
+	coroutine.yield()
+	screen.wait_for = nil
+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 })
+	end
+end
+
+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 })
+	end
+end
+
+local function change_timestep(screen)
+	screen.changed_timestep = true
+	msg.post(screen.proxy, "set_time_step", { mode = 0, factor = screen.timestep_below_popup })
+end
+
+local function reset_timestep(screen)
+	if screen.changed_timestep then
+		msg.post(screen.proxy, "set_time_step", { mode = 0, factor = 1 })
+		screen.changed_timestep = false
+	end
+end
+
+local function disable(screen, next_screen)
+	log("disable()", screen.id)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
-		msg.post(screen.script, "release_input_focus")
-		msg.post(screen.script, "monarch_context")
-		coroutine.yield()
-		if not next_screen.popup then
-			msg.post(screen.transitions.show_out, "transition_show_out")
-			coroutine.yield()
-			msg.post(screen.proxy, "unload")
-			coroutine.yield()
+		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
@@ -60,87 +252,217 @@ local function show_out(screen, next_screen, cb)
 	coroutine.resume(co)
 end
 
-local function show_in(screen, cb)
+local function enable(screen, previous_screen)
+	log("enable()", screen.id)
 	local co
 	co = coroutine.create(function()
 		screen.co = co
-		msg.post(screen.script, "monarch_context")
-		coroutine.yield()
-		msg.post(screen.proxy, "async_load")
-		coroutine.yield()
-		msg.post(screen.proxy, "enable")
-		stack[#stack + 1] = screen
-		msg.post(screen.transitions.show_in, "transition_show_in")
-		coroutine.yield()
-		msg.post(screen.script, "acquire_input_focus")
+		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)
 end
 
+local function show_out(screen, next_screen, cb)
+	log("show_out()", screen.id)
+	local co
+	co = coroutine.create(function()
+		active_transition_count = active_transition_count + 1
+		notify_listeners(M.SCREEN_TRANSITION_OUT_STARTED, { screen = screen.id, next_screen = next_screen.id })
+		screen.co = co
+		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 next_screen.popup
+		local current_is_popup = screen.popup
+		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
+		if cb then cb() end
+		notify_listeners(M.SCREEN_TRANSITION_OUT_FINISHED, { screen = screen.id, next_screen = next_screen.id })
+	end)
+	coroutine.resume(co)
+end
+
+local function show_in(screen, previous_screen, reload, cb)
+	log("show_in()", screen.id)
+	local co
+	co = coroutine.create(function()
+		active_transition_count = active_transition_count + 1
+		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 reload and screen.loaded then
+			log("show_in() reloading", screen.id)
+			unload(screen)
+		end
+		-- if the screen has been preloaded we need to enable it
+		if screen.preloaded then
+			log("show_in() screen was preloaded", screen.id)
+			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)
+		screen.co = nil
+		active_transition_count = active_transition_count - 1
+		if cb then cb() end
+		notify_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
+	end)
+	coroutine.resume(co)
+end
+
 local function back_in(screen, previous_screen, cb)
+	log("back_in()", screen.id)
 	local co
 	co = coroutine.create(function()
+		active_transition_count = active_transition_count + 1
+		notify_listeners(M.SCREEN_TRANSITION_IN_STARTED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 		screen.co = co
-		msg.post(screen.script, "monarch_context")
-		coroutine.yield()
-		if not previous_screen.popup then
-			msg.post(screen.proxy, "async_load")
-			coroutine.yield()
-			msg.post(screen.proxy, "enable")
-			msg.post(screen.transitions.back_in, "transition_back_in")
-			coroutine.yield()
+		change_context(screen)
+		if screen.preloaded then
+			log("back_in() screen was preloaded", screen.id)
+			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
-		msg.post(screen.script, "acquire_input_focus")
+		reset_timestep(screen)
+		if previous_screen and not previous_screen.popup then
+			transition(screen, M.TRANSITION.BACK_IN, { previous_screen = previous_screen.id })
+		end
+		acquire_input(screen)
+		focus_gained(screen, previous_screen)
 		screen.co = nil
+		active_transition_count = active_transition_count - 1
 		if cb then cb() end
+		notify_listeners(M.SCREEN_TRANSITION_IN_FINISHED, { screen = screen.id, previous_screen = previous_screen and previous_screen.id })
 	end)
 	coroutine.resume(co)
 end
 
-local function back_out(screen, cb)
+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 })
+		active_transition_count = active_transition_count + 1
 		screen.co = co
-		msg.post(screen.script, "release_input_focus")
-		msg.post(screen.script, "monarch_context")
-		coroutine.yield()
-		msg.post(screen.transitions.back_out, "transition_back_out")
-		coroutine.yield()
-		msg.post(screen.proxy, "unload")
+		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 })
 	end)
 	coroutine.resume(co)
 end
 
 
+--- Get data associated with a screen
+-- @param id (string|hash) Id of the screen to get data for
+-- @return Data associated with the screen
+function M.data(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].data
+end
+
+
+--- Checks to see if a screen id is registered
+-- @param id (string|hash) Id of the screen to check if is registered
+-- @return True or False if the screen id is registered or not
+function M.screen_exists(id)
+	assert(id, "You must provide a screen id")
+	id = tohash(id)
+	return screens[id] ~= nil
+end
+
+
+--- Check if Monarch is busy hiding and or showing a screen
+-- @return true if busy
+function M.is_busy()
+	return active_transition_count > 0
+end
+
+
 --- Show a new screen
--- @param id Id of the screen to show
--- @param options Table with options when showing the screen (can be nil). Valid values:
+-- @param id (string|hash) - Id of the screen to show
+-- @param options (table) - Table with options when showing the screen (can be nil). Valid values:
 -- 		* clear - Set to true if the stack should be cleared down to an existing instance of the screen
--- @ param cb Optional callback to invoke when screen is shown
-function M.show(id, options, cb)
+-- 		* reload - Set to true if screen should be reloaded if it already exists in the stack and is loaded.
+--				   This would be the case if doing a show() from a popup on the screen just below the popup.
+-- @param data (*) - Optional data to set on the screen. Can be retrieved by the data() function
+-- @param cb (function) - Optional callback to invoke when screen is shown
+-- @return success True if screen is successfully shown, false if busy performing another operation
+function M.show(id, options, data, cb)
 	assert(id, "You must provide a screen id")
+	if M.is_busy() then
+		log("show() monarch is busy, ignoring request")
+		return false
+	end
+
+	local callbacks = callback_tracker()
+	
+	id = tohash(id)
 	assert(screens[id], ("There is no screen registered with id %s"):format(tostring(id)))
 
 	local screen = screens[id]
+	screen.data = data
+
+	log("show()", screen.id)
 
 	-- manipulate the current top
 	-- close popup if needed
 	-- transition out
 	local top = stack[#stack]
 	if top then
-		-- if top is popup then close it
-		if top.popup then
-			stack[#stack] = nil
-			show_out(top, screen)
-			top = stack[#stack]
-		end
-		-- unload and transition out from top
-		if top then
-			show_out(top, screen)
+		-- keep top popup visible if new screen can be shown on top of a popup
+		if top.popup and screen.popup_on_popup then
+			disable(top, screen)
+		else
+			-- close all popups
+			while top.popup do
+				stack[#stack] = nil
+				show_out(top, screen, callbacks.track())
+				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
 
@@ -148,58 +470,174 @@ function M.show(id, options, cb)
 	-- 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 and in_stack(id) then
-		while true do
-			if table.remove(stack).id == id then
-				break
-			end
-			
+	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, cb)
+	show_in(screen, top, options and options.reload, callbacks.track())
+
+	if cb then callbacks.when_done(cb) end
+
+	return true
 end
 
 
 -- Go back to the previous screen in the stack
--- @param cb Optional callback to invoke when the previous screen is visible again
-function M.back(cb)
+-- @param data (*) - Optional data to set for the previous screen
+-- @param cb (function) - Optional callback to invoke when the previous screen is visible again
+-- @return true if successfully going back, false if busy performing another operation
+function M.back(data, cb)
+	if M.is_busy() then
+		log("back() monarch is busy, ignoring request")
+		return false
+	end
+
+	local callbacks = callback_tracker()
+	
 	local screen = table.remove(stack)
 	if screen then
-		back_out(screen, cb)
+		log("back()", screen.id)
 		local top = stack[#stack]
-		if top then
-			back_in(top, screen)
+		-- if we go back to the same screen we need to first hide it
+		-- and wait until it is hidden before we show it again
+		if top and screen.id == top.id then
+			back_out(screen, top, function()
+				if data then
+					top.data = data
+				end
+				back_in(top, screen, callbacks.track())
+			end)
+		else
+			back_out(screen, top)
+			if top then
+				if data then
+					top.data = data
+				end
+				back_in(top, screen, callbacks.track())
+			end
 		end
-	elseif cb then
-		cb()
 	end
+
+	if cb then callbacks.when_done(cb) end
+	
+	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)
+	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]
+	if screen.preloaded or screen.loaded then
+		if cb then cb() end
+		return
+	end
+	local co
+	co = coroutine.create(function()
+		screen.co = co
+		change_context(screen)
+		screen.wait_for = PROXY_LOADED
+		msg.post(screen.proxy, ASYNC_LOAD)
+		coroutine.yield()
+		screen.preloaded = true
+		screen.wait_for = nil
+		if cb then cb() end
+	end)
+	coroutine.resume(co)
 end
 
 
 function M.on_message(message_id, message, sender)
-	if message_id == hash("proxy_loaded") then
+	if message_id == PROXY_LOADED then
 		local screen = screen_from_proxy(sender)
 		assert(screen, "Unable to find screen for loaded proxy")
-		coroutine.resume(screen.co)
-	elseif message_id == hash("proxy_unloaded") then
+		if screen.wait_for == PROXY_LOADED then
+			assert(coroutine.resume(screen.co))
+		end
+	elseif message_id == PROXY_UNLOADED then
 		local screen = screen_from_proxy(sender)
 		assert(screen, "Unable to find screen for unloaded proxy")
-	elseif message_id == hash("monarch_context") then
+		if screen.wait_for == PROXY_UNLOADED then
+			assert(coroutine.resume(screen.co))
+		end
+	elseif message_id == CONTEXT then
 		local screen = screen_from_script()
 		assert(screen, "Unable to find screen for current script url")
-		coroutine.resume(screen.co)
-	elseif message_id == hash("transition_done") then
+		if screen.wait_for == CONTEXT then
+			assert(coroutine.resume(screen.co))
+		end
+	elseif message_id == M.TRANSITION.DONE then
 		local screen = screen_from_script()
 		assert(screen, "Unable to find screen for current script url")
-		coroutine.resume(screen.co)
+		if screen.wait_for == M.TRANSITION.DONE then
+			assert(coroutine.resume(screen.co))
+		end
 	end
 end
 
+--- Get a list of ids for the current screen stack
+-- (primarily used for unit testing, but could have uses outside testing)
+-- @return Table with screen ids. First entry is at the bottom of the
+-- stack and the last value is at the top (and currently visible)
+function M.get_stack()
+	local s = {}
+	for k,v in pairs(stack) do
+		s[k] = v.id
+	end
+	return s
+end
+
+
+--- Get the screen on top of the stack
+-- @param offset Optional offset from the top of the stack, (eg -1 for the previous screen)
+-- @return Id of the requested screen
+function M.top(offset)
+	local screen = stack[#stack + (offset or 0)]
+	return screen and screen.id
+end
+
+
+--- Get the screen at the bottom of the stack
+-- @param offset Optional offset from the bottom of the stack
+-- @return Id of the requested screen
+function M.bottom(offset)
+	local screen = stack[1 + (offset or 0)]
+	return screen and screen.id
+end
+
+local function url_to_key(url)
+	return (url.socket or hash("")) .. (url.path or hash("")) .. (url.fragment or hash(""))
+end
+
+
+--- Add a listener to be notified of when screens are shown or hidden
+-- @param url The url to notify, nil for current url
+function M.add_listener(url)
+	url = url or msg.url()
+	listeners[url_to_key(url)] = url
+end
+
+
+--- Remove a previously added listener
+-- @param url The url to remove, nil for current url
+function M.remove_listener(url)
+	url = url or msg.url()
+	listeners[url_to_key(url)] = nil
+end
+
+
 function M.dump_stack()
 	local s = ""
-	for i,screen in ipairs(stack) do
+	for i, screen in ipairs(stack) do
 		s = s .. ("%d = %s\n"):format(i, tostring(screen.id))
 	end
 	return s

monarch/screen.script

@@ -1,21 +1,28 @@
-local monarch = require "monarch.monarch"
+local monarch
 
 go.property("screen_proxy", msg.url("#collectionproxy"))
 go.property("screen_id", hash(""))
 go.property("popup", false)
-go.property("transition_show_in", msg.url())
-go.property("transition_show_out", msg.url())
-go.property("transition_back_in", msg.url())
-go.property("transition_back_out", msg.url())
+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)
-	monarch.register(self.screen_id, self.screen_proxy, self.popup, {
-		show_in = self.transition_show_in,
-		show_out = self.transition_show_out,
-		back_in = self.transition_back_in,
-		back_out = self.transition_back_out,
-	})
+	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")
+	monarch.register(
+		self.screen_id,
+		self.screen_proxy,
+		{
+			popup = self.popup,
+			popup_on_popup = self.popup_on_popup,
+			transition_url = self.transition_url,
+			focus_url = self.focus_url,
+			timestep_below_popup = self.timestep_below_popup,
+		}
+	)
 end
 
 function final(self)
@@ -29,11 +36,11 @@ function on_message(self, message_id, message, sender)
 		monarch.back()
 	elseif message_id == hash("back") then
 		monarch.back()
-	elseif message_id == hash("transition_show_in")
-		or message_id == hash("transition_show_out")
-		or message_id == hash("transition_back_in")
-		or message_id == hash("transition_back_out") then
-		msg.post(sender, "transition_done")
+	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/transitions/easings.lua

@@ -0,0 +1,26 @@
+local M = {}
+
+
+local function create(name)
+	assert(gui["EASING_OUT" .. name])
+	assert(gui["EASING_IN" .. name])
+	return {
+		IN = gui["EASING_OUT" .. name],
+		OUT = gui["EASING_IN" .. name],
+	}
+end
+
+
+function M.BACK() return create("BACK") end
+function M.BOUNCE() return create("BOUNCE") end
+function M.CIRC() return create("CIRC") end
+function M.CUBIC() return create("CUBIC") end
+function M.ELASTIC() return create("ELASTIC") end
+function M.EXPO() return create("EXPO") end
+function M.QUAD() return create("QUAD") end
+function M.QUART() return create("QUART") end
+function M.QUINT() return create("QUINT") end
+function M.SINE() return create("SINE") end
+
+
+return M

monarch/transitions/gui.lua

@@ -1,64 +1,107 @@
+local monarch = require "monarch.monarch"
+local easings = require "monarch.transitions.easings"
+
 local M = {}
 
-local WIDTH = tonumber(sys.get_config("display.width"))
-local HEIGHT = tonumber(sys.get_config("display.height"))
+local WIDTH = nil
+local HEIGHT = nil
+local LEFT = nil
+local RIGHT = nil
+local TOP = nil
+local BOTTOM = nil
 
-local LEFT = vmath.vector3(-WIDTH * 2, 0, 0)
-local RIGHT = vmath.vector3(WIDTH * 2, 0, 0)
-local TOP = vmath.vector3(0, HEIGHT * 2, 0)
-local BOTTOM = vmath.vector3(0, -HEIGHT * 2, 0)
+local ZERO_SCALE = vmath.vector3(0, 0, 1)
 
-function M.instant(node, to, easing, duration, delay, url)
-	msg.post(url, "transition_done")
+local LAYOUT_CHANGED = hash("layout_changed")
+
+-- Notify the transition system that the window size has changed
+-- @param width
+-- @param height
+function M.window_resized(width, height)
+	WIDTH = width
+	HEIGHT = height
+	LEFT = vmath.vector3(-WIDTH * 2, 0, 0)
+	RIGHT = vmath.vector3(WIDTH * 2, 0, 0)
+	TOP = vmath.vector3(0, HEIGHT * 2, 0)
+	BOTTOM = vmath.vector3(0, - HEIGHT * 2, 0)
 end
 
-local function slide_in(direction, node, to, easing, duration, delay, url)
+M.window_resized(tonumber(sys.get_config("display.width")), tonumber(sys.get_config("display.height")))
+
+
+function M.instant(node, to, easing, duration, delay, cb)
+	cb()
+end
+
+local function slide_in(direction, node, to, easing, duration, delay, cb)
 	local from = to + direction
 	gui.set_position(node, from)
-	gui.animate(node, gui.PROP_POSITION, to, easing, duration, delay, function()
-		msg.post(url, "transition_done")
-	end)
+	gui.animate(node, gui.PROP_POSITION, to, easing, duration, delay, cb)
 end
 
-function M.slide_in_left(node, to, easing, duration, delay, url)
-	return slide_in(LEFT, node, to, easing, duration, delay, url)
+function M.slide_in_left(node, to, easing, duration, delay, cb)
+	return slide_in(LEFT, node, to.pos, easing, duration, delay, cb)
 end
 
-function M.slide_in_right(node, to, easing, duration, delay, url)
-	slide_in(RIGHT, node, to, easing, duration, delay, url)
+function M.slide_in_right(node, to, easing, duration, delay, cb)
+	slide_in(RIGHT, node, to.pos, easing, duration, delay, cb)
 end
 
-function M.slide_in_top(node, to, easing, duration, delay, url)
-	slide_in(TOP, node, to, easing, duration, delay, url)
+function M.slide_in_top(node, to, easing, duration, delay, cb)
+	slide_in(TOP, node, to.pos, easing, duration, delay, cb)
 end
 
-function M.slide_in_bottom(node, to, easing, duration, delay, url)
-	slide_in(BOTTOM, node, to, easing, duration, delay, url)
+function M.slide_in_bottom(node, to, easing, duration, delay, cb)
+	slide_in(BOTTOM, node, to.pos, easing, duration, delay, cb)
 end
 
 
-local function slide_out(direction, node, from, easing, duration, delay, url)
+local function slide_out(direction, node, from, easing, duration, delay, cb)
 	local to = from + direction
 	gui.set_position(node, from)
-	gui.animate(node, gui.PROP_POSITION, to, easing, duration, delay, function()
-		msg.post(url, "transition_done")
-	end)
+	gui.animate(node, gui.PROP_POSITION, to, easing, duration, delay, cb)
 end
 
-function M.slide_out_left(node, from, easing, duration, delay, url)
-	slide_out(LEFT, node, from, easing, duration, delay, url)
+function M.slide_out_left(node, from, easing, duration, delay, cb)
+	slide_out(LEFT, node, from.pos, easing, duration, delay, cb)
 end
 
-function M.slide_out_right(node, from, easing, duration, delay, url)
-	slide_out(RIGHT, node, from, easing, duration, delay, url)
+function M.slide_out_right(node, from, easing, duration, delay, cb)
+	slide_out(RIGHT, node, from.pos, easing, duration, delay, cb)
 end
 
-function M.slide_out_top(node, from, easing, duration, delay, url)
-	slide_out(TOP, node, from, easing, duration, delay, url)
+function M.slide_out_top(node, from, easing, duration, delay, cb)
+	slide_out(TOP, node, from.pos, easing, duration, delay, cb)
 end
 
-function M.slide_out_bottom(node, from, easing, duration, delay, url)
-	slide_out(BOTTOM, node, from, easing, duration, delay, url)
+function M.slide_out_bottom(node, from, easing, duration, delay, cb)
+	slide_out(BOTTOM, node, from.pos, easing, duration, delay, cb)
+end
+
+function M.scale_in(node, to, easing, duration, delay, cb)
+	gui.set_scale(node, ZERO_SCALE)
+	gui.animate(node, gui.PROP_SCALE, to.scale, easing, duration, delay, cb)
+end
+
+function M.scale_out(node, from, easing, duration, delay, cb)
+	gui.set_scale(node, from.scale)
+	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
@@ -68,18 +111,67 @@ function M.create(node)
 
 	local instance = {}
 
-	local transitions = {
-		[hash("transition_show_in")] = M.instant,
-		[hash("transition_show_out")] = M.instant,
-		[hash("transition_back_in")] = M.instant,
-		[hash("transition_back_out")] = M.instant,
-	}
+	local transitions = {}
 
-	local initial_position = gui.get_position(node)
+	local current_transition = nil
+	
+	local initial_data = {}
+	initial_data.pos = gui.get_position(node)
+	initial_data.scale = gui.get_scale(node)
+
+	local function create_transition(fn, easing, duration, delay)
+		return {
+			fn = fn,
+			easing = easing,
+			duration = duration,
+			delay = delay,
+			in_progress = false,
+			urls = {},
+			id = nil
+		}
+	end
+
+	local function finish_transition(transition)
+		transition.in_progress = false
+		local message = { transition = transition.id }
+		while #transition.urls > 0 do
+			local url = table.remove(transition.urls)
+			msg.post(url, monarch.TRANSITION.DONE, message)
+		end
+	end
+
+	local function start_transition(transition, transition_id, url)
+		table.insert(transition.urls, url)
+		if not transition.in_progress then
+			table.insert(transition.urls, msg.url())
+			transition.in_progress = true
+			transition.id = transition_id
+			current_transition = transition
+			transition.fn(node, initial_data, transition.easing, transition.duration, transition.delay or 0, function()
+				finish_transition(transition)
+			end)
+		end
+	end
 
 	-- Forward on_message calls here
 	function instance.handle(message_id, message, sender)
-		transitions[message_id](sender)
+		if message_id == LAYOUT_CHANGED then
+			initial_data.pos = gui.get_position(node)
+			-- replay the current transition if the layout changes
+			-- this will ensure that things are still hidden if they
+			-- were transitioned out
+			if current_transition then
+				current_transition.fn(node, initial_data, current_transition.easing, 0, 0)
+				if current_transition.in_progress then
+					finish_transition(current_transition)
+				end
+			end
+		else
+			local transition = transitions[message_id]
+			if transition then
+				start_transition(transition, message_id, sender)
+			end
+		end
 	end
 	
 	-- Specify the transition function when this node is transitioned
@@ -89,44 +181,106 @@ function M.create(node)
 	-- @param duration Transition duration
 	-- @param delay Transition delay
 	function instance.show_in(fn, easing, duration, delay)
-		transitions[hash("transition_show_in")] = function(url)
-			print("transition_show_in", url, fn)
-			fn(node, initial_position, easing, duration, delay, url)
-		end
+		transitions[monarch.TRANSITION.SHOW_IN] = create_transition(fn, easing, duration, delay)
 		return instance
 	end
 
 	-- Specify the transition function when this node is transitioned
 	-- from when showing another screen
 	function instance.show_out(fn, easing, duration, delay)
-		transitions[hash("transition_show_out")] = function(url)
-			print("transition_show_out")
-			fn(node, initial_position, easing, duration, delay, url)
-		end
+		transitions[monarch.TRANSITION.SHOW_OUT] = create_transition(fn, easing, duration, delay)
 		return instance
 	end
 
 	--- Specify the transition function when this node is transitioned
 	-- to when navigating back in the screen stack
 	function instance.back_in(fn, easing, duration, delay)
-		transitions[hash("transition_back_in")] = function(url)
-			print("transition_back_in")
-			fn(node, initial_position, easing, duration, delay, url)
-		end
+		transitions[monarch.TRANSITION.BACK_IN] = create_transition(fn, easing, duration, delay)
 		return instance
 	end
 
 	--- Specify the transition function when this node is transitioned
 	-- from when navigating back in the screen stack
 	function instance.back_out(fn, easing, duration, delay)
-		transitions[hash("transition_back_out")] = function(url)
-			print("transition_back_out")
-			fn(node, initial_position, easing, duration, delay, url)
-		end
+		transitions[monarch.TRANSITION.BACK_OUT] = create_transition(fn, easing, duration, delay)
 		return instance
 	end
 
+	-- set default transitions (instant)
+	instance.show_in(M.instant)
+	instance.show_out(M.instant)
+	instance.back_in(M.instant)
+	instance.back_out(M.instant)
+	
 	return instance
 end
 
+
+--- Create transition where the screen slides in from the right when shown and out
+-- to the left when hidden (and the reverse when going back)
+-- @param node
+-- @param duration
+-- @param delay Optional. Defaults to 0
+-- @param easing Optional. A constant from monarch.transitions.easing
+-- @return Transition instance
+function M.in_right_out_left(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.slide_in_right, easing.OUT, duration, delay or 0)
+	.show_out(M.slide_out_left, easing.IN, duration, delay or 0)
+	.back_in(M.slide_in_left, easing.OUT, duration, delay or 0)
+	.back_out(M.slide_out_right, easing.IN, duration, delay or 0)
+end
+
+
+function M.in_left_out_right(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.slide_in_left, easing.OUT, duration, delay or 0)
+	.show_out(M.slide_out_right, easing.IN, duration, delay or 0)
+	.back_in(M.slide_in_right, easing.OUT, duration, delay or 0)
+	.back_out(M.slide_out_left, easing.IN, duration, delay or 0)
+end
+
+
+function M.in_right_out_right(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.slide_in_right, easing.OUT, duration, delay or 0)
+	.show_out(M.slide_out_right, easing.IN, duration, delay or 0)
+	.back_in(M.slide_in_right, easing.OUT, duration, delay or 0)
+	.back_out(M.slide_out_right, easing.IN, duration, delay or 0)
+end
+
+
+function M.in_left_out_left(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.slide_in_left, easing.OUT, duration, delay or 0)
+	.show_out(M.slide_out_left, easing.IN, duration, delay or 0)
+	.back_in(M.slide_in_left, easing.OUT, duration, delay or 0)
+	.back_out(M.slide_out_left, easing.IN, duration, delay or 0)
+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

monarch/utils/callback_tracker.lua

@@ -0,0 +1,39 @@
+local M = {}
+
+
+function M.create()
+	local instance = {}
+
+	local callback = nil
+	local callback_count = 0
+
+	--- Create a callback function and track when it is done
+	-- @return Callback function
+	function instance.track()
+		callback_count = callback_count + 1
+		return function()
+			callback_count = callback_count - 1
+			if callback_count == 0 and callback then
+				callback()
+			end
+		end
+	end
+
+	--- Call a function when all callbacks have been triggered
+	-- @param cb Function to call when all 
+	function instance.when_done(cb)
+		callback = cb
+		if callback_count == 0 then
+			callback()
+		end
+	end
+
+	return instance
+end
+
+
+return setmetatable(M, {
+	__call = function(_, ...)
+		return M.create(...)
+	end
+})

test/cowait.lua

@@ -0,0 +1,48 @@
+local M = {}
+
+
+local instances = {}
+
+local function create(fn)
+	local instance = {
+		co = coroutine.running(),
+		fn = fn,
+	}
+	table.insert(instances, instance)
+	coroutine.yield(instance.co)
+end
+
+	
+
+function M.seconds(amount)
+	local time = socket.gettime() + amount
+	create(function()
+		return socket.gettime() >= time
+	end)
+end
+
+
+function M.eval(fn)
+	create(fn)
+end
+
+function M.update()
+	for k,instance in pairs(instances) do
+		if instance.fn() then
+			instances[k] = nil
+			coroutine.resume(instance.co)
+		end
+	end
+end
+
+return setmetatable(M, {
+	__call = function(self, arg1, ...)
+		if type(arg1) == "number" then
+			return M.seconds(arg1, ...)
+		elseif type(arg1) == "function" then
+			return M.eval(arg1, ...)
+		else
+			error("Unknown argument type")
+		end
+	end
+})

test/cowait.script

@@ -0,0 +1,5 @@
+local cowait = require "test.cowait"
+
+function update(self, dt)
+	cowait.update()
+end

test/data/popup1.collection

@@ -0,0 +1,37 @@
+name: "popup1"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"popup1\"\n"
+  "  component: \"/test/data/popup1.gui\"\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/data/popup1.gui

@@ -0,0 +1,131 @@
+script: ""
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.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: 200.0
+    y: 100.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: "box"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "POPUP 1"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "box"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

test/data/popup2.collection

@@ -0,0 +1,37 @@
+name: "popup2"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"popup2\"\n"
+  "  component: \"/test/data/popup2.gui\"\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/data/popup2.gui

@@ -0,0 +1,131 @@
+script: ""
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.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: 200.0
+    y: 100.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: "box"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "POPUP 2"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "box"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

test/data/screen1.collection

@@ -0,0 +1,37 @@
+name: "screen1"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"screen1\"\n"
+  "  component: \"/test/data/screen1.gui\"\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/data/screen1.gui

@@ -0,0 +1,131 @@
+script: "/test/data/screen1.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 568.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: 200.0
+    y: 100.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: "box"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "1"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "box"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

test/data/screen1.gui_script

@@ -0,0 +1,12 @@
+function init(self)
+	print("init - screen1")
+end
+
+function final(self)
+	print("final - screen1")
+end
+
+function on_message(self, message_id, message, sender)
+	-- Add message-handling code here
+	-- Remove this function if not needed
+end

test/data/screen2.collection

@@ -0,0 +1,37 @@
+name: "screen2"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"screen2\"\n"
+  "  component: \"/test/data/screen2.gui\"\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/data/screen2.gui

@@ -0,0 +1,131 @@
+script: "/test/data/screen2.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 697.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: 200.0
+    y: 100.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: "box"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "2"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "box"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

test/data/screen2.gui_script

@@ -0,0 +1,12 @@
+function init(self)
+	print("init - screen2")
+end
+
+function final(self)
+	print("final - screen2")
+end
+
+function on_message(self, message_id, message, sender)
+	-- Add message-handling code here
+	-- Remove this function if not needed
+end

test/data/screens.collection

@@ -0,0 +1,357 @@
+name: "screens"
+scale_along_z: 0
+embedded_instances {
+  id: "screen1"
+  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: \"screen1\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/screen1.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: "screen2"
+  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: \"screen2\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/screen2.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: "popup1"
+  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: \"popup1\"\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: \"false\"\n"
+  "    type: PROPERTY_TYPE_BOOLEAN\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/popup1.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: "popup2"
+  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: \"popup2\"\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"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/popup2.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: "transition1"
+  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: \"transition1\"\n"
+  "    type: PROPERTY_TYPE_HASH\n"
+  "  }\n"
+  "  properties {\n"
+  "    id: \"transition_url\"\n"
+  "    value: \"transition1:/go\"\n"
+  "    type: PROPERTY_TYPE_URL\n"
+  "  }\n"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"collectionproxy\"\n"
+  "  type: \"collectionproxy\"\n"
+  "  data: \"collection: \\\"/test/data/transition1.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: "listener1"
+  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
+  }
+}
+embedded_instances {
+  id: "listener2"
+  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/transition1.collection

@@ -0,0 +1,37 @@
+name: "transition1"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"transition1\"\n"
+  "  component: \"/test/data/transition1.gui\"\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/data/transition1.gui

@@ -0,0 +1,131 @@
+script: "/test/data/transition1.gui_script"
+fonts {
+  name: "example"
+  font: "/assets/example.font"
+}
+background_color {
+  x: 0.0
+  y: 0.0
+  z: 0.0
+  w: 0.0
+}
+nodes {
+  position {
+    x: 320.0
+    y: 697.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: 200.0
+    y: 100.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: "root"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  adjust_mode: ADJUST_MODE_FIT
+  layer: ""
+  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_AUTO
+}
+nodes {
+  position {
+    x: 0.0
+    y: 0.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: 200.0
+    y: 100.0
+    z: 0.0
+    w: 1.0
+  }
+  color {
+    x: 0.0
+    y: 0.0
+    z: 0.0
+    w: 1.0
+  }
+  type: TYPE_TEXT
+  blend_mode: BLEND_MODE_ALPHA
+  text: "transition 1"
+  font: "example"
+  id: "text"
+  xanchor: XANCHOR_NONE
+  yanchor: YANCHOR_NONE
+  pivot: PIVOT_CENTER
+  outline {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  shadow {
+    x: 1.0
+    y: 1.0
+    z: 1.0
+    w: 1.0
+  }
+  adjust_mode: ADJUST_MODE_FIT
+  line_break: false
+  parent: "root"
+  layer: ""
+  inherit_alpha: true
+  alpha: 1.0
+  outline_alpha: 1.0
+  shadow_alpha: 1.0
+  template_node_child: false
+  text_leading: 1.0
+  text_tracking: 0.0
+}
+material: "/builtins/materials/gui.material"
+adjust_reference: ADJUST_REFERENCE_PARENT
+max_nodes: 512

test/data/transition1.gui_script

@@ -0,0 +1,10 @@
+local transitions = require "monarch.transitions.gui"
+
+function init(self)
+	self.transition = transitions.in_right_out_left(gui.get_node("root"), 1)
+end
+
+function on_message(self, message_id, message, sender)
+	print(message_id)
+	self.transition.handle(message_id, message, sender)
+end

test/msg.lua

@@ -0,0 +1,52 @@
+local mock = require "deftest.mock.mock"
+
+
+local M = {}
+
+
+local recipients = {}
+
+local history = {}
+
+local function get_recipient(url)
+	recipients[url] = recipients[url] or {}
+	return recipients[url]
+end
+
+local function post(url, message_id, message)
+	local data = { url = url, message_id = message_id, message = message }
+	history[#history + 1] = data
+	local recipient = get_recipient(url)
+	recipient[#recipient + 1] = data
+	msg.post.original(url, message_id, message or {})
+end
+
+function M.mock()
+	recipients = {}
+	history = {}
+	mock.mock(msg)
+	msg.post.replace(post)
+end
+
+function M.unmock()
+	mock.unmock(msg)
+end
+
+
+
+function M.messages(url)
+	return url and get_recipient(url) or history
+end
+
+function M.first(url)
+	local messages = url and get_recipient(url) or history
+	return messages[1]
+end
+
+function M.last(url)
+	local messages = url and get_recipient(url) or history
+	return messages[#messages]
+end
+
+
+return M

test/test.collection

@@ -0,0 +1,70 @@
+name: "test"
+scale_along_z: 0
+embedded_instances {
+  id: "go"
+  data: "components {\n"
+  "  id: \"test\"\n"
+  "  component: \"/test/test.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"
+  "}\n"
+  "components {\n"
+  "  id: \"cowait\"\n"
+  "  component: \"/test/cowait.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"
+  "}\n"
+  "embedded_components {\n"
+  "  id: \"screensfactory\"\n"
+  "  type: \"collectionfactory\"\n"
+  "  data: \"prototype: \\\"/test/data/screens.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

@@ -0,0 +1,9 @@
+local deftest = require "deftest.deftest"
+
+local test_monarch = require "test.test_monarch"
+
+
+function init(self)
+	deftest.add(test_monarch)
+	deftest.run()
+end

test/test_monarch.lua

@@ -0,0 +1,275 @@
+local cowait = require "test.cowait"
+local mock_msg = require "test.msg"
+local unload = require "deftest.util.unload"
+local monarch = require "monarch.monarch"
+
+local SCREEN1_STR = hash("screen1")
+local SCREEN1 = hash(SCREEN1_STR)
+local SCREEN2 = hash("screen2")
+local POPUP1 = hash("popup1")
+local POPUP2 = hash("popup2")
+local FOOBAR = hash("foobar")
+local TRANSITION1 = hash("transition1")
+
+return function()
+
+	local screens_instances = {}
+
+	local function is_shown(screen_id)
+		return monarch.is_top(screen_id)
+	end
+
+	local function is_hidden(screen_id)
+		return not monarch.is_top(screen_id)
+	end
+
+	local function wait_timeout(fn, ...)
+		local args = { ... }
+		local time = socket.gettime()
+		cowait(function()
+			return fn(unpack(args)) or socket.gettime() > time + 5	
+		end)
+		return fn(...)
+	end
+		
+	local function wait_until_shown(screen_id)
+		return wait_timeout(is_shown, screen_id)
+	end
+	local function wait_until_hidden(screen_id)
+		return wait_timeout(is_hidden, screen_id)
+	end
+	local function wait_until_not_busy()
+		return wait_timeout(function() return not monarch.is_busy() end)
+	end
+
+	local function assert_stack(expected_screens)
+		local actual_screens = monarch.get_stack()
+		if #actual_screens ~= #expected_screens then
+			error("Stack length mismatch", 2)
+		end
+		for i=1,#actual_screens do
+			if actual_screens[i] ~= expected_screens[i] then
+				error("Stack content not matching", 2)
+			end
+		end
+	end
+
+	
+	describe("monarch", function()
+		before(function()
+			mock_msg.mock()
+			monarch = require "monarch.monarch"
+			screens_instances = collectionfactory.create("#screensfactory")
+		end)
+
+		after(function()
+			mock_msg.unmock()
+			unload.unload("monarch%..*")
+			for id,instance_id in pairs(screens_instances) do
+				go.delete(instance_id)
+			end
+			cowait(0.1)
+		end)
+
+
+		it("should be able to tell if a screen exists", function()
+			assert(monarch.screen_exists(SCREEN1))
+			assert(monarch.screen_exists(SCREEN1_STR))
+			assert(not monarch.screen_exists(hash("foobar")))
+		end)
+
+
+		it("should be able to show screens and go back to previous screens", function()
+			monarch.show(SCREEN1_STR)
+			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 })
+
+			monarch.back()
+			assert(wait_until_hidden(SCREEN2), "Screen2 was never hidden")
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+
+			monarch.back()
+			assert(wait_until_hidden(SCREEN1), "Screen1 was never hidden")
+			assert_stack({ })
+		end)
+
+
+		it("should be able to pass data to a screen when showning it or going back to it", function()
+			local data1 = { foo = "bar" }
+			monarch.show(SCREEN1, nil, data1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+
+			local data2 = { boo = "car" }
+			monarch.show(SCREEN2, nil, data2)
+			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			
+			assert(monarch.data(SCREEN1) == data1, "Expected data on screen1 doesn't match actual data")
+			assert(monarch.data(SCREEN2) == data2, "Expected data on screen2 doesn't match actual data")
+
+			local data_back = { going = "back" }
+			monarch.back(data_back)
+			assert_stack({ SCREEN1 })
+
+			assert(monarch.data(SCREEN1) == data_back, "Expected data on screen1 doesn't match actual data")
+		end)
+
+
+		it("should be able to show the same screen twice", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1, SCREEN1 })
+		end)
+		
+
+		it("should be able to clear the stack if trying to show the same screen twice", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			monarch.show(SCREEN2)
+			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			assert_stack({ SCREEN1, SCREEN2 })
+			monarch.show(SCREEN1, { clear = true })
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+		end)
+		
+
+		it("should be able to show one popup on top of another the Popup On Popup flag is set", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			monarch.show(POPUP1)
+			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert_stack({ SCREEN1, POPUP1 })
+			monarch.show(POPUP2)
+			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert_stack({ SCREEN1, POPUP1, POPUP2 })
+		end)
+
+		
+		it("should prevent further operations while hiding/showing a screen", function()
+			assert(monarch.show(SCREEN1) == true)
+			assert(monarch.show(SCREEN2) == false)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+
+			assert(monarch.show(SCREEN2) == true)
+			assert(wait_until_shown(SCREEN2), "Screen2 was never shown")
+			assert_stack({ SCREEN1, SCREEN2 })
+
+			assert(monarch.back() == true)
+			assert(monarch.back() == false)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+		end)
+		
+		
+		it("should close any open popups when showing a popup without the Popup On Popup flag", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			monarch.show(POPUP2)
+			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert_stack({ SCREEN1, POPUP2 })
+			monarch.show(POPUP1)
+			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert_stack({ SCREEN1, POPUP1 })
+		end)
+
+		
+		it("should close any open popups when showing a non-popup", function()
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert_stack({ SCREEN1 })
+			monarch.show(POPUP1)
+			assert(wait_until_shown(POPUP1), "Popup1 was never shown")
+			assert_stack({ SCREEN1, POPUP1 })
+			monarch.show(POPUP2)
+			assert(wait_until_shown(POPUP2), "Popup2 was never shown")
+			assert_stack({ SCREEN1, POPUP1, POPUP2 })
+			monarch.show(SCREEN2)
+			assert(wait_until_shown(SCREEN2), "Popup2 was never shown")
+			assert_stack({ SCREEN1, SCREEN2 })
+		end)
+
+
+		it("should be able to get the id of the screen at the top and bottom of the stack", function()
+			assert(monarch.top() == nil)
+			assert(monarch.bottom() == nil)
+			assert(monarch.top(1) == nil)
+			assert(monarch.bottom(-1) == nil)
+						
+			monarch.show(SCREEN1)
+			assert(wait_until_shown(SCREEN1), "Screen1 was never shown")
+			assert(monarch.top() == SCREEN1)
+			assert(monarch.top(0) == SCREEN1)
+			assert(monarch.top(1) == nil)
+			assert(monarch.bottom() == SCREEN1)
+			assert(monarch.bottom(0) == SCREEN1)
+			assert(monarch.bottom(-1) == nil)
+									
+			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.top(0) == SCREEN2)
+			assert(monarch.top(-1) == SCREEN1)
+			assert(monarch.bottom(0) == SCREEN1)
+			assert(monarch.bottom(1) == SCREEN2)
+		end)
+
+		it("should be busy while transition is running", function()
+			monarch.show(TRANSITION1)
+			assert(wait_until_shown(TRANSITION1), "Transition1 was never shown")
+			assert(monarch.is_busy())
+			assert(wait_until_not_busy())
+		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")])
+			monarch.add_listener(URL1)
+			monarch.add_listener(URL2)
+
+			monarch.show(SCREEN1)
+			assert(mock_msg.messages(URL1)[1].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL1)[1].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL2)[1].message_id == monarch.SCREEN_TRANSITION_IN_STARTED)
+			assert(mock_msg.messages(URL2)[1].message.screen == SCREEN1)
+			assert(wait_until_not_busy())
+			assert(mock_msg.messages(URL1)[2].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[2].message.screen == SCREEN1)
+			assert(mock_msg.messages(URL2)[2].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL2)[2].message.screen == SCREEN1)
+												
+			monarch.remove_listener(URL2)
+			monarch.show(SCREEN2)
+			assert(wait_until_not_busy())
+			
+			monarch.back()
+			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.screen == SCREEN1)
+			assert(mock_msg.messages(URL1)[6].message_id == monarch.SCREEN_TRANSITION_IN_FINISHED)
+			assert(mock_msg.messages(URL1)[7].message.screen == SCREEN2)
+		end)
+	end)
+end