britzl/monarch/monarch.monarch

Monarch is a screen manager for the Defold game engine.

GitHub: britzl/monarch — pinned to 2fe3aed
1. Pick a release from britzl/monarch releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
2. Run bunx @defold-typescript/cli resolve to materialize its types.
3. Import it under a namespace alias of your choice:
```
import * as monarch from "monarch.monarch"
```

Functions

debug()
in_stack(screen_id: ScreenId): boolean
is_top(screen_id: ScreenId): boolean
is_visible(screen_id: ScreenId): boolean
is_loaded(screen_id: ScreenId): boolean
is_popup(screen_id: ScreenId): boolean
register_proxy(screen_id: ScreenId, proxy: Url, settings: RegisterProxyOptions)
register_factory(screen_id: ScreenId, factory: Url, settings: RegisterProxyOptions)
unregister(screen_id: ScreenId)
data(screen_id: ScreenId): Data
screen_exists(screen_id: ScreenId): boolean
is_busy(): boolean
show(screen_id: ScreenId, options?: ShowOptions, data?: Data, callback?: Callback)
replace(screen_id: ScreenId, options?: ReplaceOptions, data?: Data, callback?: Callback)
hide(screen_id: ScreenId, callback?: Callback): boolean
clear(callback?: Callback)
back(options?: BackOptions, data?: Data, callback?: Callback)
is_preloading(screen_id: ScreenId): boolean
is_preloaded(screen_id: ScreenId): boolean
when_preloaded(screen_id: ScreenId, callback: (screen_id?: ScreenId) => void)
preload(screen_id: ScreenId, options?: PreloadOptions, callback?: Callback)
has_missing_resources(screen_id: ScreenId): boolean
unload(screen_id: ScreenId, callback?: Callback)
post(screen_id: ScreenId, message_id: Hash | string, message?: Message): LuaMultiReturn<[ boolean, string | undefined ]>
on_message(message_id: Hash | string, message: Message, sender: Url)
get_stack(): ScreenId[]
top(offset?: number): ScreenId
bottom(offset?: number): ScreenId
set_timestep_below_popup(screen_id: ScreenId, timestep: number)
on_transition(screen_id: ScreenId, fn: (message_id: string, message: Message, sender: Url) => void)
on_focus_changed(screen_id: ScreenId, fn: (message_id: string, message: Message, sender: Url) => void)
on_post(screen_id: ScreenId, fn_or_url: Callback | Url | string)
add_listener(url?: Url)
remove_listener(url?: Url)
dump_stack(): string
queue_size(): number

`debug()`

Enable verbose logging of the internals of Monarch.

`in_stack(screen_id: ScreenId): boolean`

Check if a screen exists in the current screen stack

Parameters

screen_id: ScreenId

Returns

boolean — true of the screen is in the stack

`is_top(screen_id: ScreenId): boolean`

Check if a Monarch screen is at the top of the view stack.

Parameters

screen_id: ScreenId

Returns

boolean — true if the screen is at the top of the stack

`is_visible(screen_id: ScreenId): boolean`

Check if a Monarch screen is visible.

Parameters

screen_id: ScreenId

Returns

boolean — true if the screen is visible

`is_loaded(screen_id: ScreenId): boolean`

Check if a screen is loaded

Parameters

screen_id: ScreenId

Returns

boolean — true if the screen is loaded

`is_popup(screen_id: ScreenId): boolean`

Check if a screen is a popup

Parameters

screen_id: ScreenId

Returns

boolean — true if the screen is a popup

`register_proxy(screen_id: ScreenId, proxy: Url, settings: RegisterProxyOptions)`

Register a new screen contained in a collection proxy. This is done automatically by the screen_proxy.script. It is expected that the caller of this function is a script component attached to the same game object as the proxy. This is required since monarch will acquire and release input focus of the game object where the proxy is attached.

Parameters

screen_id: ScreenId — Unique id of the screen
proxy: Url — URL to the collection proxy containing the screen
settings: RegisterProxyOptions — Settings table for screen. Accepted values:

popup - true if 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
timestep_below_popup - Timestep to set on proxy when below a popup
screen_keeps_input_focus_when_below_popup - If this screen should keep input focus when below a popup
others_keep_input_focus_when_below_screen - If screens below this screen should keep input focus
auto_preload - true if the screen should be automatically preloaded

`register_factory(screen_id: ScreenId, factory: Url, settings: RegisterProxyOptions)`

Register a new screen contained in a collection factory. This is done automatically by the screen_factory.script. It is expected that the caller of this function is a script component attached to the same game object as the factory. This is required since monarch will acquire and release input focus of the game object where the factory is attached.

Parameters

screen_id: ScreenId — Unique id of the screen
factory: Url — URL to the collection factory containing the screen
settings: RegisterProxyOptions — Settings table for screen. Accepted values:

popup - true if 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
screen_keeps_input_focus_when_below_popup - If this screen should keep input focus when below a popup
others_keep_input_focus_when_below_screen - If screens below this screen should keep input focus
auto_preload - true if the screen should be automatically preloaded

`unregister(screen_id: ScreenId)`

Unregister a screen This is done automatically by the screen.script

Parameters

screen_id: ScreenId — Id of the screen to unregister

`data(screen_id: ScreenId): Data`

Get data associated with a screen

Parameters

screen_id: ScreenId — Id of the screen to get data for

Returns

Data — Data associated with the screen

`screen_exists(screen_id: ScreenId): boolean`

Check if a Monarch screen exists.

Parameters

screen_id: ScreenId — Id of the screen to check if is registered

Returns

boolean — True or False if the screen id is registered or not

`is_busy(): boolean`

Check if Monarch is busy showing and/or hiding a screen.

Returns

boolean — true if busy

`show(screen_id: ScreenId, options?: ShowOptions, data?: Data, callback?: Callback)`

Show a Monarch screen.

Parameters

screen_id: ScreenId — Id of the screen to check if is registered
options?: ShowOptions — 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
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.
sequential - Set to true to wait for the previous screen to show itself out before starting the show in transition even when transitioning to a different scene ID.
no_stack - Set to true to load the screen without adding it to the screen stack.
pop - The number of screens to pop from the stack before adding the new one.
data?: Data — Optional data to set on the screen. Can be retrieved by the data() function
callback?: Callback — Optional callback to invoke when screen is shown

`replace(screen_id: ScreenId, options?: ReplaceOptions, data?: Data, callback?: Callback)`

Replace the top of the stack with a new screen.

Parameters

screen_id: ScreenId — Id of the screen to show.
options?: ReplaceOptions — Table with options when showing the screen (can be nil). Valid values:
clear {boolean} - Set to true if the stack should be cleared down to an existing instance of the screen.
reload {boolean} - Set to true if the 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.
no_stack {boolean} - Set to true to load the screen without adding it to the screen stack.
data?: Data — Optional data to set on the screen. Can be retrieved by the data() function.
callback?: Callback — Optional callback to invoke when the screen is shown.

`hide(screen_id: ScreenId, callback?: Callback): boolean`

Hide a screen. The screen must either be at the top of the stack or visible but not added to the stack (through the no_stack option).

Parameters

screen_id: ScreenId — Id of the screen to hide.
callback?: Callback — Optional callback to invoke when the screen is hidden.

Returns

boolean — True if successfully hiding, false if busy or for some other reason unable to hide the screen.

`clear(callback?: Callback)`

Clear the stack completely. Any visible screens will be hidden by navigating back out from them.

Parameters

callback?: Callback — Optional callback to invoke when the stack has been cleared.

`back(options?: BackOptions, data?: Data, callback?: Callback)`

Go back to the previous screen in the stack.

Parameters

options?: BackOptions — Table with options when backing out from the screen (can be nil). Valid values:
sequential {boolean} - Set to true to wait for the current screen to hide itself out before starting the back in transition even when transitioning to a different scene ID.
data?: Data — Optional data to set for the previous screen.
callback?: Callback — Optional callback to invoke when the previous screen is visible again.

`is_preloading(screen_id: ScreenId): boolean`

Check if a screen is preloading via monarch.preload() or automatically via the Preload screen option.

Parameters

screen_id: ScreenId — Screen id.

Returns

boolean — True if preloading, false otherwise.

`is_preloaded(screen_id: ScreenId): boolean`

Parameters

screen_id: ScreenId

Returns

boolean

`when_preloaded(screen_id: ScreenId, callback: (screen_id?: ScreenId) => void)`

Invoke a callback when a specific screen has been preloaded. This is mainly useful on app start when wanting to show a screen that has the Preload flag set (since it will immediately start to load which would prevent a call to monarch.show from having any effect).

Parameters

screen_id: ScreenId — Id of the screen to monitor for preload completion.
callback: (screen_id?: ScreenId) => void — Callback to invoke when the screen has been preloaded.

`preload(screen_id: ScreenId, options?: PreloadOptions, callback?: Callback)`

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.

Parameters

screen_id: ScreenId — Id of the screen to preload.
options?: PreloadOptions — Options for preloading the screen.
callback?: Callback — Optional callback to invoke when the screen is loaded.

`has_missing_resources(screen_id: ScreenId): boolean`

Check if a screen has missing resources, always returns false for factory

Parameters

screen_id: ScreenId — Id of the screen to preload

Returns

boolean

`unload(screen_id: ScreenId, callback?: Callback)`

Unload a preloaded monarch screen.

Parameters

screen_id: ScreenId — Id of the screen to unload.
callback?: Callback — Optional callback to invoke when the screen is unloaded.

`post(screen_id: ScreenId, message_id: Hash | string, message?: Message): LuaMultiReturn<[ boolean, string | undefined ]>`

Post a message to a screen using msg.post.

Parameters

screen_id: ScreenId — Id of the screen to send the message to.
message_id: Hash | string — Id of the message to send.
message?: Message — Optional message data to send.

Returns

LuaMultiReturn<[ boolean, string | undefined ]> — result - True if the message is sent successfully.

`on_message(message_id: Hash | string, message: Message, sender: Url)`

Parameters

message_id: Hash | string
message: Message
sender: Url

`get_stack(): ScreenId[]`

Get a list of IDs for the current screen stack. (Primarily used for unit testing, but could have uses outside testing.)

Returns

ScreenId[] — Table with screen IDs. The first entry is at the bottom of the stack, and the last value is at the top (and currently visible).

`top(offset?: number): ScreenId`

Get the screen on top of the stack.

Parameters

offset?: number — Optional offset from the top of the stack (e.g., -1 for the previous screen).

Returns

ScreenId — Id of the requested screen.

`bottom(offset?: number): ScreenId`

Get the screen at the bottom of the stack.

Parameters

offset?: number — Optional offset from the bottom of the stack.

Returns

ScreenId — Id of the requested screen.

`set_timestep_below_popup(screen_id: ScreenId, timestep: number)`

Set the timestep to apply for a screen when below a popup.

Parameters

screen_id: ScreenId — Id of the screen to change the timestep setting for.
timestep: number — Timestep to apply.

`on_transition(screen_id: ScreenId, fn: (message_id: string, message: Message, sender: Url) => void)`

Set a function to call when a transition should be started. The function will receive (message_id, message, sender). IMPORTANT! You must call monarch.on_message() from the same script as this function was called.

Parameters

screen_id: ScreenId — Screen id to associate the transition with.
fn: (message_id: string, message: Message, sender: Url) => void — Transition handler function.

`on_focus_changed(screen_id: ScreenId, fn: (message_id: string, message: Message, sender: Url) => void)`

Set a function to call when a screen gains or loses focus. The function will receive (message_id, message, sender). IMPORTANT! You must call monarch.on_message() from the same script as this function was called.

Parameters

screen_id: ScreenId — Screen id to associate the focus listener function with.
fn: (message_id: string, message: Message, sender: Url) => void — Focus listener function.

`on_post(screen_id: ScreenId, fn_or_url: Callback | Url | string)`

Set either a function to be called when msg.post() is called on a specific screen or a URL where the message is sent. IMPORTANT! If you provide a function, you must also make sure to call monarch.on_message(message_id, message, sender) from the same script as this function was called.

Parameters

screen_id: ScreenId — Screen id to associate the message listener function with.
fn_or_url: Callback | Url | string — The function to call or URL to send the message to.

`add_listener(url?: Url)`

Add a listener to be notified when screens are shown or hidden.

Parameters

url?: Url — The url to notify, undefined for the current url.

`remove_listener(url?: Url)`

Remove a previously added listener.

Parameters

url?: Url — The url to remove, nil for current url.

`dump_stack(): string`

Returns

string

`queue_size(): number`

Returns

number