Objects Actions

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

Add Rotation

Adds a signed number of degrees to the current planar rotation.

Reference key: rotate.

Editor category: Objects > Facing and Rotation.

Example: In Step, add a few degrees of rotation to spin a coin.

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

Parameter	Type	Optional	Details
Degrees	number	No	Expression or literal value.

Add To Instance Set

Adds the targets (Applies To) to an Instance Set made earlier by Make Instance Set, or to an Instance Set Variable; an instance already in it is not added twice.

Reference key: addToInstanceSet.

Editor category: Objects > Manage Objects.

Example: Inside a Repeat, after Create Instance (Created As “enemy”), Add To Instance Set “wave” with Applies To “enemy”.

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

Parameter	Type	Optional	Details
Instance Set	instanceTarget	No	An Instance Set made earlier by Make Instance Set, or an Instance Set Variable. Each live target is added once.

Add to Position

Adds an expression-driven X/Y offset to the current position once. Use Move at Speed for frame-rate-independent continuous movement.

Reference key: movePosition.

Editor category: Objects > Position.

Example: In an Axis Direction Pressed event, move relative by a small X or Y offset for discrete grid motion.

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

Parameter	Type	Optional	Details
X Offset	number	No	Immediate horizontal offset. Accepts numbers, variables, globals, and expressions.
Y Offset	number	No	Immediate vertical offset. Accepts numbers, variables, globals, and expressions.

Add to Z Order

Adds a signed amount to this instance Z Order. Positive values move it forward; negative values move it backward.

Reference key: addDepth.

Editor category: Objects > Scale and Z Order.

Example: In Mouse Pressed On Object, add 1 to depth to bring the clicked object forward.

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

Parameter	Type	Optional	Details
Amount	number	No	Expression or literal value.

Attach to Parent

Attaches this instance to the nearest live instance of one selected parent Object. The anchor, local offset, inheritance, and destruction settings describe that one hierarchy link; cycles are rejected.

Reference key: reparentInstance.

Editor category: Objects > Object Hierarchy.

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

Parameter	Type	Optional	Details
Parent	instanceTarget	Yes	The exact parent: Self, Other, a named result (Created As, Results As, a Function Output), an Instance Parameter, or Its Creator (each target joins the instance that created it). Leave it on Nearest Instance of Object to pick by Object instead. When it names several instances, the nearest one is used. Default: “”.
New Parent Object	thing:object	No	The nearest live instance of this Object becomes the parent. Shown when Parent is blank.
Keep World Position	boolean	Yes	On preserves the instance where it is. Off applies Local XYZ immediately. Default: true.
Parent Anchor	enum	Yes	Choose one of the listed options. Choices: origin, coordinate, boundingBox. Default: “origin”.
Anchor Name	text	Yes	Coordinate name/id, or a Bounding Box point such as topRight.
Local X	number	Yes	Expression or literal value. Default: 0.
Local Y	number	Yes	Expression or literal value. Default: 0.
Local Z	number	Yes	Expression or literal value. Default: 0.
Inherit Rotation	boolean	Yes	On or off. Default: true.
Inherit Scale	boolean	Yes	On or off. Default: true.
Inherit Visibility	boolean	Yes	On or off. Default: true.
Destroy with Parent	boolean	Yes	On or off. Default: true.

Change Component Value

Changes one mutable Object Component value through its direct path. The value type comes from that component schema. The Operator sets the value (=) or combines it with the current value (+=, -=, *=, /=); combining needs a Number property.

Reference key: setComponentProperty.

Editor category: Objects > Components.

Parameter	Type	Optional	Details
Component Value	objectComponentProperty	No	Type or choose a mutable Object Component path such as victim.health.current.
Operator	enum	Yes	Choose one of the listed options. Choices: =, +=, -=, *=, /=. Default: “=”.
Value	mixed	No	Expression or literal value.

Change Instance

Re-identifies one live instance as another Object, adopting that Object’s Logic, visual, collider, depth, and visibility while preserving position, velocity, and instance variables.

Reference key: changeInstance.

Editor category: Objects > Manage Objects.

Example: Change a closed chest into Open Chest without moving it; optionally run the new Object’s Create event.

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

Parameter	Type	Optional	Details
Object	thing:object	No	Object resource name. Live-instance target parameters may also select an attached Child Object placement.
Run Create Event	boolean	Yes	On or off. Default: false.

Change Sprite Flip Property

Changes horizontal or vertical sprite mirroring without resetting the other axis.

Reference key: setSpriteFlipProperty.

Editor category: Objects > Sprites.

Example: In Step, set Horizontal to (vx < 0) to face the movement direction.

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

Parameter	Type	Optional	Details
Property	enum	No	Choose one of the listed options. Choices: horizontal, vertical. Default: “horizontal”.
Value	mixed	No	Zero turns mirroring off for the selected axis; any nonzero value turns it on. Default: 0. Shown when Property has a selection.

Change Sprite Tint Property

Changes exactly one persistent sprite-tint property while preserving every unrelated tint setting. Disabling removes the visible tint without discarding Color or Mode.

Reference key: setSpriteTintProperty.

Editor category: Objects > Sprites.

Example: Set Color to #ff3b30, Mode to solid, then Enabled to true as three independent actions.

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

Parameter	Type	Optional	Details
Property	enum	No	The one persistent sprite-tint property to change. Enabled state is independent from Color and Mode. Choices: enabled, color, mode. Default: “color”.
Value	mixed	No	The new value. Enabled accepts true/false; Color accepts a color; Mode accepts multiply or solid. Default: “#ffffff”. Shown when Property has a selection.

Clear All Swarms

Removes every live swarm entity from every Sprite pool.

Reference key: swarmClearAll.

Editor category: Objects > Swarms.

Clear Swarm

Removes every live swarm entity that uses one selected Sprite while preserving every other swarm pool.

Reference key: swarmClear.

Editor category: Objects > Swarms.

Parameter	Type	Optional	Details
Sprite	thing:sprite	No	Choose a sprite resource.

Create Instance

Creates one instance at world XYZ, Self-relative XYZ, or an exact named Coordinate, and names it (Created As). Follow it with ordinary Atomics that target that name to configure hierarchy, motion, facing, or other state.

Reference key: spawn.

Editor category: Objects > Manage Objects.

Example: Create a bullet at Self’s Muzzle Coordinate, Created As “bullet”, then Set Rotation with Applies To “bullet”.

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

Parameter	Type	Optional	Details
Object to Create	thing:object	No	Object resource name. Live-instance target parameters may also select an attached Child Object placement.
Position Relative To	enum	No	World uses absolute XYZ coordinates. Self places relative to the Object holding this Logic. Choices: world, object. Default: “world”.
Self Position	enum	No	XYZ uses local offsets from Self. Coordinate uses one named Coordinate attached to Self. Choices: xyz, coordinate. Default: “xyz”.
Coordinate	text	Yes	A named Coordinate attached to the Object holding this Logic.
X	number	No	Expression or literal value.
Y	number	No	Expression or literal value.
Z (Height)	number	Yes	Optional height in a 3D Scene, in meters (Blender Z).
Launch Speed	number	Yes	Optional starting speed for the new instance. Leave blank to create it standing still.
Launch Angle (deg)	number	Yes	Direction of the starting speed in degrees, measured the same way as Set Direction. Used only when Launch Speed is set. Default: 0.
Angle Relative To	enum	Yes	World measures Launch Angle from the screen; Creator adds the creating instance’s facing. Choices: world, creator. Default: “world”.
Created As	resultName	No	Names what this Create makes, so later Actions in this Event or Function can target it. The name is local: it is gone when the Event or Function finishes. Default: “created”.

Results

Field	Type	Description
count	number

Destroy Instance

Destroys the selected target: Self, Event other, or all live instances of a named Object.

Reference key: destroySelf.

Editor category: Objects > Manage Objects.

Example: In Collision with Player, destroy a pickup after it is collected.

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

Detach From Parent

Keeps this instance at its current world transform, removes its runtime parent, and restores ordinary physics.

Reference key: detachFromParent.

Editor category: Objects > Object Hierarchy.

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

Face Toward

Immediately faces an Object or resolved position without moving.

Reference key: faceToward.

Editor category: Objects > Facing and Rotation.

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

Parameter	Type	Optional	Details
Target	enum	No	Choose one of the listed options. Choices: object, position. Default: “object”.
Target Object	thing:object	No	The nearest live instance of this Object is used. The acting instance is never its own target. Shown when Target is object.
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”. Shown when Target 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 Target is position.
Y	number	No	Expression or literal value. Default: 0. Shown when Target is position.
Rotation Offset	number	Yes	Added after aiming. Use this when the artwork’s forward direction is not zero degrees. Default: 0.

Lerp Position Toward

Moves partway toward an Object or resolved position once. Call it repeatedly for smooth exponential following; Amount is clamped from 0 to 1.

Reference key: lerpPosition.

Editor category: Objects > Position.

Example: In Step, lerp a camera anchor 0.12 toward a Player Coordinate.

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

Parameter	Type	Optional	Details
Target	enum	No	Choose one of the listed options. Choices: object, position. Default: “position”.
Target Object	thing:object	No	The nearest live instance of this Object is used. The acting instance is never its own target. Shown when Target is object.
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”. Shown when Target 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 Target is position.
Y	number	No	Expression or literal value. Default: 0. Shown when Target is position.
Z (Height)	number	Yes	Optional target feet height in a 3D Scene, in meters (Blender Z). Shown when Target is position.
Amount (0-1)	number	No	Interpolation amount for this execution. 0 keeps the current position; 1 reaches the target. Default: 0.1.

Lerp Rotation

Lerps toward an angle, Object, or position. Amount gives smooth proportional convergence; Speed gives fixed degrees-per-second turning.

Reference key: lerpRotation.

Editor category: Objects > Facing and Rotation.

Example: In Step, lerp a vehicle toward 0 degrees with Amount 0.08.

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

Parameter	Type	Optional	Details
Target	enum	No	Choose one of the listed options. Choices: angle, object, position. Default: “angle”.
Target Rotation	number	No	Target planar rotation in degrees. Default: 0. Shown when Target is angle.
Target Object	thing:object	No	The nearest live instance of this Object is used. The acting instance is never its own target. Shown when Target is object.
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”. Shown when Target 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 Target is position.
Y	number	No	Expression or literal value. Default: 0. Shown when Target is position.
Interpolation	enum	No	Choose one of the listed options. Choices: amount, speed. Default: “amount”.
Amount (0-1)	number	No	Fraction of the remaining shortest arc applied each execution. Default: 0.1. Shown when Interpolation is amount.
Speed (deg/s)	number	No	Maximum planar rotation speed in degrees per second. Default: 180. Shown when Interpolation is speed.
Rotation Offset	number	Yes	Expression or literal value. Default: 0. Shown when Target is one of object, position.

Lerp Scale

Changes each supplied scale axis partway toward its target once. Call it repeatedly for smooth exponential scaling; Amount is clamped from 0 to 1.

Reference key: lerpScale.

Editor category: Objects > Scale and Z Order.

Example: In Step, lerp a pickup toward 1.2 on both scale axes with Amount 0.15.

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

Parameter	Type	Optional	Details
Target Horizontal Scale	number	Yes	Target horizontal size multiplier. Blank preserves the current horizontal scale. Default: 1.
Target Vertical Scale	number	Yes	Target vertical size multiplier. Blank preserves the current vertical scale. Default: 1.
Amount (0-1)	number	No	Interpolation amount for this execution. 0 keeps the current scale; 1 reaches the target. Default: 0.1.

Make Instance Set

Makes an empty, named Instance Set for later Actions in this Event or Function to fill with Add To Instance Set, for example everything a Repeat creates.

Reference key: makeInstanceSet.

Editor category: Objects > Manage Objects.

Example: Make Instance Set “wave”, then Repeat 5 { Create Enemy, Created As “enemy”; Add To Instance Set “wave” with Applies To “enemy” }, then Set Speed on “wave”.

Parameter	Type	Optional	Details
Name	resultName	No	Names a new, empty Instance Set. Add To Instance Set fills it; Applies To can then target everything in it. The name is local: it is gone when the Event or Function finishes. Default: “group”.
Of Object	objectInput	Yes	Optional: the Object Parameter whose Object the set holds. Then expressions read its Components (wave.transform.position.x) and only instances of that Object can be added.

Results

Field	Type	Description
count	number

Search Instances

Finds live Objects by Components, Tag, or distance, stores the complete named result set for this Logic, then runs the nested actions once per result with that result as Self.

Reference key: searchByComponent.

Editor category: Objects > Search and Queries.

Example: Search Instances by Tag [enemy], Order Nearest, as NearbyEnemies, then target NearbyEnemies from a later action.

Parameter	Type	Optional	Details
Results As	resultName	No	Names the matching InstanceSet so later actions in this Event or Function can target it. The name is local: it is gone when the Event or Function finishes. Default: “searchResults”.
Find By	enum	No	Choose one of the listed options. Choices: component, tag, distance. Default: “component”.
Required Components	componentList	No	Drop one or more Components from the Component List. A matching Object must have these components. Shown when Find By is component.
Match Components	enum	Yes	All requires every listed Component; Any accepts an Object with at least one. Choices: all, any. Default: “all”. Shown when Find By is component.
Required Tag	text	No	Choose a Tag. A matching Object must carry that tag. Shown when Find By is tag.
From Object	thing:object	Yes	Measure from its nearest live instance. Blank measures from Self. Shown when Find By is distance.
Within Distance (m)	number	No	Objects at or inside this distance are included. Default: 4. Shown when Find By is distance.
Of Object	thing:object	Yes	Keep only instances of this Object. Its Components can then be read through the result name (for example nearby.health.value). Blank keeps every match.
Order	enum	Yes	Creation keeps the order instances were created in; Nearest puts the closest to Self (or the From Object) first, ties in creation order. Choices: creation, nearest. Default: “creation”.

Results

Field	Type	Description
count	number

Set Active

Activates or deactivates the target Object. Inactive Objects do not render, run Logic, receive input, or participate in physics.

Reference key: setActive.

Editor category: Objects > Sprites.

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

Parameter	Type	Optional	Details
Active	boolean	No	On or off.

Set Alpha

Sets alpha for the target or game.

Reference key: setAlpha.

Editor category: Objects > Sprites.

Example: In Create, set alpha to 0.5 for a ghost object.

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

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

Set Animation Clip

Changes the animation clip used by this instance.

Reference key: setAnimation.

Editor category: Objects > Sprites.

Example: In an Axis Direction Held event, set the Run animation clip for that direction.

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

Parameter	Type	Optional	Details
Clip	thing:animationClip	No	Choose a animation clip resource.

Set Frame

Sets frame for the target or game.

Reference key: setFrame.

Editor category: Objects > Sprites.

Example: In Create, set a specific sprite frame for a tile-like object.

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

Parameter	Type	Optional	Details
Frame	number	No	Whole number value.

Set Instance Set

Replaces what an Instance Set (made by Make Instance Set, or an Instance Set Variable) holds, for example with what the Create just before it made. Use Add To Instance Set to keep the earlier contents.

Reference key: setInstanceSet.

Editor category: Objects > Manage Objects.

Example: In each of several Ifs, after Create Instance (Created As “piece”), Set Instance Set “lastPiece” To “piece”; after the Ifs, target “lastPiece”.

Parameter	Type	Optional	Details
Instance Set	instanceTarget	No	An Instance Set made earlier by Make Instance Set, or an Instance Set Variable. Its contents are replaced.
To	instanceTarget	Yes	What the set holds from now on: a named result, an Instance Parameter, an Instance or Instance Set Variable, Self or Other. Nothing empties the set. Default: “”.

Set Position

Moves the target immediately to a world position, an Object-local offset, a named Coordinate, or a Transform bounding-box anchor. Axes accept numbers, declared Parameters, Variables, and expressions.

Reference key: setPosition.

Editor category: Objects > Position.

Example: In Scene Start, set the player position to a checkpoint Coordinate.

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

Parameter	Type	Optional	Details
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	No	Expression or literal value.
Y	number	No	Expression or literal value.
Z (Height)	number	Yes	Optional feet height in a 3D Scene, in meters (Blender Z; up is +Z).

Set Rotation

Sets the exact planar rotation in degrees. Use Add Rotation for a relative turn.

Reference key: setAngle.

Editor category: Objects > Facing and Rotation.

Example: Set one exact planar rotation in degrees.

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

Parameter	Type	Optional	Details
Degrees	number	No	Expression or literal value.

Set Scale

Sets the Object instance’s live size multipliers. A value of 1 restores the authored component size; use the same value on both axes for uniform scaling.

Reference key: setScale.

Editor category: Objects > Scale and Z Order.

Example: In Create, set Horizontal Scale to 1.5 and Vertical Scale to 0.8 for a wide, squashed pickup.

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

Parameter	Type	Optional	Details
Horizontal Scale	number	Yes	Horizontal size multiplier. 1 keeps the authored width; blank preserves the current horizontal scale. Default: 1.
Vertical Scale	number	Yes	Vertical size multiplier. 1 keeps the authored height; blank preserves the current vertical scale. Default: 1.

Set Sprite

Changes the sprite resource. Animation playback and fixed-frame selection are separate atomic actions.

Reference key: setSprite.

Editor category: Objects > Sprites.

Example: Set Sprite for a costume swap.

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

Parameter	Type	Optional	Details
Sprite	thing:sprite	No	Choose a sprite resource.

Set Visible

Sets visible for the target or game.

Reference key: setVisible.

Editor category: Objects > Sprites.

Example: In Create, hide a trigger object while keeping its collision active.

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

Parameter	Type	Optional	Details
Visible	boolean	No	On or off.

Set Z Order

Sets the exact Z Order used to sort this instance. Higher values draw in front of lower values.

Reference key: setDepth.

Editor category: Objects > Scale and Z Order.

Example: Set Z Order to y for exact top-down sorting.

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

Parameter	Type	Optional	Details
Depth / Amount	number	No	Number value; decimals are allowed.

Spawn Swarm

Spawns one optimized transient batch of a Sprite. Clearing one Sprite pool or every pool uses separate actions.

Reference key: swarmSpawn.

Editor category: Objects > Swarms.

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

Parameter	Type	Optional	Details
Sprite	thing:sprite	No	The Sprite used by this homogeneous transient batch.
Count	number	No	Expression or literal value. Default: 20.
X	number	Yes	Blank spawns at this instance.
Y	number	Yes	Blank spawns at this instance.
Spread X	number	Yes	Expression or literal value. Default: 0.
Spread Y	number	Yes	Expression or literal value. Default: 0.
Velocity X	number	Yes	Expression or literal value. Default: 0.
Velocity Y	number	Yes	Expression or literal value. Default: 0.
Velocity Spread X	number	Yes	Expression or literal value. Default: 0.
Velocity Spread Y	number	Yes	Expression or literal value. Default: 0.
Lifetime (seconds)	number	No	Expression or literal value. Default: 3.
Sprite Frame	number	Yes	Expression or literal value. Default: 0.
Depth	number	Yes	Expression or literal value. Default: 0.