Time Actions

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

Advance Time

Rolls the Day/Night clock forward (negatives rewind), wrapping through midnight into the next $time_day.

Reference key: advanceTime.

Editor category: Time > World Time.

Example: A campfire rest: Advance Time 8 hours, then heal the party.

Parameter	Type	Optional	Details
Hours	number	No	Expression or literal value. Default: 1.
Minutes	number	Yes	Expression or literal value. Default: 0.

Control Pause Overlay

Shows or hides the viewport-fixed pause overlay without changing simulation pause. Showing is accepted only while the game is already paused.

Reference key: controlPauseOverlay.

Editor category: Time > Game Speed.

Example: Pause the game, then show the overlay. Use the Pause Overlay Lifecycle Logic for the complete workflow.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: show, hide. Default: “show”.
Menu spec (JSON)	text	Yes	Text value; some actions also accept $global names. Shown when Operation is show.

Delete Save

Deletes one named save slot. Saving and loading slots are separate actions.

Reference key: deleteSave.

Editor category: Time > Save Games.

Example: A save screen’s Clear Slot choice deletes “$menuSlot”.

Parameter	Type	Optional	Details
Slot	text	No	The slot to delete, or “$menuSlot” for the pause-menu choice. Default: “default”.

End Game

Ends the current game, fires Game End once, and releases the running scene. Restarting is a separate action.

Reference key: endGame.

Editor category: Time > Game Session.

Example: After the final victory sequence, end the game.

Ignore Time Flow

Marks the acting instance as exempt from Set Time Flow: while the world runs slow or fast it keeps real-time pace, and Rewind Time leaves it in place. The bullet-time player, aim cursors, or a narrator stay crisp while everything else crawls.

Reference key: setObjectTimeImmune.

Editor category: Time > Time Flow.

Example: On Create (Player): Ignore Time Flow [ignore], then Set Time Flow [0.2] makes enemies crawl while the player moves freely.

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

Parameter	Type	Optional	Details
Operation	enum	No	Ignore exempts this instance from the world pace; follow returns it to the shared clock. Choices: ignore, follow. Default: “ignore”.

Load Game

Validates and loads one named save slot. The Action result reports pending or failed; completion uses Custom Events load:succeeded and load:failed. Invalid or unsupported saves are refused before replacing the current game, with a visible retry message.

Reference key: loadGame.

Editor category: Time > Save Games.

Example: From a Continue button, Load Game from slot “main”.

Parameter	Type	Optional	Details
Slot	text	No	The slot to read, or “$menuSlot” for the pause-menu choice. Default: “default”.

Results

Field	Type	Description
ok	boolean	True only after restoration completes. A normal Load Game request returns pending first; use load:succeeded for completion.
status	text	pending, loaded, or failed. Admission queues restoration rather than completing it immediately; completion dispatches load:succeeded or load:failed.
slot	text	Resolved slot name used for the operation. The Action trims surrounding whitespace from resolved Text before lookup; empty or missing text resolves to default. Slot names are case-sensitive.
code	text	Machine-readable failure reason, such as missing-save, invalid-json, invalid-state, unsupported-version, incompatible-content, incompatible-scale, superseded, interrupted, or storage-unavailable. Blank on success or while pending.
message	text	Human-readable explanation associated with a failure. Blank when no explanation is supplied. Branch on Status or Error Code rather than matching message wording.

Load Persistent Value

Reads a device-persisted value, or the Default if none is stored yet, and publishes one typed Action result. Use Change Variable or Change Variable (Global scope) only when the value must be retained.

Reference key: loadPersistent.

Editor category: Time > Persistent Values.

Example: On Scene Start, load persistent “highscore” with default [0], then use persistentValueResult.value.

Parameter	Type	Optional	Details
Key	text	No	Text value; some actions also accept $global names.
Default	mixed	Yes	Expression or literal value.

Results

Field	Type	Description
value	mixed

Open Persistent Values File

Opens a file picker for a .mythvalues file and stores its values (filtered by Key Prefix) as persistent values. Then Custom Event values:imported runs with $values_file_count and $values_file_name set, or values:failed / values:canceled.

Reference key: importPersistentValues.

Editor category: Time > Persistent Values.

Example: An OPEN PUZZLE button opens a values file with Key Prefix “shared-puzzle”; on values:imported the game rebuilds its shared-puzzle card.

Parameter	Type	Optional	Details
Key Prefix	text	Yes	Only keys in the file that start with this text are stored; the rest are ignored. Blank accepts every key.

Pause Clock

Freezes or resumes the Day/Night clock without touching gameplay ($time_paused).

Reference key: pauseClock.

Editor category: Time > World Time.

Example: The festival: Pause Clock, run the scene, then Pause Clock “resume”.

Parameter	Type	Optional	Details
Mode	enum	No	Choose one of the listed options. Choices: pause, resume, toggle. Default: “pause”.

Record Time History

Turns the time recorder on or off. While on, a 2D Scene keeps a rolling history of every instance so Rewind Time can play the world backwards; off discards the history. Recording pauses inside 3D Scenes and multiplayer sessions.

Reference key: setTimeRecording.

Editor category: Time > Time Flow.

Example: On Game Start: Record Time History [on] keeping [8] seconds, so the rewind power is always ready.

Parameter	Type	Optional	Details
Operation	enum	No	On keeps history from this moment; off stops recording and discards what was kept. Choices: on, off. Default: “on”.
Keep Seconds	number	Yes	How many seconds of the past stay available to Rewind Time (1–30). Longer windows keep more memory. Default: 10. Shown when Operation is on.

Restart Game

Restarts the complete game from its configured start scene. Ending and releasing the run is a separate action.

Reference key: restartGame.

Editor category: Time > Game Session.

Example: A retry or pause-menu choice restarts the game.

Rewind Time

Plays the recorded world backwards, Life is Strange style. Start scrubs positions, motion, and poses back through the history (destroyed instances return, newborns vanish); stop resumes play from that past moment and discards the rewound future; jump leaps back instantly. Ignore Time Flow instances hold their place, input stays live so a release can stop it, and $rewind_active / $rewind_seconds report state. Needs Record Time History; 2D Scenes only.

Reference key: rewindTime.

Editor category: Time > Time Flow.

Example: On Command Held [Rewind]: Rewind Time [start] at Speed [2]; On Command Released: Rewind Time [stop].

Parameter	Type	Optional	Details
Operation	enum	No	Start scrubs backwards (optionally auto-stopping after Seconds of the past), stop resumes play at the reached moment, jump snaps back a number of seconds instantly. Choices: start, stop, jump. Default: “start”.
Speed	number	Yes	How fast the past scrubs by: 1 matches real pace, 2 doubles it. Clamped 0.1–8. Default: 2. Shown when Operation is start.
Seconds	number	Yes	For jump: snap this many recorded seconds into the past instantly. For start: 0 scrubs until stopped; above 0 the scrub auto-stops after consuming this much of the past — the visible watch-it-undo beat. Default: 2. Shown when Operation is one of start, jump.

Save Game

Writes the current game state to one named slot. The Action result reports saved, pending, or failed; Saved is true only after storage succeeds. Platformer callbacks defer saves until the complete simulation step. Custom Events save:succeeded and save:failed report completion; failures also offer a visible retry.

Reference key: saveGame.

Editor category: Time > Save Games.

Example: At a checkpoint, Save Game to slot “auto”.

Parameter	Type	Optional	Details
Slot	text	No	The slot to write. “$menuSlot” uses the pause-menu choice; “auto” is the autosave slot. Default: “default”.

Results

Field	Type	Description
ok	boolean	True only after the slot write succeeds. False for pending or failed requests; invoking Save Game alone does not establish saved progress.
status	text	saved, pending, or failed. pending means the simulation-boundary write has been queued; completion dispatches save:succeeded or save:failed.
slot	text	Resolved slot name used for the operation. The Action trims surrounding whitespace from resolved Text before lookup; empty or missing text resolves to default. Slot names are case-sensitive.
code	text	Machine-readable failure reason, such as quota-exceeded, storage-unavailable, snapshot-failed, restore-in-progress, or restore-incomplete. Blank on success or while pending.
message	text	Human-readable explanation associated with a failure. Blank when no explanation is supplied. Branch on Status or Error Code rather than matching message wording.

Save Game Copy With Values

Downloads a copy of this game page with the chosen persistent values inside it. Whoever opens the copy gets those values stored once on their device before the game starts, so the game can show what the sender made. Needs a Single HTML export. The Action result reports ok and count.

Reference key: sharePageCopy.

Editor category: Time > Persistent Values.

Example: A SHARE AS WEB GAME button saves keys starting with “my-puzzle-1”, baked as “shared-puzzle”, into “my-puzzle.html”.

Parameter	Type	Optional	Details
File Name	text	No	The download name; the .html extension is added. A lone “$global” reads a text variable. Default: “my-game”.
Key Prefix	text	Yes	Only persistent keys that start with this text are baked in. Blank bakes every persistent value of this game.
Save As Prefix	text	Yes	Replaces Key Prefix in the copy, so the values land under other keys on the other device.

Results

Field	Type	Description
ok	boolean
count	number
code	text
message	text

Save Persistent Value

Writes one device-persistent value under one title-scoped key. Quote text values when saving.

Reference key: savePersistent.

Editor category: Time > Persistent Values.

Example: Save Persistent Value key “highscore” from $score.

Parameter	Type	Optional	Details
Key	text	No	Text value; some actions also accept $global names.
Value	number	No	Expression or literal value.

Results

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

Save Persistent Values To File

Downloads a small .mythvalues file holding the chosen persistent values. Another copy of this game opens it with Open Persistent Values File. The Action result reports ok and count.

Reference key: exportPersistentValues.

Editor category: Time > Persistent Values.

Example: A SHARE button saves keys starting with “my-puzzle-1” to a file named “my-puzzle”, saved as prefix “shared-puzzle”.

Parameter	Type	Optional	Details
File Name	text	No	The download name; the .mythvalues extension is added. A lone “$global” reads a text variable. Default: “my-values”.
Key Prefix	text	Yes	Only persistent keys that start with this text go into the file. Blank writes every persistent value of this game.
Save As Prefix	text	Yes	Replaces Key Prefix inside the file, so the values land under other keys when the file is opened (my-puzzle-1 saved as shared-puzzle).

Results

Field	Type	Description
ok	boolean
count	number
code	text
message	text

Set Alarm

Starts an alarm that fires after the given number of seconds.

Reference key: setAlarm.

Editor category: Time > Timers.

Example: After shooting, set Alarm 0 for a cooldown.

Parameter	Type	Optional	Details
Alarm (0-11)	enum	No	Choose one of the listed options. Choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11. Default: “0”.
Seconds	number	No	Delay before the alarm fires. Accepts a number, variable, global, or expression. Delay uses simulation seconds, not milliseconds.

Set Clock Speed

Scales how fast game time flows against the Day/Night day length ($time_speed).

Reference key: setClockSpeed.

Editor category: Time > World Time.

Example: Indoors: Set Clock Speed 0.25 so the day lingers while players shop.

Parameter	Type	Optional	Details
Multiplier	number	No	1 = the attached Atmosphere’s day length; 2 doubles time; 0 stands still. Default: 1.

Set Full Screen

Shows the game full screen, or back in its window. Browsers allow full screen only just after the player presses a key or clicks, so run it from a Command Pressed or Clicked Event. If the player or the browser refuses, the game goes on in its window (a note in the Console says so once). The project’s Window Mode still decides how a published game opens.

Reference key: setFullScreen.

Editor category: Time > Game Session.

Example: Command Pressed [Full Screen] (F): Set Full Screen [Toggle].

Parameter	Type	Optional	Details
Full Screen	enum	No	Toggle switches between full screen and the window; On and Off set it. Choices: toggle, on, off. Default: “toggle”.

Set Game Paused

Pauses or resumes the whole simulation. Pausing holds steps, alarms, physics, and canvas input (except the Commands of Input Contexts set to Works While Paused, and mouse events on screen-space Objects, so a game can drive its own pause panel) and fires “gamePaused” / “gameResumed”; a live multiplayer session ignores local pause. Gameplay pace is a separate Set Game Speed Atomic.

Reference key: pauseGame.

Editor category: Time > Game Speed.

Example: Pause before showing a pause menu; use Set Game Speed separately for a gentler timing mode.

Parameter	Type	Optional	Details
Paused (1 pause / 0 resume)	number	No	Expression or literal value. Default: 1.

Set Game Speed

Changes the pace of steps, physics, alarms, waits, cooldowns, and gameplay animation while menus, dialogue, and camera effects stay responsive. The setting survives scene changes and resets with Restart Game.

Reference key: setGameSpeed.

Editor category: Time > Game Speed.

Example: On an Assist-menu choice, Set Game Speed to 0.8 so timing windows are easier without changing the level.

Parameter	Type	Optional	Details
Speed	number	No	Simulation multiplier from 0.25 to 2. Use 0.8 for an accessibility-friendly 80% pace; 1 restores normal speed. Default: 1.

Set Object Time Factor

Gives one instance a personal pace on top of the world Time Flow — its movement, animations, alarms, and scheduled events run at this multiple. A hasted hero at 2, a magically slowed guardian at 0.3.

Reference key: setObjectTimeFactor.

Editor category: Time > Time Flow.

Example: On Custom Event [freezeRay]: Set Object Time Factor [0.25] on the touched enemy so it crawls while the world runs normally.

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

Parameter	Type	Optional	Details
Factor	number	No	This instance’s personal pace: 0.5 runs half speed, 2 double speed, 1 returns to normal. Clamped 0.05–4. Default: 1.

Set Time Flow

Slow motion and fast forward: scales the whole simulation — movement, physics, alarms, animations, scheduled events — while menus, dialogue, and the camera stay responsive. Objects marked Ignore Time Flow keep real-time pace. Composes with Set Game Speed (accessibility) and resets with Restart Game.

Reference key: setTimeFlow.

Editor category: Time > Time Flow.

Example: On Collision with PowerCore: Set Time Flow to [0.2] easing across [0.15] seconds with Hold [1.5] — a bullet-time burst that releases itself.

Parameter	Type	Optional	Details
Speed	number	No	The world pace: 0.2 is dramatic slow motion, 1 is normal, 2 is double speed. Clamped 0.05–4. Default: 1.
Ease Seconds	number	Yes	0 switches instantly; otherwise the pace glides there across this many real seconds. Default: 0.
Hold Seconds	number	Yes	0 keeps the pace once reached; above 0 it holds that many real seconds, then glides back to normal on its own. Default: 0.

Set World Time

Sets the Day/Night clock to one exact hour and minute. Advancing time, changing clock speed, and pausing the clock are separate Atomic actions.

Reference key: setTimeOfDay.

Editor category: Time > World Time.

Example: Set time to 6:00 after sleeping; use the focused clock actions for advancing, speed, or pause.

Parameter	Type	Optional	Details
Hour (0-23)	number	No	Expression or literal value. Default: 8.
Minute	number	Yes	Expression or literal value. Default: 0.

Start Cooldown

Starts a named cooldown on the target instance.

Reference key: startCooldown.

Editor category: Time > Timers.

Example: After firing or taking damage, start a named cooldown for the target instance.

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

Parameter	Type	Optional	Details
Cooldown Key	text	No	Text value; some actions also accept $global names. Default: “cooldown”.
Seconds	number	No	Cooldown duration. Accepts a number, variable, global, or expression. Default: 0.2.

Start Recurring Timer

Starts or restarts one saveable named recurring timer. Stopping one timer or every timer uses separate actions.

Reference key: startRecurringTimer.

Editor category: Time > Timers.

Example: Start “rent” every 30 seconds with an optional shorter first delay.

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

Parameter	Type	Optional	Details
Timer Name	text	No	A name chosen by the author. Starting the same name again restarts it with the new timing. Default: “timer”.
Repeat Every (s)	number	No	Positive simulation seconds between firings. It pauses and scales with gameplay time. Default: 1.
First Delay (s)	number	Yes	Optional delay before the first firing. Blank uses Repeat Every. Starting the same name again on this target restarts its schedule and firing count.
Ring Once	boolean	Yes	Fire a single time after First Delay (or Repeat Every), then stop: a named one-shot timer. Default: false.

Stop All Recurring Timers

Stops every named recurring timer on the target instance. Numbered Alarms are unchanged.

Reference key: stopAllRecurringTimers.

Editor category: Time > Timers.

Example: When a simulation controller shuts down, stop all of its recurring timers in one action.

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

Stop Recurring Timer

Stops one named recurring timer. Use Stop All Recurring Timers to clear the target instance’s complete timer set.

Reference key: stopRecurringTimer.

Editor category: Time > Timers.

Example: When the simulation closes for the night, stop the “customers” timer.

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

Parameter	Type	Optional	Details
Timer Name	text	No	The exact non-empty recurring timer name to stop.

Wait

Pauses the remaining actions in this event for a short time.

Reference key: wait.

Editor category: Time > Timers.

Example: Between action-list steps, wait for 0.5 seconds.

Parameter	Type	Optional	Details
Seconds	number	No	Number value; decimals are allowed.