Audio Actions

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

Change Sound Effect Property

Changes exactly one property in the Master, Music, or Sound Effects effect rack. Enabled state is independent, so disabling an effect preserves its authored knobs for later re-enabling.

Reference key: setAudioEffectProperty.

Editor category: Audio > Sound and Music.

Example: When a pause menu opens, enable the Music Filter and change its Cutoff to 700 over 0.3 seconds; disable the Filter when the menu closes.

Parameter	Type	Optional	Details
Bus	enum	Yes	Master = everything; Music / Sound Effects = just that bus. Choices: master, music, sfx. Default: “master”.
Property	enum	No	The one effect-rack property to change. Filter Type accepts lowpass, highpass, or bandpass; each effect has its own Enabled property. Choices: reverb amount, reverb size, reverb enabled, equalizer bass, equalizer middle, equalizer treble, equalizer enabled, filter type, filter cutoff, filter resonance, filter enabled, echo amount, echo delay, echo repeats, echo enabled, distortion drive, distortion enabled, compressor strength, compressor enabled. Default: “reverb amount”.
Value	mixed	No	The new value. Enabled properties use true/false; amounts, drive, strength, and repeats use 0–1; EQ bands use dB; Filter Resonance uses 0.1–12; Filter Type uses lowpass, highpass, or bandpass. Default: 0.3. Shown when Property has a selection.
Seconds	number	Yes	Glides a continuous property over this many seconds. Enabled, Filter Type, and Reverb Size changes apply immediately. Default: 0.

Control Mic Recording

Records microphone input into a named Sound. When recording is ready, Mic Recording Ready fires and $mic_rec_ready becomes 1. Use Play Sound with that name to play the recording through normal bus mixing. $mic_rec is 1 during recording, and $mic_rec_time reports elapsed seconds. Recordings stay in memory for the current play session; this Action does not save them to disk or upload them. If the microphone is off, the Action enables it and requests permission.

Reference key: micRecordStart.

Editor category: Audio > Microphone.

Example: While R is held: Start Mic Recording into “echo”, Max Seconds 5. On Mic Recording Ready: Play Sound “echo” with Set Reverb — the canyon answers in the player’s own voice.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: start, stop. Default: “start”.
Save as sound name	text	No	The recording becomes a playable sound with this name. Using an existing sound’s name swaps in the player’s take for this play session (its volume/bus settings still apply). Default: “recording”. Shown when Operation is start.
Max Seconds	number	Yes	The recording stops itself after this long (1-120). Choosing Stop ends it sooner. Default 30. Default: 30. Shown when Operation is start.

Control Sound

Plays, loops, crossfades, or stops one selected Sound resource. Use Stop All Sounds for global audio shutdown. Volume, spatial playback, listener selection, and sound effects remain separate controls.

Reference key: playSound.

Editor category: Audio > Sound and Music.

Example: Start a looping engine sound, crossfade into a new music track, or stop one named loop.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: play, loop, crossfade music, stop. Default: “play”.
Sound	thing:sound	Yes	Choose a sound resource. Shown when Operation is one of play, loop, crossfade music, stop.
Crossfade Seconds	number	Yes	The overlap while old music fades out and the new looping track fades in. Default: 1. Shown when Operation is crossfade music.

Control Speech

The device reads text aloud with its built-in voices (text-to-speech) — a narrator, talking signs, or reading the screen to players who can’t read yet. It uses the voices installed on the player’s device, so the exact voice varies; ask by name or language and it degrades gracefully. A device with no voices skips the line with a console note instead of breaking the game. Changing scenes stops the voice, so let important lines finish with “Wait until finished”.

Reference key: speakText.

Editor category: Audio > Speech.

Example: On Scene Start: Speak Text “Welcome to the forest!” with Wait on, then Speak Text “Find the three lanterns.” — the second line politely follows the first.

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: speak, pause, resume, stop. Default: “speak”.
Text	text	No	Text to speak. Supports {expressions}: “Coins: {$coins}” speaks the current value. Default: “Hello!”. Shown when Operation is speak.
Replace current speech	boolean	Yes	On = stop whatever is being said and say this now. Off = politely wait in line behind it (up to 12 lines). Default: true. Shown when Operation is speak.
Wait until finished	boolean	Yes	The event pauses at this action until the line has been spoken — the game itself keeps running. Great for narration sequences. (Ignored in lockstep multiplayer so players stay in sync.) Default: false. Shown when Operation is speak.

Play Sound At

Plays spatial audio from an Object or a fixed resolved position.

Reference key: playSoundAt.

Editor category: Audio > Sound and Music.

Parameter	Type	Optional	Details
Sound	thing:sound	No	Choose a sound resource.
Source	enum	No	Choose one of the listed options. Choices: object, position. Default: “object”.
At Object	thing:object	Yes	Blank uses the Object running this Action; otherwise the nearest live instance is used. Shown when Source is object.
Follow It	boolean	Yes	On or off. Default: true. Shown when Source is object.
Position Relative To	enum	Yes	Choose one of the listed options. Choices: world, object, coordinate, boundingBox. Default: “world”. Shown when Source is position.
Coordinate	text	Yes	Text value; some actions also accept $global names. Shown when Position Relative To is coordinate.
Bounding Box Anchor	enum	Yes	Choose one of the listed options. Choices: center, top, bottom, left, right, topLeft, topRight, bottomLeft, bottomRight. Default: “center”. Shown when Position Relative To is boundingBox.
X	number	No	Expression or literal value. Default: 0. Shown when Source is position.
Y	number	No	Expression or literal value. Default: 0. Shown when Source is position.
Z (Height)	number	Yes	3D Scenes only: height in meters (Blender Z). Shown when Source is position.
Heard Up To	number	Yes	Expression or literal value.
Full Volume Within	number	Yes	Expression or literal value.

Set Audio Listener

Selects the listener position for positional sounds. The default listener is the camera. Bind the listener to the player Object when camera lag should not affect the perceived sound position. The listener returns to the camera when the selected Object is gone or the game restarts.

Reference key: setAudioListener.

Editor category: Audio > Sound and Music.

Example: On Create [Hero]: Set Audio Listener to Hero — danger now sounds near when it is near HIM, not the camera.

Parameter	Type	Optional	Details
Listen From	thing:object	Yes	Select the player Object as the listener, or leave blank to use the camera.

Set Mic Loud Threshold

How loud is “loud”: crossing this level fires Loud Sound and turns $mic_loud on. The loud state holds through quarter-second dips (a breath mid-shout never flickers it) and releases with Quiet Again once things calm down.

Reference key: micSetThreshold.

Editor category: Audio > Microphone.

Example: On Game Start: Set Mic Loud Threshold to 35 so only a real shout scares the birds off the fence.

Parameter	Type	Optional	Details
Loud at level (0-100)	number	No	The $mic_level that counts as LOUD. Talking ~40, a shout ~90. Default 25. Default: 25.

Set Mic Sensitivity

Changes only the microphone analysis sensitivity. Loud threshold and smoothing have their own Atomic actions.

Reference key: micSetSensitivity.

Editor category: Audio > Microphone.

Example: Set Mic Sensitivity to 160 for a quiet laptop microphone.

Parameter	Type	Optional	Details
Sensitivity (0-400)	number	No	100 is the calibrated input level; lower values reduce and higher values amplify the analyzed signal. Default: 100.

Set Mic Smoothing

How steady the $mic_level needle is. A shout always registers immediately — smoothing mostly shapes how gracefully the level falls afterward, which is what makes meters and singing bars feel good.

Reference key: micSetSmoothing.

Editor category: Audio > Microphone.

Example: For a karaoke bar: Set Mic Smoothing to 80 so the bar glides instead of jittering.

Parameter	Type	Optional	Details
Smoothing (%)	number	No	0 = twitchy and instant, 100 = a calm needle that falls gently. Default 50. Default: 50.

Set Microphone Enabled

Turns microphone analysis on or off. Sensitivity, loud threshold, smoothing, and recording transport are separate Atomic actions.

Reference key: micEnable.

Editor category: Audio > Microphone.

Example: Enable the microphone when a voice minigame starts, then disable it when the minigame ends.

Parameter	Type	Optional	Details
Enabled	boolean	No	On or off. Default: true.

Set Speech Language

Changes only the narrator language fallback used by later Speak Text actions.

Reference key: setSpeechLanguage.

Editor category: Audio > Speech.

Example: When the player chooses Spanish: Set Speech Language to “es”.

Parameter	Type	Optional	Details
Language	text	No	A language code such as en, es, or fr. It selects the best installed language match when the preferred voice is unavailable.

Set Speech Pitch

Changes only the narrator pitch used by later Speak Text actions.

Reference key: setSpeechPitch.

Editor category: Audio > Speech.

Example: Set Speech Pitch to 0.75 for a lower voice.

Parameter	Type	Optional	Details
Pitch (0-2)	number	No	The narrator pitch. 1 is the device voice’s normal pitch. Default: 1.

Set Speech Speed

Changes only the narrator speaking speed used by later Speak Text actions.

Reference key: setSpeechRate.

Editor category: Audio > Speech.

Example: Set Speech Speed to 0.9 for a calmer storyteller.

Parameter	Type	Optional	Details
Speed (0.25-4)	number	No	The narrator speaking-speed multiplier. 1 is normal speed. Default: 1.

Set Speech Voice

Chooses the preferred device voice used by every later Speak Text action. Language, speed, pitch, and volume are independent narrator settings with their own Atomic actions.

Reference key: setSpeechVoice.

Editor category: Audio > Speech.

Example: On Game Start: Set Speech Voice to “Zira” so every spoken line uses that installed voice when available.

Parameter	Type	Optional	Details
Voice	text	Yes	Part of a voice name to prefer for every later spoken line. Blank keeps the current narrator voice.

Set Speech Volume

Changes only the narrator volume used by later Speak Text actions.

Reference key: setSpeechVolume.

Editor category: Audio > Speech.

Example: Set Speech Volume to 0.5 before quiet background narration.

Parameter	Type	Optional	Details
Volume (0-1)	number	No	The narrator volume before the device’s own output volume is applied. Default: 1.

Set Voice Sensitivity

Scales how forgiving every Voice Word’s accept threshold is. The default 100 is auto-calibrated from how much the taught takes differ from each other — raise it if real players are missed, lower it if random speech triggers words.

Reference key: voiceSetSensitivity.

Editor category: Audio > Voice Commands.

Example: In the options menu: Set Voice Sensitivity to {$voiceSlider}.

Parameter	Type	Optional	Details
Sensitivity (25-400)	number	No	100 is calibrated from the taught takes themselves; higher accepts looser matches (noisy rooms, young voices), lower demands closer ones (fewer false accepts). Default: 100.

Set Volume

Sets volume for the target or game.

Reference key: setMasterVolume.

Editor category: Audio > Sound and Music.

Example: Choose Master, Music, or Sound Effects and set that bus volume from an options slider.

Parameter	Type	Optional	Details
Audio Bus	enum	Yes	Master changes everything; Music and Sound Effects change only that bus. Choices: master, music, sfx. Default: “master”.
Volume (0-1)	number	No	A number or expression — $optMusic / 100 lets an options menu drive it. Default: 1.

Start Voice Listening

Starts recognizing the game’s taught Voice Words from the player’s microphone (auto-enables the microphone, permission ask included). When a word is confidently heard, Voice Command Heard fires with $voice_last / $voice_score; unclear speech fires Voice Not Recognized. Recognition happens entirely on this machine: audio is reduced to voice features and forgotten — nothing is recorded and nothing leaves the device. Listening pauses itself while Speak Text is talking so the game never hears its own narrator.

Reference key: voiceListen.

Editor category: Audio > Voice Commands.

Example: On Game Start: Start Voice Listening in wake-word mode. On Wake Word Heard: chime. On Voice Command Heard + If Voice Heard [map]: open the map.

Parameter	Type	Optional	Details
Mode	enum	No	Commands: every taught Voice Word is matched whenever the player speaks. Wake word: only the wake word is listened for; hearing it opens a few-second command window ($voice_wake is 1) for one command — the Ok-Google pattern. Choices: commands, wake word. Default: “commands”.

Stop All Sounds

Stops every currently playing Sound at once. It does not change Master, Music, or Sound Effects volume and does not disable future playback.

Reference key: stopAllSounds.

Editor category: Audio > Sound and Music.

Example: Before restarting the game or entering a silent title scene, stop all sounds.

Teach Voice Word

Records spoken takes as recognition templates for a word. $voice_teaching and $voice_teach_left report progress; Voice Word Taught fires when teaching completes. Recognition matches sound and does not depend on spelling or language. Use this to teach a player-chosen word or adapt recognition to a voice that differs from the authored takes. Listening starts automatically if it is off.

Reference key: voiceTeach.

Editor category: Audio > Voice Commands.

Example: On dialogue [Teach familiar name], teach Voice Word “{$petName}” with 3 takes. On Voice Word Taught, speak “Name learned.”

Parameter	Type	Optional	Details
Word	text	No	The word to (re)teach. A word authored in Game Settings is re-taught in the player’s own voice; a new name becomes a new word for this play session. Default: “open”.
Takes	number	Yes	How many times the player says it (1-5, default 3 — more takes, steadier recognition). Default: 3.