Animation and Effects Actions

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

Add Camera Shader

Adds a shader to the end of the camera effect stack, which runs up to 4 full-screen shaders in order (an ASCII shader always runs last). Adding a shader already in the stack updates its Applies To and Strength instead. Set Camera Shader still replaces the whole stack.

Reference key: addCameraShader.

Editor category: Animation and Effects > Shaders.

Example: On Scene Start, add a Vignette after the CRT shader the Scene already uses.

Parameter	Type	Optional	Details
Shader	thing:shader	No	Choose a shader resource.
Applies To	enum	Yes	World shades the game world only; Screen UI (the HUD) stays clear. Screen shades the whole screen, Screen UI included. Choices: world, screen. Default: “world”.
Strength	number	Yes	0 leaves the image unchanged, 1 is the full effect. Default: 1.

Attach To Bone

Pins this instance to a named bone on another instance’s 2D skeletal rig or 3D glTF model. Weapons, particles, hit markers, and props ride the animated bone; the socket releases if its owner is destroyed. A blank bone detaches.

Reference key: attachToBone.

Editor category: Animation and Effects > Rigging.

Example: On Custom Event [equip]: the Sword runs Attach To Bone [Hero] bone [hand.R].

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

Parameter	Type	Optional	Details
Attach To	thing:object	No	The object whose skeleton carries this instance (its first live instance).
Bone	text	No	A bone from the target’s 2D Rig or 3D model skeleton — hand, head, spine (partial names match). Blank detaches.
Offset X	number	Yes	Bone-space offset (meters for 2D rigs, world units for 3D models). Default: 0.
Offset Y	number	Yes	Number value; decimals are allowed. Default: 0.
Offset Z	number	Yes	Number value; decimals are allowed. Default: 0.
Inherit Rotation	boolean	Yes	glTF visuals take the bone’s full rotation (a sword follows the swing); sprite visuals keep billboarding. Default: true.

Burst Particles

Emits a one-shot Particle effect at the Object origin, a named Coordinate, a bounding-box anchor, or an explicit world position.

Reference key: burstParticles.

Editor category: Animation and Effects > Particles.

Example: When a weapon fires, burst sparks at its named Muzzle Coordinate.

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

Parameter	Type	Optional	Details
Particles	thing:particle	No	Choose a particle resource.
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	Optional horizontal offset in the selected position space.
Y	number	Yes	Optional vertical offset in the selected position space.
Count	number	Yes	Whole number value.
Tint	color	Yes	Multiplies this burst’s authored colors. Accepts a Color value or expression. Blank keeps the Particle resource colors.
Opacity	number	Yes	Multiplies this burst’s authored alpha, from 0 to 1. Blank keeps the resource alpha. Values are captured when the burst starts.
Z-index Offset	number	Yes	Optional Object-local layer offset. 0 uses the target Object’s base depth; positive values draw in front and negative values draw behind. Blank preserves the legacy all-effects layer.
Runtime Path Variable	text	Yes	Optional instance variable naming a runtime Path used instead of the Particle resource’s static emission Path.

Change Sprite Deform Property

Changes exactly one retained sprite-deform property while preserving every unrelated setting.

Reference key: setSpriteDeformProperty.

Editor category: Animation and Effects > Sprite Effects.

Example: Set Mode to sway, then animate Amplitude and Speed on independent tracks as a storm arrives.

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

Parameter	Type	Optional	Details
Property	enum	No	The one retained deform property to change. Mode accepts wave, sway, jelly, bulge, twist, skew, or taper. Choices: mode, amplitude, amount, twist angle, skew x, skew y, idle wobble, speed, wavelength, radius, center x, center y, phase, pin edge, axis, grid columns, grid rows, spring frequency, spring damping. Default: “mode”.
Value	mixed	No	The new value. Pin Edge accepts auto, none, top, bottom, left, right, or center; Axis accepts x or y. Default: “sway”. Shown when Property has a selection.
Seconds	number	Yes	Glides a numeric property over this many seconds. Mode, Pin Edge, Axis, and grid resolution change immediately. Default: 0.
Ease	enum	Yes	Easing used when the selected numeric property glides. Choices: linear, easeIn, easeOut, easeInOut. Default: “easeInOut”.

Change Sprite Mask Property

Changes exactly one retained sprite-mask property while preserving every unrelated mask setting.

Reference key: setSpriteMaskProperty.

Editor category: Animation and Effects > Sprite Effects.

Example: Set Shape to ellipse, then animate Width and Height with separate property actions.

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

Parameter	Type	Optional	Details
Property	enum	No	The one retained mask property to change. Shape accepts rect, ellipse, or sprite; Follow accepts object or scene. Choices: shape, mask sprite, width, height, offset x, offset y, corner radius, invert, follow. Default: “shape”.
Value	mixed	No	The new value. Width/Height blank means the frame size; Mask Sprite accepts a Sprite resource name; Invert accepts true/false. Default: “ellipse”. Shown when Property has a selection.
Seconds	number	Yes	Glides Width, Height, offsets, or Corner Radius over this many seconds. Shape, source, Invert, and Follow change immediately. Default: 0.
Ease	enum	Yes	Easing used when the selected numeric property glides. Choices: linear, easeIn, easeOut, easeInOut. Default: “easeInOut”.

Control Fullscreen Video

Plays a Video resource fullscreen like a movie — letterboxed, never stretched. Input is supplied by the selected Command, with a two-press skip so nobody skips a story beat by accident. A missing or broken clip warns and ends the cutscene instead of hanging the game.

Reference key: playVideo.

Editor category: Animation and Effects > Video.

Example: On Game Start: Play Video [intro] with Skip Cinematic, then Go to Scene [Village].

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: play, pause, resume, stop. Default: “play”.
Video	thing:video	No	Choose a video resource. Shown when Operation is play.
Wait until finished	boolean	Yes	The world freezes (like dialogue) until the video ends, is skipped, or is stopped. Default: true. Shown when Operation is play.
Players can skip	boolean	Yes	The selected Command shows “Press again to skip”; a second press skips. Off = the video always plays out. Default: true. Shown when Operation is play.
Skip Command	enum	Yes	A Button Command from Input Manager. Blank means the video cannot be skipped by mapped input. Shown when Operation is play.

Control Particle Emitter

Starts or stops a continuous Particle emitter on this instance. One-shot emission is the separate Burst Particles action.

Reference key: startParticles.

Editor category: Animation and Effects > Particles.

Example: Start a fire trail behind an aircraft, then stop it when the flame is extinguished.

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

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: start, stop. Default: “start”.
Particles	thing:particle	No	Choose a particle resource. Shown when Operation is one of start, burst.
Tint	color	Yes	Per-emitter color multiplier, captured on Start. Blank inherits the target’s Particle Emitter tint, or white. Shown when Operation is one of start, burst.
Opacity	number	Yes	Per-emitter alpha multiplier from 0 to 1. Blank inherits the target’s Particle Emitter opacity, or 1. Shown when Operation is one of start, burst.
Z-index Offset	number	Yes	Optional Object-local layer offset. 0 uses the target Object’s base depth; positive values draw in front and negative values draw behind. Blank keeps the existing defaults: bursts use the effects layer and continuous emitters sit one layer behind their host. Shown when Operation is one of start, burst.
Runtime Path Variable	text	Yes	Optional instance variable naming a runtime Path used instead of the Particle resource’s static emission Path. Shown when Operation is one of start, burst.

Control Rig Animation

Plays or stops a skeletal rig animation on this instance. Live playback speed is a separate atomic action.

Reference key: playRig.

Editor category: Animation and Effects > Rigging.

Example: Play “swing” once, then stop back to the setup pose.

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

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: play, stop. Default: “play”.
Animation	text	No	A rig animation by name — authored on the Skeletal Rig Editor’s timeline. Shown when Operation is play.
Loop	enum	Yes	anim = the animation’s own loop setting; once holds the last frame and fires Animation End. Choices: anim, loop, once. Default: “anim”. Shown when Operation is play.
Fade (sec)	number	Yes	Crossfades between the current animation and the requested state. 0 snaps instantly. Default: 0.15. Shown when Operation is one of play, stop.
Restart if playing	boolean	Yes	On: playing the same animation again starts it over. Off: it keeps going. Default: false. Shown when Operation is play.

Control Timeline Playback

Plays, stops, pauses, or resumes one Timeline resource in one consistent All-or-Self scope. Seeking and playback speed are separate atomic actions.

Reference key: timelinePlay.

Editor category: Animation and Effects > Timeline and Tween.

Example: Play “DoorOpen” on Self, then pause or stop that same scoped playback as needed.

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

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: play, stop, pause, resume. Default: “play”.
Timeline	thing:timeline	No	Choose a timeline resource.
Scope	enum	Yes	“all” controls every matching player; “self” controls only playback bound to this acting instance. Choices: all, self. Default: “all”.
Start At (s)	number	Yes	Number value; decimals are allowed. Default: 0. Shown when Operation is play.

Control Video on Object

Starts or stops a Video on this Object’s picture.

Reference key: playVideoOnObject.

Editor category: Animation and Effects > Video.

Example: On Create of the TV object: play [newsLoop]; on power-off, choose Stop.

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

Parameter	Type	Optional	Details
Operation	enum	No	Choose one of the listed options. Choices: play, stop. Default: “play”.
Video	thing:video	No	Choose a video resource. Shown when Operation is play.
Loop	boolean	Yes	Blank = the Video resource’s Loop on objects setting. Yes plays forever, like a TV; No restores the object’s picture when the video ends. Shown when Operation is play.

Impulse Sprite Deform

Kicks a jelly deform’s spring — the squash-and-stretch pop for landings, hits, and bounces. It wobbles, settles, and goes still (no cost while settled). Only jelly mode responds; there is no effect (and no error) on other modes.

Reference key: impulseSpriteDeform.

Editor category: Animation and Effects > Sprite Effects.

Example: On Collision with the floor: Impulse Sprite Deform -0.8 — a landing squash that boings back.

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

Parameter	Type	Optional	Details
Strength	number	Yes	1 kicks a full wobble at the jelly’s authored Amount; negative squashes first instead of stretching; 0.3 is a light tap. Default: 1.

Remove Camera Shader

Removes one shader from the camera effect stack and leaves the others running in their order.

Reference key: removeCameraShader.

Editor category: Animation and Effects > Shaders.

Example: When the player surfaces, remove the Underwater shader but keep the Scene’s color grade.

Parameter	Type	Optional	Details
Shader	thing:shader	No	Choose a shader resource.

Seek Timeline

Jumps matching playback to a signed raw time and applies that frame immediately.

Reference key: timelineSeek.

Editor category: Animation and Effects > Timeline and Tween.

Example: On Custom Event [replay], seek “Intro” back to 0.

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

Parameter	Type	Optional	Details
Timeline	thing:timeline	No	Choose a timeline resource.
Time (s)	number	No	Expression or literal value. Default: 0.
Scope	enum	Yes	Choose one of the listed options. Choices: all, self. Default: “all”.

Set Camera Shader

Applies a custom shader as a full-screen post effect on the camera: by default to the game world, leaving Screen UI clear; Applies To: Screen includes the UI. Leave Shader blank to clear it.

Reference key: setCameraShader.

Editor category: Animation and Effects > Shaders.

Example: On Scene Start, set a CRT or underwater shader for the whole screen; use blank to restore the normal view.

Parameter	Type	Optional	Details
Shader	thing:shader	Yes	Blank removes the current camera shader.
Applies To	enum	Yes	World shades the game world only; Screen UI (the HUD) stays clear. Screen shades the whole screen, Screen UI included. Choices: world, screen. Default: “world”.

Set Camera Shader Strength

Blends one shader in the camera effect stack with the image beneath it, from 0 (off) to 1 (full effect). Animate it from Step or an Alarm to fade an effect in or out.

Reference key: setCameraShaderStrength.

Editor category: Animation and Effects > Shaders.

Example: In Step, raise the Damage Flash strength toward 1 while health is low.

Parameter	Type	Optional	Details
Shader	thing:shader	No	Choose a shader resource.
Strength	number	No	0 leaves the image unchanged, 1 is the full effect. Default: 1.

Set Fullscreen Video Volume

Sets the volume used by the current and later fullscreen videos. Playback transport remains a separate action, and the Master and Music mixer buses still apply.

Reference key: setVideoVolume.

Editor category: Animation and Effects > Video.

Example: Set Fullscreen Video Volume to 0.5 before playing a quiet background movie.

Parameter	Type	Optional	Details
Volume (0-1)	number	No	Expression or literal value. Default: 1.

Set Object Shader

Applies a custom shader as a post effect on this instance only. Leave Shader blank to clear it.

Reference key: setObjectShader.

Editor category: Animation and Effects > Shaders.

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

Parameter	Type	Optional	Details
Shader	thing:shader	Yes	Blank removes the current object shader.

Set Object Shader Param

Sets a custom uniform on this instance’s object shader only, overriding the shared Set Shader Param value for it. Clearing the object shader or switching to a different one forgets the override. A texture uniform takes a Sprite name, or @identity-lut, @identity-lut-32 or @noise.

Reference key: setObjectShaderParam.

Editor category: Animation and Effects > Shaders.

Example: When an enemy is hit, set its “flash” uniform to 1 so only that enemy flashes.

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

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

Set Object Video Volume

Sets the volume used by the current and later videos on this Object without starting or stopping its screen.

Reference key: setObjectVideoVolume.

Editor category: Animation and Effects > Video.

Example: Set Object Video Volume to 0 for a silent billboard, then play its looping clip.

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

Parameter	Type	Optional	Details
Volume (0-1)	number	No	Expression or literal value. Default: 1.

Set Rig

Changes only the skeletal rig this instance uses. Rig appearance and animation playback are separate Atomic actions.

Reference key: setRig.

Editor category: Animation and Effects > Rigging.

Example: Set Rig to the transformed character rig, then use Control Rig Animation to choose its first animation.

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

Parameter	Type	Optional	Details
Rig	thing:rig	Yes	Blank restores the object’s own Skeletal Rig setting.

Set Rig IK Target

Points an IK chain at a live target: two-bone chains (arm, leg) reach it with a natural elbow bend, one-bone chains aim along it. The rest of the animation keeps playing — heads track the pointer, feet plant, arms grab.

Reference key: setRigIK.

Editor category: Animation and Effects > Rigging.

Example: On Step: Set Rig IK Target chain “arm-r” to pointer — the hero’s arm follows the mouse while the walk cycle plays.

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

Parameter	Type	Optional	Details
IK Chain	text	No	An IK chain by name (authored in the Skeletal Rig Editor).
Target	enum	No	Point uses X and Y in the selected Position Relative To space. Object follows another Object; Pointer follows the mouse. Off returns to keyframes. Choices: point, object, pointer, off. Default: “point”.
Position Relative To	enum	Yes	World uses absolute Scene coordinates. For a Screen UI Object, that world point is projected into its screen coordinate frame. Screen uses pixels from the Screen Anchor, matching the Screen Offset fields. World Objects treat Screen as World. Object uses offsets from the acting Object, while Coordinate uses offsets from a named Coordinate. Bounding Box uses offsets from the selected Transform bounding-box anchor. Choices: world, screen, object, coordinate, boundingBox. Default: “world”.
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	Point target X in the coordinate space selected by Position Relative To.
Y	number	Yes	Point target Y in that same coordinate space.
Object	thing:object	Yes	The object to reach toward (object mode; nearest instance).
Mix (0-1)	number	Yes	How strongly IK overrides the animation (0 = off, 1 = full). Default: 1.
Bend	enum	Yes	Which way a two-bone chain’s elbow/knee folds. Choices: +, -. Default: “+”.

Set Rig Part

Changes one named rig attachment while the skeleton keeps playing. Selecting a complete authored outfit is the separate Set Rig Part Set Atomic.

Reference key: setRigPart.

Editor category: Animation and Effects > Rigging.

Example: Change the hand slot to “Axe”; use Set Rig Part Set for the complete “Winter Coat” outfit.

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

Parameter	Type	Optional	Details
Slot	text	No	The rig slot to change, by name (e.g. “hand-r”).
Sprite	thing:sprite	Yes	The new part image. Blank + blank frame = back to the slot’s own part.
Frame	number	Yes	Frame index within the sprite. Blank keeps the slot’s frame.

Set Rig Part Set

Changes a rig’s complete outfit or visual variant in one action. Individual Set Rig Part overrides still win, so equipped weapons can stay equipped through a costume change.

Reference key: setRigPartSet.

Editor category: Animation and Effects > Rigging.

Example: On entering the snow biome: Set Rig Part Set “Winter Coat” on the player.

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

Parameter	Type	Optional	Details
Part Set	text	Yes	A Part Set authored on the rig. Blank restores the rig’s default artwork.

Set Rig Speed

Changes the playing rig animation’s speed — slow-motion swings, frozen poses, haste effects.

Reference key: setRigSpeed.

Editor category: Animation and Effects > Rigging.

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

Parameter	Type	Optional	Details
Speed	number	No	Playback rate multiplier for the current animation. 0 freezes mid-pose. Default: 1.

Set Scene Sprite Shader

Applies a Shader independently in every 2D Sprite resource frame, including Sprites created later. The Background and UI remain outside the effect. Leave Shader blank to clear it.

Reference key: setSpriteShader.

Editor category: Animation and Effects > Shaders.

Example: On Scene Start, set an ASCII Shader to convert every aircraft, projectile, pickup, and scenery Sprite in its own local coordinates.

Parameter	Type	Optional	Details
Shader	thing:shader	Yes	Blank removes the current scene-wide Sprite shader.

Set Shader Param

Sets a custom uniform on a shader (animate it from Step or an Alarm). A texture uniform takes a Sprite name, or @identity-lut, @identity-lut-32 or @noise.

Reference key: setShaderParam.

Editor category: Animation and Effects > Shaders.

Example: In Step, ramp a “progress” uniform 0..1 to drive a transition.

Parameter	Type	Optional	Details
Shader	thing:shader	No	Choose a shader resource.
Uniform	text	No	Text value; some actions also accept $global names.
Value	number	No	Expression or literal value.

Set Sprite Deform State

Changes only whether this instance uses its retained visual sprite deformation.

Reference key: setSpriteDeformEnabled.

Editor category: Animation and Effects > Sprite Effects.

Example: Turn a wind sway off, then enable it later with the same mode and tuning.

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

Parameter	Type	Optional	Details
Enabled	boolean	No	On applies the retained deformation tuning (or a default wave); Off restores a rigid sprite without discarding that tuning. Default: true.

Set Sprite Mask State

Changes only whether this instance uses its retained visual sprite mask.

Reference key: setSpriteMaskEnabled.

Editor category: Animation and Effects > Sprite Effects.

Example: Disable the mask during editing, then enable it later without rebuilding its shape.

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

Parameter	Type	Optional	Details
Enabled	boolean	No	On applies the retained mask tuning (or a default rectangle); Off reveals the complete sprite without discarding that tuning. Default: true.

Set Timeline Speed

Sets matching playback rate. Negative plays backwards; use Pause instead of zero.

Reference key: timelineSpeed.

Editor category: Animation and Effects > Timeline and Tween.

Example: While the Fast Forward Command is active, set “ConveyorLoop” speed to 2.

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

Parameter	Type	Optional	Details
Timeline	thing:timeline	No	Choose a timeline resource.
Speed ×	number	No	Expression or literal value. Default: 1.
Scope	enum	Yes	Choose one of the listed options. Choices: all, self. Default: “all”.

Stop Tween

Stops Tween Property on the selected property for the target instance. Choose All to stop every running property tween. Values stay where they stopped. A later Set Alpha or Set Position therefore keeps its assigned value. Starting another tween replaces the running tween when both use the same property on that instance.

Reference key: stopTween.

Editor category: Animation and Effects > Timeline and Tween.

Example: Stop Tween Alpha, then Set Alpha to 1, to cancel a fade-out.

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

Parameter	Type	Optional	Details
Property	enum	No	All stops every tween on this instance. Scale also stops a Horizontal Scale or Vertical Scale tween, and either axis stops a Scale tween. Choices: all, alpha, scale, horizontal scale, vertical scale, angle, x, y. Default: “all”.

Tween Property

Moves one visual or spatial property toward a target value. Scale uses size multipliers, with 1 representing the authored size; Horizontal Scale and Vertical Scale animate separate axes. A new tween replaces the running tween on its property. Scale overlaps both axis tweens; either axis also overlaps Scale. Other properties continue.

Reference key: tweenProperty.

Editor category: Animation and Effects > Timeline and Tween.

Example: Tween Horizontal Scale to 1.5 over 0.4 seconds while Vertical Scale stays unchanged. Use the Tween Property Lifecycle Logic when completion should also destroy the instance.

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

Parameter	Type	Optional	Details
Property	enum	No	Scale changes both size multipliers together. Horizontal Scale and Vertical Scale animate one axis while preserving the other; 1 is the authored size. Choices: alpha, scale, horizontal scale, vertical scale, angle, x, y. Default: “alpha”.
Target Value	number	No	Expression or literal value.
Seconds	number	No	Duration in simulation seconds. Accepts numbers, instance variables, globals, and expressions. Default: 0.5.
Ease	enum	Yes	Choose one of the listed options. Choices: linear, easeIn, easeOut, easeInOut, smooth. Default: “linear”.