Scene Management Actions

Built-in authoring reference for Mercury 1.0.1. All actions.

Animate Light Emitter

Transitions one numeric or color property of one Light Emitter in either 2D or 3D. Other emitters and properties retain their state.

Reference key: animateLightEmitter.

Editor category: Scene Management > Weather and Lighting.

Parameter	Type	Optional	Details
Emitter Value	objectComponentProperty	No	A named Light Emitter component property on an Object Parameter.
Value	mixed	No	Expression or literal value.
Seconds	number	No	Expression or literal value. Default: 0.5.
Ease	enum	No	Choose one of the listed options. Choices: linear, easeIn, easeOut, easeInOut. Default: “easeInOut”.

Cancel Asset Preparation

Stops this request and releases its interest. Shared work needed by another Scene or request continues.

Reference key: cancelAssetPreparation.

Editor category: Scene Management > Asset Loading.

Parameter	Type	Optional	Details
Preparation token	text	No	Text value; some actions also accept $global names.

Change Ambient Weather Property

Changes one retained screen-space weather property while preserving the other. Kind none clears the visible effect without discarding its intensity.

Reference key: setWeatherProperty.

Editor category: Scene Management > Weather and Lighting.

Example: Change Kind to fog, then change Intensity to 0.7.

Parameter	Type	Optional	Details
Property	enum	No	Choose one of the listed options. Choices: kind, intensity. Default: “kind”.
Value	mixed	No	Kind accepts rain, snow, storm, fog, or none. Intensity accepts a number from 0 to 1. Default: “rain”. Shown when Property has a selection.

Change Light Property

Changes exactly one property of one 2D light. Optional duration belongs to that same property transition; unrelated light state is preserved.

Reference key: setLightProperty.

Editor category: Scene Management > Weather and Lighting.

Example: Change Light Property “hall” intensity to 1 over 2 seconds.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Light	text	Yes	A scene light by name; blank = this object’s own light.
Property	enum	No	Choose one of the listed options. Choices: color, radius, intensity, flicker, flicker speed, spot angle, spot cone, casts shadows. Default: “intensity”.
Value	mixed	No	The one new property value. Color accepts a hex color or text variable; Casts Shadows accepts true/false; the other properties accept numeric expressions. Shown when Property has a selection.
Seconds	number	Yes	0 applies immediately. A positive duration glides Color, Radius, Intensity, or Flicker to the new value. Default: 0. Shown when Property is one of color, radius, intensity, flicker.
Ease	enum	Yes	Choose one of the listed options. Choices: linear, easeIn, easeOut, easeInOut. Default: “easeInOut”. Shown when Property is one of color, radius, intensity, flicker.

Control Book

Opens a Book resource as an accessible full-screen page-turning dialog. Drag a corner, use the on-screen arrows, press Left/Right, or use the Flip Page actions; Home returns to the beginning, End jumps to the end of a free-turning book, Escape or ✕ closes it, and Read again appears on the final page. In branching-story navigation, a labeled choice gates forward turns, End is unavailable, and Previous retraces the reader’s visited path. Page text substitutes {expressions} and pages with a “Show only if” condition are skipped while hidden.

Reference key: showBook.

Editor category: Scene Management > Messages, Dialogue, and Books.

Example: When the player presses G on the title screen, show the “fieldGuide” book.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: open, close, next page, previous page, turn to page. Default: “open”.
Book	thing:book	No	Choose a book resource. Shown when Operation is open.
Page	number	Yes	For Open, blank or 0 starts at the cover. Turn to page uses 1 for the first page. Default: 0. Shown when Operation is one of open, turn to page.

Control Dialogue

Starts a Dialogue resource or ends the active conversation.

Reference key: startDialogue.

Editor category: Scene Management > Messages, Dialogue, and Books.

Example: An NPC’s interact event starts its conversation; an interruption uses End.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: start, end. Default: “start”.
Dialogue	thing:dialogue	No	Choose a dialogue resource. Shown when Operation is start.
Start Node	text	Yes	Blank starts at the dialogue’s own start node. Shown when Operation is start.

Control Light

Turns one 2D light on, off, or toggles it without changing any of its visual properties. Needs the scene’s Lighting enabled.

Reference key: setLightEnabled.

Editor category: Scene Management > Weather and Lighting.

Example: On Custom Event [power-out]: Control Light “ceiling1” off.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Light	text	Yes	A scene light by name. Blank = this object’s own light; one is created if the object never had one.
Operation	enum	No	Choose one of the listed options. Choices: on, off, toggle. Default: “on”.

Control Menu

Opens one navigable UI menu or closes the named or top menu without changing its world-pause state. Use Hide All Menus to clear the complete focus stack.

Reference key: controlMenu.

Editor category: Scene Management > Menus.

Example: Open ShopList, then hide that named menu or the current top menu from Cancel.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: show, hide. Default: “show”.
Menu Element	thing:object	Yes	Choose a screen object resource. Shown when Operation is one of show, hide.

Display Message

Shows one modal text message after substituting live expressions; the player dismisses it to continue.

Reference key: showMessage.

Editor category: Scene Management > Messages, Dialogue, and Books.

Example: Display “Coins found: {$coins}.” after opening the chest.

Parameter	Type	Optional	Details
Text	text	No	Text value; some actions also accept $global names.

Get Asset Preparation Status

Returns the token, state, ready flag, progress from 0 to 1, completed and total items, and any error.

Reference key: getAssetPreparationStatus.

Editor category: Scene Management > Asset Loading.

Parameter	Type	Optional	Details
Preparation token	text	No	Text value; some actions also accept $global names.

Results

Field	Type	Description
token	text
state	text
ready	boolean
progress	number
completed	number
total	number
error	text

Go to Scene

Goes to one selected scene, optionally fading or crossfading and placing the traveler at a named arrival Object. Use Next Scene, Previous Scene, or Restart Scene for relative navigation.

Reference key: goToScene.

Editor category: Scene Management > Scene Flow.

Example: When the player touches a door, go to Overworld with a 0.4s fade, spawning at the FromVillage marker.

Parameter	Type	Optional	Details
Scene	thing:scene	No	Scene resource name.
Transition	enum	Yes	Cut switches at once. Fade goes to black and back. Crossfade keeps the last frame of this scene on screen and dissolves it into the new scene. Choices: cut, fade, crossfade. Default: “cut”.
Transition Seconds	number	Yes	Fade: the length of each half (to black, then back). Crossfade: the length of the dissolve. Default: 0.4.
Spawn At Object	thing:object	Yes	An object placed in the target scene (a door/marker). The TRAVELER arrives at the first marker instance (one spawns if the scene has none). When a door-like sensor runs this from a collision, the traveler is whatever touched it; otherwise it is the acting object.

Hide All Menus

Closes every open menu at once and clears the menu focus stack. Use it for cutscenes, scene hand-offs, and other global UI shutdown.

Reference key: hideAllMenus.

Editor category: Scene Management > Menus.

Example: Before a boss cutscene, hide all menus.

Next Scene

Moves to the next scene in project order. Nothing changes when the current scene is already last.

Reference key: nextScene.

Editor category: Scene Management > Scene Flow.

Example: After the last goal is collected, use Next Scene to advance the campaign.

Play Cutscene

Plays a Cutscene resource. Exact Scene placements bind automatically; a dynamic actor track can bind its named role to this action’s target. Gameplay can hold while the director runs and Cutscene Ended fires after final state and cleanup.

Reference key: playCutscene.

Editor category: Scene Management > Scene Flow.

Example: On Game Start, Play Cutscene [Intro]; optionally bind Self as role “hero”.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Cutscene	thing:cutscene	No	Choose a cutscene resource.
Bind Self As Role	text	Yes	Optional runtime role declared by an actor track. The action target becomes that role for this playback.

Popup Text

Floating text that rises and fades - damage numbers, “+10 gold”, “LEVEL UP!”. Anchors above this instance unless X/Y is given. (3D projects approximate the anchor.)

Reference key: popupText.

Editor category: Scene Management > Messages, Dialogue, and Books.

Example: On collision with Coin: Popup Text “+{data(’Items’,’Coin’,’value’)}” then Destroy Other.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Text	text	No	Supports {expressions}: “{$battleDmg}!” shows the live value. Default: “+1”.
Color	color	Yes	Text value; some actions also accept $global names. Default: “#ffffff”.
Size	number	Yes	Number value; decimals are allowed. Default: 0.5625.
Font	thing:font	Yes	Optional project Font resource. Blank uses the runtime feedback font.
Rise	number	Yes	How far it floats up (meters). Default: 1.125.
Seconds	number	Yes	Number value; decimals are allowed. Default: 0.8.
Position Relative To	enum	Yes	World uses absolute scene coordinates. Object uses local offsets from the acting Object. Coordinate uses local offsets from a named Coordinate. Bounding Box uses local offsets from a selected Transform bounding-box anchor. Choices: world, object, coordinate, boundingBox. Default: “object”.
Coordinate	text	Yes	A named Coordinate on the acting Object. Used only when Position Relative To is Coordinate.
Bounding Box Anchor	enum	Yes	A point on the acting Object’s Transform bounding box. Used only when Position Relative To is Bounding Box. Choices: center, top, bottom, left, right, topLeft, topRight, bottomLeft, bottomRight. Default: “center”.
X	number	Yes	Blank = just above this instance.
Y	number	Yes	Expression or literal value.

Prepare Assets

Prepares Scene images and sounds without starting its gameplay. An optional loading group name or ID selects a group from Game Settings instead. Textures also prepares ordinary image uploads; shader and Scene construction readiness remain separate. The result token identifies the request. Waiting pauses this action chain only.

Reference key: prepareAssets.

Editor category: Scene Management > Asset Loading.

Example: On the loading screen, prepare the Mission assets, wait, then check the result before enabling Play.

Parameter	Type	Optional	Details
Scene	thing:scene	No	Scene resource name.
Loading group (optional)	text	No	Text value; some actions also accept $global names. Default: “”.
Preparation	enum	No	Choose one of the listed options. Choices: decoded, textures. Default: “textures”.
Keep until released	boolean	No	On or off. Default: true.
Wait for completion	boolean	No	On or off. Default: false.

Results

Field	Type	Description
token	text
state	text
ready	boolean
progress	number
completed	number
total	number
error	text

Previous Scene

Moves to the previous scene in project order. Nothing changes when the current scene is already first.

Reference key: previousScene.

Editor category: Scene Management > Scene Flow.

Example: A back door or menu return can use Previous Scene.

Release Prepared Assets

Lets assets no longer used by any Scene or request enter the idle cache. Safe to call repeatedly.

Reference key: releasePreparedAssets.

Editor category: Scene Management > Asset Loading.

Parameter	Type	Optional	Details
Preparation token	text	No	Text value; some actions also accept $global names.

Restart Scene

Restarts the current scene without restarting the complete game run.

Reference key: restartScene.

Editor category: Scene Management > Scene Flow.

Example: When the player loses a life, use Restart Scene to retry the current level.

Set Background Sliding Offset

Jumps the live repeated Background to an exact offset without changing its speed.

Reference key: setBackgroundSlidingOffset.

Editor category: Scene Management > Backgrounds.

Example: Set both offsets to 0 when a new wave begins to restart the backdrop alignment.

Parameter	Type	Optional	Details
Background	thing:background	Yes	A Background mounted in the current Scene. Blank changes every mounted Background.
X Offset	number	Yes	Horizontal offset in pixels. Positive moves right; blank preserves the current X offset.
Y Offset	number	Yes	Vertical offset in pixels. Positive moves up; blank preserves the current Y offset.

Set Background Sliding Paused

Pauses or resumes live Background sliding while preserving its current speed and offset.

Reference key: setBackgroundSlidingPaused.

Editor category: Scene Management > Backgrounds.

Example: Pause sliding during a boss introduction, then set Paused to Off when play resumes.

Parameter	Type	Optional	Details
Background	thing:background	Yes	A Background mounted in the current Scene. Blank changes every mounted Background.
Paused	boolean	No	On or off. Default: true.

Set Background Sliding Speed

Changes the live sliding velocity. An axis moves only when Resize Behavior repeats it with Tile Both, Tile Horizontally, or Tile Vertically.

Reference key: setBackgroundSlidingSpeed.

Editor category: Scene Management > Backgrounds.

Example: On Scene Start, set Y Speed to 120 for a downward-moving vertical-shooter backdrop.

Parameter	Type	Optional	Details
Background	thing:background	Yes	A Background mounted in the current Scene. Blank changes every mounted Background.
X Speed	number	Yes	Horizontal pixels per second. Positive moves right; blank preserves the current X speed.
Y Speed	number	Yes	Vertical pixels per second. Positive moves up; blank preserves the current Y speed.

Set Cursor

Sets cursor for the target or game.

Reference key: setCursor.

Editor category: Scene Management > UI.

Example: In Game Start, hide the cursor for a keyboard-only game.

Parameter	Type	Optional	Details
Visible	boolean	Yes	On or off. Default: true.

Set Language

Switches the live language: t() lookups and story text (dialogue lines, book pages, UI labels) re-read the Strings table column with this code from the next line on. Reports a typed write result and retains failed writes for retry. Persists as “opt_locale” so an Options screen’s Game Start restore re-applies it; blank returns to the default language.

Reference key: setLanguage.

Editor category: Scene Management > Language.

Example: An options row runs Set Language “fr” — the next spoken line and every reopened book read French.

Parameter	Type	Optional	Details
Language code	text	No	Text value; some actions also accept $global names.

Results

Field	Type	Description
ok	boolean
status	text
key	text
code	text
message	text

Set Menu Pause State

Changes only whether the named or top open UI menu pauses the world.

Reference key: setMenuPauseState.

Editor category: Scene Management > Menus.

Example: Open a menu, then turn on its world pause without rebuilding the menu stack.

Parameter	Type	Optional	Details
Menu Element	thing:object	Yes	Blank changes the top menu.
Pause the World	boolean	No	On or off. Default: true.

Set UI Binding

Assigns one retained expression binding to one UI element so the UI refreshes from that value automatically. Use Set UI Text for a one-time text assignment.

Reference key: setBinding.

Editor category: Scene Management > UI.

Example: Bind a UI label to score so it updates automatically.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Element	thing:object	Yes	Blank uses the screen-space Object selected by Applies To.
Binding	text	No	Text value; some actions also accept $global names.

Set UI Element Active

Activates or deactivates one UI Object. Inactive UI does not render, update Logic, or receive pointer input.

Reference key: setElementActive.

Editor category: Scene Management > UI.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Element	thing:object	Yes	Blank uses the screen-space Object selected by Applies To.
Active	boolean	No	On or off. Default: true.

Set UI Element Visibility

Shows or hides one UI Object. Use Set UI Group Visibility when several elements share one Group value.

Reference key: showElement.

Editor category: Scene Management > UI.

Example: Show or hide one UI element, or target a UI Group to change the whole group together.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Element	thing:object	Yes	Blank uses the screen-space Object selected by Applies To.
Visible	boolean	No	On or off. Default: true.

Set UI Group Visibility

Shows or hides every UI Object with the same non-empty Group value.

Reference key: showHudGroup.

Editor category: Scene Management > UI.

Example: Hide UI Group “gameplay-core” while Pause is open, then show it on Resume.

Parameter	Type	Optional	Details
UI Group	text	No	The exact Group value shared by the UI Objects.
Visible	boolean	No	On or off. Default: true.

Set UI Text

Sets one UI element to a literal or expression-substituted text value. Automatic expression binding is the separate Set UI Binding Atomic.

Reference key: setText.

Editor category: Scene Management > UI.

Example: After scoring, set a UI label text to the new value.

Choose the target instance with the Action’s Applies To field.

Parameter	Type	Optional	Details
Element	thing:object	Yes	Blank uses the screen-space Object selected by Applies To.
Text	text	No	Text value; some actions also accept $global names.

Unlock Gallery Image

Marks one Gallery table row as unlocked — on the device, forever. The row’s “unlocked” cell flips true for the current session. A successful write restores it on later runs while browser storage is retained, so a CG gallery screen can dim what the player has not yet found. “$menuRow” and other $globals resolve.

Reference key: unlockGalleryImage.

Editor category: Scene Management > Gallery.

Example: When the true ending plays, Unlock Gallery Image “Sunrise” so the player can pick it in the gallery and view it.

Parameter	Type	Optional	Details
Gallery Entry	text	No	Text value; some actions also accept $global names.

Results

Field	Type	Description
ok	boolean
status	text
key	text
code	text
message	text

View Image (Fullscreen)

Shows a sprite full-screen over everything — click or Escape closes it. A bare name stays literal and “$global” dereferences, so a gallery pick can stash its cell in a global first.

Reference key: viewImage.

Editor category: Scene Management > Gallery.

Example: A gallery menu’s pick: Set Global galleryPick = data(‘Gallery’, $menuRow, ‘image’), then View Image “$galleryPick”.

Parameter	Type	Optional	Details
Sprite	text	No	Text value; some actions also accept $global names.