### Screen Proxy Script Setup Example

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/screen-scripts.md

Example setup for integrating screen_proxy.script with a collection proxy component in Defold. Ensure the collection proxy and script properties are correctly configured in the editor.

```lua
-- In a game object's associated script:
-- 1. Add a collection proxy component
-- 2. Add screen_proxy.script to the game object
-- 3. Set the properties:
--    Screen Proxy: #collectionproxy
--    Screen Id: hash("menu")
--    Popup: false
--    Preload: true
```

--------------------------------

### Example Setup for Screen Factory

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/screen-scripts.md

This Lua code demonstrates the setup required in a game object's script to use the screen_factory.script. It involves adding a collection factory component, attaching the screen_factory.script, and configuring its properties in the editor.

```lua
-- In a game object's associated script:
-- 1. Add a collection factory component
-- 2. Add screen_factory.script to the game object
-- 3. Set the properties:
--    Screen Factory: #collectionfactory
--    Screen Id: hash("enemy_wave")
--    Popup: false
--    Preload: false
```

--------------------------------

### Configuration Guide

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

Instructions and documentation for configuring the Monarch framework, including installation, property settings, and registration.

```APIDOC
## Configuration Guide

### Description
This guide provides detailed information on configuring the Monarch framework, covering installation, property documentation, programmatic registration, and best practices.

### Topics Covered
- Installation instructions
- Property documentation
- Programmatic registration
- Collection structure recommendations
- Preloading configuration
- Transition setup options
- Input focus configuration
- Best practices
```

--------------------------------

### Monarch Screen Scripts API Reference

Source: https://github.com/britzl/monarch/blob/master/_autodocs/DOCUMENTATION_SUMMARY.md

Documentation for screen setup, covering `screen_proxy.script` and `screen_factory.script`. It details configurable properties, message handlers for show, back, and hide actions, setup examples, common screen patterns, and error handling.

```APIDOC
## Monarch Screen Scripts API Reference

### Description
Documents the API for setting up screen scripts, specifically `screen_proxy.script` and `screen_factory.script`. Covers configurable properties, message handlers for common screen lifecycle events, setup examples, and error handling.

### API Surface
- **Script Types**: `screen_proxy.script`, `screen_factory.script`
- **Configurable Properties**: All configurable properties for screen scripts.
- **Message Handlers**: `show`, `back`, `hide`.
- **Examples**: Setup examples and common screen patterns.
- **Error Handling**: Guide for handling errors within screen scripts.
```

--------------------------------

### Monarch Examples & Patterns Details (examples-and-patterns.md)

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

Details the content of the examples-and-patterns.md file, listing various code examples and patterns such as menu navigation, popups, tabbed UIs, preloading, message passing, and focus handling.

```text
Examples & Patterns (examples-and-patterns.md):
- Basic menu navigation
- Popup dialogs
- Tabbed UI systems
- Preloading patterns
- Dynamic transitions
- Message passing
- Focus handling
- Global listeners
- Multi-popup stacks
- Navigation patterns
- Bootstrap patterns
(12 complete code examples)
```

--------------------------------

### Example Scale Transition

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Shows how to apply scale in and out transitions to a GUI node. Choose an appropriate easing function and duration for the animation.

```lua
local transition = transitions.create(gui.get_node("button"))
  .show_in(transitions.scale_in, gui.EASING_OUTBACK, 0.6)
  .show_out(transitions.scale_out, gui.EASING_INBACK, 0.6)
```

--------------------------------

### Monarch One-Minute Intro

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

This snippet demonstrates the basic setup and usage of the Monarch library for managing screens, including registration, message handling, navigation, and custom transitions.

```lua
-- 1. Import
local monarch = require "monarch.monarch"

-- 2. Register screen (automatic with screen_proxy.script)
-- Set properties in editor: Screen Id = hash("menu")

-- 3. In screen's on_message()
function on_message(self, message_id, message, sender)
  monarch.on_message(message_id, message, sender)
end

-- 4. Show screens
monarch.show(hash("menu"))

-- 5. Navigate
monarch.back()

-- 6. Add transitions
local transitions = require "monarch.transitions.gui"
local tr = transitions.create(gui.get_node("root"))
  .show_in(transitions.fade_in, gui.EASING_OUTQUAD, 0.3)
  .show_out(transitions.fade_out, gui.EASING_INQUAD, 0.3)
monarch.on_transition(hash("menu"), tr)
```

--------------------------------

### Basic Transition Setup

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Sets up a basic transition for a GUI node, defining slide-in and slide-out animations for show and back navigation events. This is useful for creating custom screen animations.

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

function init(self)
  -- Create a transition for the root node
  -- Slide in from right on show, slide out left on hide
  local transition = transitions.create(gui.get_node("root"))
    .show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
    .show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
    .back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
    .back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)
  
  monarch.on_transition(hash("my_screen"), transition)
end

function on_message(self, message_id, message, sender)
  monarch.on_message(message_id, message, sender)
end
```

--------------------------------

### Example Slide Transition

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Demonstrates how to use slide in and out transitions with a GUI node. Specify the transition function, easing, and duration.

```lua
local transition = transitions.create(gui.get_node("panel"))
  .show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.5)
  .show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.5)
```

--------------------------------

### Example Instant Transition

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Shows how to apply an instant transition, effectively disabling animation for a node's appearance. This is useful for elements that should not animate.

```lua
-- No transition for this node
.show_in(transitions.instant)
```

--------------------------------

### Monarch Configuration Details (configuration.md)

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

Details the content of the configuration.md file, covering installation, property documentation, programmatic registration, collection structure, preloading, transition setup, input focus, and best practices.

```text
Configuration (configuration.md):
- Installation instructions
- Property documentation
- Programmatic registration
- Collection structure recommendations
- Preloading configuration
- Transition setup options
- Input focus configuration
- Best practices
```

--------------------------------

### Configure Screen Transitions with Predefined Animations

Source: https://github.com/britzl/monarch/blob/master/README_TRANSITIONS.md

Set up slide and fade transitions for a specific screen ('foobar') using the `monarch.transitions.gui` module. This example demonstrates configuring 'show_in', 'show_out', 'back_in', and 'back_out' animations for a GUI node. It also shows how to handle the `TRANSITION_DONE` message.

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

function init(self)
	-- create transitions for the node 'root'
	-- the node will slide in/out from left and right with
	-- a specific easing, duration and delay
	local transition = transitions.create(gui.get_node("root"))
		.show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
		.show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.6, 0)
		.back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.6, 0)
		.back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.6, 0)

	monarch.on_transition("foobar", transition)
end

function on_message(self, message_id, message, sender)
	monarch.on_message(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
```

--------------------------------

### Example Fade Transition

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Illustrates the use of fade in and out transitions for a GUI node. This is useful for making elements appear or disappear smoothly.

```lua
local transition = transitions.create(gui.get_node("overlay"))
  .show_in(transitions.fade_in, gui.EASING_OUTQUAD, 0.3)
  .show_out(transitions.fade_out, gui.EASING_INQUAD, 0.3)
```

--------------------------------

### Custom Code Example: Loading Multiple Screens

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/utilities.md

Demonstrates how to use the async and callback_tracker modules in custom code to load multiple screens in parallel. Requires importing the utility modules.

```lua
local async = require "monarch.utils.async"
local callback_tracker = require "monarch.utils.callback_tracker"

-- Example: Load multiple screens in parallel
function load_multiple_screens(screen_ids)
  return async(function(await, resume)
    local tracker = callback_tracker()
    
    for _, screen_id in ipairs(screen_ids) do
      await(monarch.preload, screen_id, tracker.track())
    end
    
    tracker.when_done(function()
      resume()
    end)
  end)
end
```

--------------------------------

### Proper Bootstrap Order for Initialization

Source: https://github.com/britzl/monarch/blob/master/_autodocs/examples-and-patterns.md

Ensure all screens are registered before the first `monarch.show()` call by delaying the initial screen display. This script posts a message to itself after initial setup and shows the first screen only after receiving that message.

```lua
-- bootstrap.script
local monarch = require "monarch.monarch"

function init(self)
  -- Delay showing first screen to let other screens register
  msg.post("#", "init_complete")
end

function on_message(self, message_id, message, sender)
  if message_id == hash("init_complete") then
    -- All screens should be registered by now
    monarch.show(hash("main_menu"))
  end
  
  monarch.on_message(message_id, message, sender)
end
```

--------------------------------

### Dynamic Transitions Based on Previous Screen

Source: https://github.com/britzl/monarch/blob/master/_autodocs/examples-and-patterns.md

Implement different transition animations based on the screen the user is coming from. This example shows zooming in from 'gameplay' and fading in from the 'menu'.

```lua
local monarch = require "monarch.monarch"

function init(self)
  monarch.on_transition(hash ("game_over"), function(message_id, message, sender)
    if message_id == monarch.TRANSITION_SHOW_IN then
      local prev_screen = message.previous_screen
      
      if prev_screen == hash ("gameplay") then
        -- Zoom in from gameplay
        gui.set_scale(gui.get_node("panel"), vmath.vector3(0.5, 0.5, 1))
        gui.animate(gui.get_node("panel"), gui.PROP_SCALE, vmath.vector3(1, 1, 1), gui.EASING_OUTBACK, 0.6)
      else
        -- Fade in from menu
        gui.set_color(gui.get_node("panel"), vmath.vector4(1, 1, 1, 0))
        gui.animate(gui.get_node("panel"), gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), gui.EASING_OUTQUAD, 0.4)
      end
    end
  end)
end

function on_message(self, message_id, message, sender)
  monarch.on_message(message_id, message, sender)
  
  if message_id == monarch.TRANSITION_DONE then
    msg.post(sender, monarch.TRANSITION_DONE)
  end
end
```

--------------------------------

### Using Transition Helper Functions

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Quickly apply common slide and fade transitions using helper functions. These functions simplify the setup for predefined animation types and durations.

```lua
transitions.in_right_out_left(node, 0.5)           -- Slide right in, left out
transitions.in_left_out_right(node, 0.5)           -- Slide left in, right out
transitions.fade_in_out(node, 0.3)                 -- Fade animations
transitions.in_left_out_left(node, 0.5)            -- Both left
transitions.in_right_out_right(node, 0.5)          -- Both right
```

--------------------------------

### Screen Transition In Message Table

Source: https://github.com/britzl/monarch/blob/master/_autodocs/types.md

Sent to listeners when a screen transition in starts or finishes.

```lua
{
  screen = hash,
  previous_screen = hash  -- hash: Previous screen (may be nil)
}
```

--------------------------------

### Post Message Table Example

Source: https://github.com/britzl/monarch/blob/master/_autodocs/types.md

Used with `monarch.post()` to send custom serializable data to screens. Received in handlers set via `monarch.on_post()`.

```lua
{
  -- Any custom fields
  damage = 10,
  health = 100,
  message_text = "Hello"
}
```

--------------------------------

### Using Easing Functions in Transitions

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Demonstrates how to get an easing function's IN and OUT properties and apply them to a transition. Note that the IN/OUT naming is reversed from Defold's convention for clarity, where OUT is used for 'easing out' animations.

```lua
local easing = easings.QUAD()
-- easing.IN = gui.EASING_OUTQUAD
-- easing.OUT = gui.EASING_INQUAD

-- Use in transitions
transition.show_in(node, transitions.slide_in_right, easing.OUT, 0.5)
```

--------------------------------

### Retrieve Screen Data with monarch.data()

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Use `monarch.data()` to get data previously set when showing a screen. Ensure the `monarch` module is required.

```lua
local monarch = require "monarch.monarch"

monarch.show(hash("level"), nil, { level_id = 5, difficulty = "hard" })

-- Later, in the screen:
local screen_data = monarch.data(hash("level"))
-- screen_data = { level_id = 5, difficulty = "hard" }
```

--------------------------------

### Monarch Utilities API Reference

Source: https://github.com/britzl/monarch/blob/master/_autodocs/DOCUMENTATION_SUMMARY.md

Documentation for internal utilities, including the `async` module for coroutine-based execution and the `callback_tracker` module for callback coordination. Provides usage examples for custom code.

```APIDOC
## Monarch Utilities API Reference

### Description
Documents internal utility modules available for use in custom code, focusing on asynchronous operations and callback coordination.

### API Surface
- **`async` module**: For coroutine-based asynchronous execution.
- **`callback_tracker` module**: For callback coordination.
- **Usage Examples**: Demonstrates how to use these utilities in custom code.
```

--------------------------------

### Monarch Transitions Details (transitions.md)

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

Details the content of the transitions.md file, including API methods, predefined transitions, easing functions, helper methods, custom transition guides, and responsive transition handling.

```text
Transitions (api-reference/transitions.md):
- Transition API methods
- Predefined transitions (17 total)
- Easing functions (10 types)
- Helper methods (5 common patterns)
- Custom transition guide
- Multiple node examples
- Responsive transition handling
```

--------------------------------

### Monarch Screen Scripts Details (screen-scripts.md)

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

Details the content of the screen-scripts.md file, covering screen_proxy.script and screen_factory.script documentation, properties, message handlers, setup examples, and common patterns.

```text
Screen Scripts (api-reference/screen-scripts.md):
- screen_proxy.script documentation
- screen_factory.script documentation
- All properties documented
- Message handlers documented
- Setup examples
- Common patterns
```

--------------------------------

### Window Resizing Integration

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

This snippet demonstrates how to initialize the transition system and update it when the window is resized or the orientation changes. It shows how to create a transition, register it with Monarch, and handle the `window_resized` message to update the transition's state.

```APIDOC
## Window Resizing Integration

### Description
Integrates the Monarch transition system with window resize events to ensure transitions adapt to new dimensions.

### Usage
Initialize the transition system in `init` and call `self.transition.window_resized(width, height)` within the `on_message` function when a `window_resized` message is received.

### Code Example
```lua
local transitions = require "monarch.transitions.gui"

function init(self)
  self.transition = transitions.create(gui.get_node("root"))
    .show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.5)
  
  monarch.on_transition(hash("my_screen"), self.transition)
end

function on_message(self, message_id, message, sender)
  -- Notify transitions of window size change
  if message_id == hash("window_resized") then
    self.transition.window_resized(message.width, message.height)
  end
  
  monarch.on_message(message_id, message, sender)
end
```
```

--------------------------------

### Setting Up Basic Screen Transitions

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Create a transition object using `transitions.create` and chain methods like `show_in`, `show_out`, `back_in`, and `back_out` to define animation, easing, duration, and delay. Assign the transition to a screen using `monarch.on_transition`.

```lua
local transition = transitions.create(gui.get_node("root"))
  .show_in(transitions.slide_in_right, gui.EASING_OUTQUAD, 0.5, 0)
  .show_out(transitions.slide_out_left, gui.EASING_INQUAD, 0.5, 0)
  .back_in(transitions.slide_in_left, gui.EASING_OUTQUAD, 0.5, 0)
  .back_out(transitions.slide_out_right, gui.EASING_INQUAD, 0.5, 0)

monarch.on_transition(hash("screen_id"), transition)
```

--------------------------------

### Get Current Navigation Stack

Source: https://github.com/britzl/monarch/blob/master/_autodocs/README.md

Retrieves the current stack of screens managed by Monarch.

```lua
monarch.get_stack()
```

--------------------------------

### Screen Transition Out Message Table

Source: https://github.com/britzl/monarch/blob/master/_autodocs/types.md

Sent to listeners when a screen transition out starts or finishes.

```lua
{
  screen = hash,
  next_screen = hash      -- hash: Next screen (may be nil)
}
```

--------------------------------

### monarch.bottom

Source: https://github.com/britzl/monarch/blob/master/README_API.md

Retrieves the ID of the screen at the bottom of the stack. An optional offset can be provided to get screens further up the stack.

```APIDOC
## monarch.bottom([offset])

### Description
Get the id of the screen at the bottom of the stack.

### Parameters
#### Query Parameters
- **offset** (number) - Optional - Offset from the bottom of the stack

### Return
- **screen_id** (string|hash) - Id of the requested screen
```

--------------------------------

### monarch.SCREEN_TRANSITION_OUT_STARTED

Source: https://github.com/britzl/monarch/blob/master/README_API.md

Message sent when a screen has started to transition out. This event is received by listeners added via monarch.add_listener().

```APIDOC
## monarch.SCREEN_TRANSITION_OUT_STARTED

### Description
Message sent to listeners added using `monarch.add_listener()` when a screen has started to transition out.

### Parameters
#### Event Parameters
- **screen** (hash) - Id of the screen
- **next_screen** (hash) - Id of the next screen (if any)
```

--------------------------------

### Use Built-In GUI Transition Helpers

Source: https://github.com/britzl/monarch/blob/master/_autodocs/configuration.md

Implement common GUI animations for screen transitions using helper functions from `monarch.transitions.gui`. This approach is suitable for most GUI animation needs.

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

function init(self)
  local transition = transitions.in_right_out_left(gui.get_node("root"), 0.5)
  monarch.on_transition(hash("my_screen"), transition)
end
```

--------------------------------

### monarch.top

Source: https://github.com/britzl/monarch/blob/master/README_API.md

Retrieves the ID of the screen currently at the top of the stack. An optional offset can be provided to get screens further down the stack.

```APIDOC
## monarch.top([offset])

### Description
Get the id of the screen at the top of the stack.

### Parameters
#### Query Parameters
- **offset** (number) - Optional - Offset from the top of the stack, ie -1 to get the previous screen

### Return
- **screen_id** (string|hash) - Id of the requested screen
```

--------------------------------

### Check Queued Navigation Actions

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Gets the number of queued navigation actions. Use this to determine if there are pending navigation operations.

```lua
local monarch = require "monarch.monarch"

if monarch.queue_size() > 0 then
  print("There are queued navigation actions")
end
```

--------------------------------

### Initialize and Show First Screen

Source: https://github.com/britzl/monarch/blob/master/README.md

Ensures the screen script is initialized before showing the first screen. Delays the initial `monarch.show()` call by posting a message to the controller.

```lua
function init(self)
	msg.post("#", "show_first_screen")
end

function on_message(self, message_id, message, sender)
	monarch.show(hash("first_screen"))
end
```

--------------------------------

### Dump Formatted Stack Contents

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Gets a formatted string representation of the current screen stack. Useful for debugging purposes.

```lua
local monarch = require "monarch.monarch"

print(monarch.dump_stack())
-- Output:
-- 1 = menu
-- 2 = level_select
-- 3 = level
```

--------------------------------

### Show Different Monarch Screens

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Demonstrates how to show Monarch screens with varying levels of configuration, including simple display, options, and data with callbacks.

```lua
local monarch = require "monarch.monarch"

-- Simple show
monarch.show(hash("menu_screen"))

-- With options
monarch.show(hash("settings_screen"), { clear = true })

-- With data and callback
monarch.show(hash("level_screen"), { reload = false }, { level = 5 }, function()
  print("Level screen is now visible")
end)
```

--------------------------------

### Create and Use Callback Tracker

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/utilities.md

Demonstrates how to create a callback tracker, track multiple individual callbacks, register a final callback to be executed when all tracked callbacks are invoked, and then invoke the tracked callbacks.

```lua
local callback_tracker = require "monarch.utils.callback_tracker"

local tracker = callback_tracker.create()

-- Track multiple callbacks
local cb1 = tracker.track()
local cb2 = tracker.track()
local cb3 = tracker.track()

-- Execute when all are called
tracker.when_done(function()
  print("All callbacks were invoked")
end)

-- Invoke callbacks in any order
cb1()
cb2()
cb3()  -- when_done callback is called here
```

--------------------------------

### Get Current Screen Stack

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Retrieves the current screen stack as a table of screen IDs. Primarily used for unit testing.

```lua
local monarch = require "monarch.monarch"

local stack = monarch.get_stack()
-- stack = { hash("menu"), hash("level_select"), hash("level") }
```

--------------------------------

### monarch.on_transition

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Sets up a callback function to be executed when a screen undergoes a transition (showing in, showing out, back in, back out). This allows for custom animation or logic during screen changes.

```APIDOC
## monarch.on_transition(screen_id, fn)

### Description
Set up a function to be called when a screen should transition in or out. This allows defining custom transition behavior.

### Method
monarch.on_transition

### Parameters
#### Path Parameters
- **screen_id** (string|hash) - Required - Id of the screen
- **fn** (function|nil) - Required - Function to handle transitions, or nil to remove transition handler

### Behavior
- Function receives: `(message_id, message, sender)`
- Message ids: `TRANSITION_SHOW_IN`, `TRANSITION_SHOW_OUT`, `TRANSITION_BACK_IN`, `TRANSITION_BACK_OUT`
- Must call `monarch.on_message()` in the same script to process Monarch messages
- Must send `TRANSITION_DONE` message back to sender when transition is complete
- Message contains `previous_screen` for SHOW_IN/BACK_OUT or `next_screen` for SHOW_OUT/BACK_IN
```

--------------------------------

### monarch.bottom([offset])

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Retrieves the screen ID at the bottom of the stack, which is the first screen that was shown. An optional offset can be used to get screens further up the stack.

```APIDOC
## monarch.bottom([offset])

### Description
Get the screen id at the bottom of the stack (first screen shown).

### Signature
```lua
monarch.bottom([offset: number]) -> string|hash|nil
```

### Parameters
#### Path Parameters
- **offset** (number) - Optional - Offset from the bottom (1 for the next screen up)

### Returns
#### Success Response
- **string or hash or nil** - The id of the requested screen, or nil if the stack doesn't have that many screens
```

--------------------------------

### Monarch Transitions System API Reference

Source: https://github.com/britzl/monarch/blob/master/_autodocs/DOCUMENTATION_SUMMARY.md

Details the Transitions system API, including transition instances like `show_in`, `show_out`, `back_in`, `back_out`, and all predefined transitions such as slide, scale, fade, and instant. It also covers helper creators, custom transition implementation, and responsive transitions.

```APIDOC
## Monarch Transitions System API Reference

### Description
Provides documentation for the Monarch Transitions system, detailing the API for transition instances and predefined transitions. Includes guidance on custom transition implementation and handling responsive transitions.

### API Surface
- **Transition Instances**: `show_in()`, `show_out()`, `back_in()`, `back_out()`.
- **Predefined Transitions**: Slide (8 directions), Scale (in/out), Fade (in/out), Instant.
- **Helper Transition Creators**: 5 common patterns.
- **Custom Transitions**: Implementation guide.
- **Responsive Transitions**: Handling window resizing and layout changes.
- **Easing Functions**: 10 types with IN/OUT variants.
- **Message Details**: Information on transition messages and context data.
```

--------------------------------

### Get Top Screen ID with monarch.top()

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Retrieve the ID of the currently active screen using `monarch.top()`. An optional offset can be provided to access screens further down the stack.

```lua
local monarch = require "monarch.monarch"

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

-- Get the previous screen (one below the top)
local previous = monarch.top(-1)
```

--------------------------------

### Import Monarch Modules

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Import the necessary Monarch libraries for screen management and transitions.

```lua
local monarch = require "monarch.monarch"
local transitions = require "monarch.transitions.gui"
local easings = require "monarch.transitions.easings"
```

--------------------------------

### Show a Screen

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Display a new screen. Optionally, pass data or clear the stack.

```lua
monarch.show(hash("menu"))
```

```lua
monarch.show(hash("level"), nil, { level_id = 5 })
```

```lua
monarch.show(hash("popup"), { clear = true })
```

--------------------------------

### Monarch Documentation Structure

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

This outlines the hierarchical structure of the Monarch documentation, including main index, quick reference, guides, API references, and summary files.

```text
=== DOCUMENTATION STRUCTURE ===

✓ Main Index: README.md
✓ Quick Reference: quick-reference.md
✓ Configuration Guide: configuration.md
✓ Type Reference: types.md
✓ Examples & Patterns: examples-and-patterns.md
✓ API Reference Directory: api-reference/
  ✓ monarch.md - Core API (1351 lines)
  ✓ screen-scripts.md - Screen setup
  ✓ transitions.md - Animation system
  ✓ utilities.md - Internal utilities

✓ Documentation Summary: DOCUMENTATION_SUMMARY.md

Total Files: 10
Total Lines: 4,855+
```

--------------------------------

### Handle Screen Transitions with monarch.on_transition

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Set up a function to be called when a screen should transition in or out. This allows defining custom transition behavior. Remember to call monarch.on_message() and send TRANSITION_DONE.

```lua
local monarch = require "monarch.monarch"

function init(self)
  monarch.on_transition(hash("menu"), function(message_id, message, sender)
    if message_id == monarch.TRANSITION_SHOW_IN then
      -- Animate the screen in
      gui.animate(gui.get_node("root"), gui.PROP_POSITION, vmath.vector3(0, 0, 0), gui.EASING_OUTQUAD, 0.5)
    elseif message_id == monarch.TRANSITION_SHOW_OUT then
      -- Animate the screen out
      gui.animate(gui.get_node("root"), gui.PROP_POSITION, vmath.vector3(0, -1080, 0), gui.EASING_INQUAD, 0.5)
    end
  end)
end

function on_message(self, message_id, message, sender)
  monarch.on_message(message_id, message, sender)
  
  -- Signal when transition is done
  if message_id == hash("animation_done") then
    msg.post(sender, monarch.TRANSITION_DONE)
  end
end
```

--------------------------------

### Define a Custom Transition Function

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Create a custom transition function with a specific signature to define unique animation behaviors. This example fades and scales a GUI node.

```lua
local function custom_fade_scale(node, state, easing, duration, delay, cb)
  -- node: the GUI node
  -- state: object with .pos, .scale, etc.
  -- easing: GUI easing constant
  -- duration: animation duration
  -- delay: animation delay
  -- cb: callback when animation completes
  
  gui.set_scale(node, vmath.vector3(0.5, 0.5, 1))
  gui.set_color(node, vmath.vector4(1, 1, 1, 0))
  
  -- Animate scale
  gui.animate(node, gui.PROP_SCALE, state.scale, easing, duration, delay)
  
  -- Animate color/alpha (with callback)
  gui.animate(node, gui.PROP_COLOR, vmath.vector4(1, 1, 1, 1), easing, duration, delay, cb)
end

-- Use it
local transition = transitions.create(gui.get_node("root"))
  .show_in(custom_fade_scale, gui.EASING_OUTQUAD, 0.5)
```

--------------------------------

### Basic Show/Back Navigation

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Shows a new screen and navigates back. Use `monarch.show` to display a screen and `monarch.back` to close the current one.

```lua
monarch.show(hash("menu"))
monarch.back()
```

--------------------------------

### Helper for Common Slide Transitions

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Uses a helper method to quickly set up common slide-in and slide-out transitions for a GUI node. This simplifies the configuration for standard screen navigation animations.

```lua
local transitions = require "monarch.transitions.gui"
local easings = require "monarch.transitions.easings"
local monarch = require "monarch.monarch"

function init(self)
  local node = gui.get_node("root")
  
  -- Slide in from right, out to left (and reverse for back)
  -- Duration 0.5s, delay 0.1s, using QUAD easing
  local transition = transitions.in_right_out_left(node, 0.5, 0.1, easings.QUAD())
  monarch.on_transition(hash("my_screen"), transition)
end
```

--------------------------------

### Get Bottom Screen ID with monarch.bottom()

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Access the ID of the first screen shown using `monarch.bottom()`. An optional offset allows retrieval of screens higher up the stack.

```lua
local monarch = require "monarch.monarch"

-- Get the first screen (bottom of stack)
local first = monarch.bottom()

-- Get the second screen from the bottom
local second = monarch.bottom(1)
```

--------------------------------

### Wait for Screen Preload Completion

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Set up a callback to execute when a screen finishes preloading. If the screen is already preloaded, the callback runs immediately. Useful for showing screens instantly after they are ready.

```lua
local monarch = require "monarch.monarch"

-- Wait for preload to complete
monarch.when_preloaded(hash("startup_screen"), function(screen_id)
  -- Now show it instantly
  monarch.show(screen_id)
end)
```

--------------------------------

### Show Settings Popup from Gameplay Screen

Source: https://github.com/britzl/monarch/blob/master/_autodocs/examples-and-patterns.md

This script handles input on the gameplay screen to show the settings popup. It requires the `monarch` library.

```lua
local monarch = require "monarch.monarch"

function on_input(self, action_id, action)
  if action_id == hash("settings") and action.released then
    monarch.show(hash("settings_popup"))
  end
end
```

--------------------------------

### transition.show_in

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/transitions.md

Adds a transition effect when a screen is shown. This is typically used for initial screen appearances.

```APIDOC
## transition.show_in(node, fn, easing, duration, [delay])

### Description
Add a transition when the screen is shown.

### Parameters
#### Path Parameters
- **node** (node) - Required - GUI node to animate
- **fn** (function) - Required - Transition function (e.g., `transitions.slide_in_right`)
- **easing** (constant) - Required - GUI easing constant (e.g., `gui.EASING_OUTQUAD`)
- **duration** (number) - Required - Animation duration in seconds
- **delay** (number) - Optional - Delay before animation starts in seconds

### Request Example
```lua
transition.show_in(gui.get_node("root"), transitions.fade_in, gui.EASING_OUTQUAD, 0.5, 0)
```

### Returns
The transition instance (for method chaining)
```

--------------------------------

### Import Transitions GUI Module

Source: https://github.com/britzl/monarch/blob/master/_autodocs/README.md

Use this require statement to import the Monarch transitions GUI module.

```lua
require "monarch.transitions.gui"
```

--------------------------------

### Monarch API Reference Details (monarch.md)

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

Details the content of the monarch.md file, highlighting the number of functions, signature completeness, parameter tables, return values, behavior notes, and code examples.

```text
API Reference (api-reference/monarch.md):
- 50+ functions documented
- Full signatures with parameter types
- Parameters tables
- Return value descriptions
- Behavior notes
- Code examples for each function
- Related function references
```

--------------------------------

### Set Up Message Receiver

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Use monarch.on_post to configure a screen to receive messages posted via monarch.post(). Ensure monarch.on_message() is called within the on_message handler.

```lua
local monarch = require "monarch.monarch"

function init(self)
  monarch.on_post(hash("menu"), function(message_id, message, sender)
    if message_id == hash("play_sound") then
      -- Handle message
    end
  end)
  -- Must call on_message to process Monarch messages
  monarch.on_message(message_id, message, sender)
end

function on_message(self, message_id, message, sender)
  monarch.on_message(message_id, message, sender)
end
```

--------------------------------

### monarch.on_post

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Sets up a screen to receive messages posted via `monarch.post()`.

```APIDOC
## monarch.on_post(screen_id, fn_or_url)

### Description
Set up a screen to receive messages posted via `monarch.post()`.

### Signature
```lua
monarch.on_post(screen_id: string|hash, fn_or_url: function|url|string)
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| screen_id | string or hash | Yes | — | Id of the screen to set up |
| fn_or_url | function or url | Yes | — | Either a function that handles messages or a URL to send messages to |

### Returns

Nothing.

### Behavior

- If a function is provided: Must call `monarch.on_message()` in the same script's `on_message()` handler
- If a URL is provided: Messages are sent directly to that URL via `msg.post()`
- Callback signature: `fn(message_id, message, sender)`
```

--------------------------------

### Show a Screen

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Displays a new screen. You can optionally pass data to the screen or clear the stack before showing.

```APIDOC
## Show a Screen

### Description
Displays a new screen. You can optionally pass data to the screen or clear the stack before showing.

### Method
`monarch.show(screen_id, data, options)`

### Parameters
#### Path Parameters
- **screen_id** (hash) - Required - The identifier of the screen to show.
- **data** (table) - Optional - Data to pass to the screen.
- **options** (table) - Optional - Configuration options, e.g., `{ clear = true }`.

### Request Example
```lua
monarch.show(hash("menu"))
monarch.show(hash("level"), nil, { level_id = 5 })
monarch.show(hash("popup"), { clear = true })
```
```

--------------------------------

### Monarch Verification Checklist

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

This checklist confirms the completeness and quality of Monarch documentation, verifying that all functions, constants, scripts, transitions, easing functions, and configuration options are documented with code examples and adhere to technical reference standards.

```text
=== VERIFICATION CHECKLIST ===

✓ All exported functions documented
✓ All constants documented
✓ All scripts documented
✓ All transition functions documented
✓ All easing functions documented
✓ All configuration options documented
✓ Code examples are non-test code
✓ No introductions or marketing
✓ No tutorials
✓ Pure technical reference
✓ Clear organization
✓ Cross-referenced
✓ Properly formatted markdown
✓ Exhaustive coverage
✓ Professional quality
```

--------------------------------

### Monarch Documentation Quality Checklist

Source: https://github.com/britzl/monarch/blob/master/_autodocs/VERIFICATION.txt

This checklist outlines the quality standards for Monarch documentation, including complete signatures, parameter tables, return values, code examples, behavior notes, error handling, best practices, and cross-referencing.

```text
=== DOCUMENTATION QUALITY ===

✓ Complete function signatures with types
✓ Parameter tables for all parameters
✓ Return value documentation
✓ Usage code examples (60+ total)
✓ Behavior notes for non-obvious features
✓ Error handling guidance
✓ Best practices documented
✓ Configuration options mapped
✓ Data structure definitions
✓ Message formats documented
✓ Cross-references between related items
✓ Source file paths referenced
```

--------------------------------

### monarch.back

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Navigates back to the previous screen by removing the current screen from the stack and showing the one beneath it. This is the inverse of `show()`.

```APIDOC
## monarch.back

### Description
Navigates back to the previous screen by removing the current screen from the stack and showing the one beneath it. This is the inverse of `show()`.

### Method
`monarch.back([options: table], [data: any], [callback: function])`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **options** (table) - Optional - Navigation options (see Options table below)
- **data** (any) - Optional - Data to set on the previous screen before showing it
- **callback** (function) - Optional - Invoked when the previous screen is fully visible

### Options Table
- **sequential** (boolean) - Default: false - If true, waits for the current screen to finish transitioning out before showing the previous screen

### Returns
- **boolean** - Same as `monarch.show()`.

### Behavior
- Queued: This operation is added to the action queue
- Stack manipulation: The top screen is removed from the stack
- Transition: `TRANSITION_BACK_OUT` is triggered on the current screen; `TRANSITION_BACK_IN` on the previous
- Focus: Input focus is released from the current screen and acquired by the previous screen
- Visibility: The previous screen becomes visible
```

--------------------------------

### Internal usage pattern for async operations

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/utilities.md

Demonstrates an internal usage pattern for the async module, showing how to chain asynchronous operations like loading and transitioning screens before resuming.

```lua
local async = require "monarch.utils.async"

function show_screen(screen)
  return async(function(await, resume)
    -- Load the screen
    await(load_screen, screen, resume)
    
    -- Transition in
    await(transition_in, screen, resume)
    
    -- Both operations complete before resume() callback is called
  end)
end
```

--------------------------------

### Main Menu Navigation Script

Source: https://github.com/britzl/monarch/blob/master/_autodocs/examples-and-patterns.md

Handles transitions and input for the main menu screen. Use this script for screens that initiate navigation.

```lua
local monarch = require "monarch.monarch"

function init(self)
  monarch.on_transition(hash("main_menu"), function(message_id, message, sender)
    if message_id == monarch.TRANSITION_SHOW_IN then
      gui.animate(gui.get_node("root"), gui.PROP_POSITION, vmath.vector3(0, 0, 0), gui.EASING_OUTQUAD, 0.5)
    elseif message_id == monarch.TRANSITION_SHOW_OUT then
      gui.animate(gui.get_node("root"), gui.PROP_POSITION, vmath.vector3(-1080, 0, 0), gui.EASING_INQUAD, 0.5)
    end
  end)
end

function on_message(self, message_id, message, sender)
  monarch.on_message(message_id, message, sender)
  
  if message_id == monarch.TRANSITION_DONE then
    msg.post(sender, monarch.TRANSITION_DONE)
  end
end

function on_input(self, action_id, action)
  if action_id == hash("play") and action.released then
    monarch.show(hash("level_select"))
  end
  if action_id == hash("settings") and action.released then
    monarch.show(hash("settings"))
  end
end
```

--------------------------------

### Monarch Core API Reference

Source: https://github.com/britzl/monarch/blob/master/_autodocs/DOCUMENTATION_SUMMARY.md

This section details the complete core API for Monarch, covering screen navigation, state queries, preloading, registration, message handling, callbacks, and utility functions. Each exported function is documented with its signature, parameters, return values, behavior notes, and code examples.

```APIDOC
## Monarch Core API Reference

### Description
Provides comprehensive documentation for the core Monarch API, including functions for screen navigation (show, replace, back, hide, clear), state queries (is_visible, is_top), preloading (preload, when_preloaded), registration (register_proxy, register_factory), message handling (post, on_post), callbacks (on_transition, on_focus_changed), and utilities (set_timestep_below_popup, debug).

### API Surface
- **Screen Navigation**: `show()`, `replace()`, `back()`, `hide()`, `clear()`
- **Screen State Queries**: `is_visible()`, `is_top()`, `is_popup()`
- **Preloading**: `preload()`, `when_preloaded()`, `is_preloading()`, `unload()`
- **Registration**: `register_proxy()`, `register_factory()`, `unregister()`
- **Message Handling**: `post()`, `on_post()`, `add_listener()`, `remove_listener()`
- **Callbacks**: `on_transition()`, `on_focus_changed()`, `on_message()`
- **Utilities**: `set_timestep_below_popup()`, `debug()`, `get_stack()`

### Documentation Details for Each Function
- Complete signature with types
- Parameters table (name, type, required, default, description)
- Return values
- Behavior notes
- Realistic code examples
- Related functions
```

--------------------------------

### Utilities

Source: https://github.com/britzl/monarch/blob/master/_autodocs/README.md

Documentation for internal utility modules, including async utilities and callback coordination.

```APIDOC
## Utilities

### `async` module
- Provides utilities for working with coroutines.

### `callback_tracker` module
- Offers tools for coordinating multiple callbacks.
```

--------------------------------

### Import Async Utils Module

Source: https://github.com/britzl/monarch/blob/master/_autodocs/README.md

Use this require statement to import the Monarch asynchronous utilities module.

```lua
require "monarch.utils.async"
```

--------------------------------

### Show Screen with Callback

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Shows a screen and executes a callback function when it becomes visible. The callback is provided as the fourth argument to `monarch.show`.

```lua
monarch.show(hash("screen"), nil, nil, function()
  print("Screen is now visible")
end)
```

--------------------------------

### Screen Settings Configuration

Source: https://github.com/britzl/monarch/blob/master/_autodocs/types.md

Use this table when registering a screen with monarch.register_proxy() or monarch.register_factory(). These settings control how the screen behaves in the display stack.

```lua
{
  popup = false,
  popup_on_popup = false,
  timestep_below_popup = 1,
  screen_keeps_input_focus_when_below_popup = false,
  others_keep_input_focus_when_below_screen = false,
  auto_preload = false
}
```

--------------------------------

### monarch.add_listener

Source: https://github.com/britzl/monarch/blob/master/_autodocs/api-reference/monarch.md

Adds a URL to be notified of all screen transition events.

```APIDOC
## monarch.add_listener([url])

### Description
Add a URL to be notified of all screen transition events.

### Signature
```lua
monarch.add_listener([url: url])
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| url | url | No | current URL | URL to notify of transition events |

### Returns

Nothing.

### Behavior

- Messages sent: `SCREEN_TRANSITION_IN_STARTED`, `SCREEN_TRANSITION_IN_FINISHED`, `SCREEN_TRANSITION_OUT_STARTED`, `SCREEN_TRANSITION_OUT_FINISHED`, `SCREEN_TRANSITION_FAILED`
- Multiple listeners can be added
- Each listener is notified of every screen transition
```

--------------------------------

### Assign Transitions to Multiple Nodes

Source: https://github.com/britzl/monarch/blob/master/README_TRANSITIONS.md

Configure transitions for multiple GUI nodes simultaneously by creating a transition instance without specifying a node initially, then chaining `show_in` calls for each target node.

```lua
function init(self)
	local transition = transitions.create() -- note that no node is passed to transition.create()!
		.show_in(gui.get_node("node1"), transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
		.show_in(gui.get_node("node2"), transitions.slide_in_right, gui.EASING_OUTQUAD, 0.6, 0)
end
```

--------------------------------

### Monarch Transition Handler

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Manage screen transition animations (show in/out, back in/out). Remember to send the TRANSITION_DONE message when finished.

```lua
monarch.on_transition(hash("screen_id"), function(message_id, message, sender)
  if message_id == monarch.TRANSITION_SHOW_IN then
    -- Animate in
  elseif message_id == monarch.TRANSITION_SHOW_OUT then
    -- Animate out
  elseif message_id == monarch.TRANSITION_BACK_IN then
    -- Animate back in
  elseif message_id == monarch.TRANSITION_BACK_OUT then
    -- Animate back out
  end
  
  -- MUST send when done
  msg.post(sender, monarch.TRANSITION_DONE)
end)
```

--------------------------------

### Go Back

Source: https://github.com/britzl/monarch/blob/master/_autodocs/quick-reference.md

Navigates back to the previous screen in the stack. Optionally restore screen data.

```APIDOC
## Go Back

### Description
Navigates back to the previous screen in the stack. Optionally restore screen data.

### Method
`monarch.back(data, options)`

### Parameters
#### Path Parameters
- **data** (table) - Optional - Data to pass to the previous screen.
- **options** (table) - Optional - Configuration options, e.g., `{ restore = true }`.

### Request Example
```lua
monarch.back()
monarch.back(nil, { restore = true })
```
```