Movement and Physics Actions

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

Add Velocity

Adds to horizontal velocity, vertical velocity, or both. A blank axis is unchanged.

Reference key: addVelocity.

Editor category: Movement and Physics > Motion.

Example: In Step, add a small Y Velocity each frame for custom gravity.

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

Parameter	Type	Optional	Details
X Amount	number	Yes	Signed horizontal velocity change. Blank leaves horizontal velocity unchanged.
Y Amount	number	Yes	Signed vertical velocity change. Blank leaves vertical velocity unchanged.

Apply Force

A continuous push — wind, a rocket engine, a magnet. Speed builds up over time instead of jumping instantly. A force only lasts one frame, so put it in Step or Command Held to keep pushing.

Reference key: applyForce.

Editor category: Movement and Physics > Physics Forces.

Example: In Command Held [Thrust], Apply Force with Strength 600 and Direction 270 — a rocket thruster that gradually beats gravity.

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

Parameter	Type	Optional	Details
Strength	number	No	The steady push. A Mass 1 object gains this much speed every second (m/s²); heavier objects accelerate less. Default: 12.5.
Direction (deg)	number	No	0 pushes right, 90 up, 180 left, and 270 down. Default: 0.
Push Point X	number	Yes	Push this many meters right of the origin (turns with the object) — an off-center force also twists it. Needs “Allow rotation”. Default: 0.
Push Point Y	number	Yes	Vertical part of the push point, in meters (positive is above the origin). Default: 0.

Apply Impulse

Applies one mass-aware impulse, optionally off-center so an object with Allow rotation also spins. Continuous force is a separate Atomic action.

Reference key: applyImpulse.

Editor category: Movement and Physics > Physics Forces.

Example: On Collision [Bomb], apply an instant impulse; use Apply Force in Step for wind or a rocket engine.

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

Parameter	Type	Optional	Details
Strength	number	Yes	How hard to push. Blank uses an impulse of 200. Heavier objects respond less.
Direction (deg)	number	No	0 pushes right, 90 up, 180 left, and 270 down. Default: 0.
Push Point X	number	Yes	Land the push this many meters right of the object’s origin (the point turns with the object). An off-center push also makes it spin — turn on “Allow rotation” in the object’s Physics panel. Default: 0.
Push Point Y	number	Yes	Vertical part of the push point, in meters (positive is above the origin). Default: 0.

Apply Torque

Applies mass-aware torque for this physics step. Direct angular speed is a separate Set Spin Atomic.

Reference key: applyTorque.

Editor category: Movement and Physics > Physics Forces.

Example: Use Apply Torque in Step to drive a physical wheel.

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

Parameter	Type	Optional	Details
Value (torque or deg/sec)	number	Yes	Apply Torque uses twisting force (blank 3000); Set Speed uses degrees per second (blank 180). Positive turns counter-clockwise.

Bounce

Reflects this instance away from Other while preserving its current speed, and makes the contact fully elastic. Use it in a Collision event.

Reference key: bounce.

Editor category: Movement and Physics > Movement Forces.

Example: On Collision with a wall or paddle, Bounce the ball away from Other.

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

Change Path Movement Property

Changes exactly one retained path-movement property while preserving every unrelated setting. Active movement adopts the changed property immediately.

Reference key: setPathProperty.

Editor category: Movement and Physics > Path Movement.

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

Parameter	Type	Optional	Details
Property	enum	No	The one retained path-movement property to change. Path selects a project Path; Runtime Path Variable names an instance variable whose non-empty text overrides it when movement starts. Choices: path, runtime path variable, speed, end mode, face travel, facing offset, ease. Default: “path”.
Value	mixed	No	The new value. Speed and Facing Offset accept numbers; Face Travel accepts true/false; End Mode accepts stop, restart, or reverse; Ease accepts a Path easing name. Default: “”. Shown when Property has a selection.

Chase Object

Keeps this instance going after the nearest instance of an Object, along a route around walls, solid tiles and fixed solid Objects that updates as the target moves. It holds position within Stop Distance and follows again when the target moves off. Works in 2D and 3D Scenes.

Reference key: chaseObject.

Editor category: Movement and Physics > Navigation.

Example: When the Hero enters the room: Chase Object [Hero], Stop Distance 40.

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

Parameter	Type	Optional	Details
Object	thing:object	No	Chase the nearest living instance of this Object.
Speed	number	Yes	Meters per second along the route. Default: 3.75.
Stop Distance	number	Yes	Hold position this many meters from the target. 0 stops when the two bodies touch. Default: 0.
Re-plan Every	number	Yes	Seconds between route updates. The route also updates whenever the target moves away from where it was. Default: 0.5.
Avoid Others	boolean	Yes	Keep apart from other navigating instances instead of piling up. Default: true.

Control Joint Lifecycle

Creates or detaches one 2D joint lifecycle. Creation connects this object with a pin, rod, spring, rope, or weld, or pins it directly to the world. Detach cuts one named joint or every joint on this object. Motor speed and swing limits remain separate focused Atomics.

Reference key: createJoint.

Editor category: Movement and Physics > Physics Joints.

Example: Create a Rope joint to the Crane Arm named winch, then run Control Joint Lifecycle with Detach and name winch to release it.

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

Parameter	Type	Optional	Details
Operation	enum	No	Choose the physical connection to create, or Detach to cut matching live joints. Choices: pin to object, pin in place, rod, spring, rope, weld, detach. Default: “pin to object”.
To Object	thing:object	No	Connect to the nearest living instance of this Object. Shown when Operation is one of pin to object, rod, spring, rope, weld.
Length	number	Yes	Distance in meters. Leave 0 to use the distance the objects stand at now. Default: 0. Shown when Operation is one of rod, spring, rope.
Stiffness (Hz)	number	Yes	How quickly the spring pulls toward its rest length. Default: 4. Shown when Operation is spring.
Damping (0-1)	number	Yes	How quickly spring wobble settles. Default: 0.5. Shown when Operation is spring.
Anchor X	number	Yes	This object’s anchor point in meters right of its origin. Default: 0. Shown when Operation is one of pin to object, pin in place, rod, spring, rope.
Anchor Y	number	Yes	This object’s anchor point in meters above its origin. Default: 0. Shown when Operation is one of pin to object, pin in place, rod, spring, rope.
Joint Name	text	Yes	For creation, assigns an optional label. Detach cuts only this label; blank cuts every joint on the object.

Control Path Movement

Starts or stops path movement using the properties configured by Change Path Movement Property.

Reference key: controlPathMovement.

Editor category: Movement and Physics > Path Movement.

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

Parameter	Type	Optional	Details
Operation	enum	No	Starts the retained Path setup from its beginning, or stops movement while preserving that setup. Choices: start, stop. Default: “start”.

Face Direction

Turns the grid walker to face a direction (or the mouse / another object) without stepping.

Reference key: faceDirection.

Editor category: Movement and Physics > Motion.

Example: When a dialogue starts, Face Direction towardObject the player so the NPC turns to them.

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

Parameter	Type	Optional	Details
Direction	enum	No	Choose one of the listed options. Choices: up, down, left, right, towardMouse, towardObject. Default: “down”.
Object	thing:object	Yes	Used by “towardObject” — the nearest-listed instance to face.

Limit Joint Swing

Fences this object’s pin joints between two angles, measured from how the pair stood when pinned: a door that opens 90° and no further, a lever with two ends, a seesaw that can’t flip all the way over. The swing stops firmly at each end. (Angle fidelity needs a Myth engine, where bodies really rotate.)

Reference key: setJointLimits.

Editor category: Movement and Physics > Physics Joints.

Example: After pinning at its edge, the Door runs Limit Joint Swing 0 to 90 — it opens one way and stops against the frame.

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

Parameter	Type	Optional	Details
Min Swing (deg)	number	No	The farthest it may swing clockwise from how the pair stood when pinned (0 = that starting pose). Default: -45.
Max Swing (deg)	number	No	The farthest it may swing counter-clockwise from the starting pose. Default: 45.
Joint Name	text	Yes	Limit only pins with this label. Blank limits every pin joint on this object.

Move at Speed

Moves by an X/Y meters-per-second (m/s) vector for the current simulation step. The runtime scales the vector by elapsed simulation time.

Reference key: moveAtSpeed.

Editor category: Movement and Physics > Motion.

Example: In 2D Axis Input [Move], use event.axisVector.x and event.axisVector.y for frame-rate-independent movement; positive Y moves up.

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

Parameter	Type	Optional	Details
X	number	No	Horizontal movement. Per Second is frame-rate independent; Offset is applied once immediately. Default: 0.
Y	number	No	Vertical movement. Per Second is frame-rate independent; Offset is applied once immediately. Default: 0.

Move Toward Point

Sets one velocity vector aimed at the resolved point with the requested speed. It does not stop automatically on arrival.

Reference key: moveToward.

Editor category: Movement and Physics > Motion.

Example: Aim a projectile toward the Player Coordinate at speed 320.

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. Default: 0.
Y	number	No	Expression or literal value. Default: 0.
Speed	number	No	World Objects use meters per second. Screen UI Objects use logical pixels per second, even with a World target. Accepts a number, Variable, Global or expression. Default: 3.75.

Navigate To Point

Walks this instance to a point along a route around walls, solid tiles and fixed solid Objects. It steers by velocity, so collisions still apply. Runs Navigation Arrived on arrival and Navigation Blocked when there is no route or the walk keeps getting stuck. Works in 2D and 3D Scenes.

Reference key: navigateTo.

Editor category: Movement and Physics > Navigation.

Example: When the floor is clicked: Navigate To Point at [$click_x], [$click_y].

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. Default: 0.
Y	number	No	Expression or literal value. Default: 0.
Speed	number	Yes	Cruising speed along the route, slowing near arrival. World Objects use meters per second; Screen UI Objects use logical pixels per second. Default: 3.75.
Stop Distance	number	Yes	Arrival threshold measured from the Object center to the resolved point. World Objects use meters; Screen UI Objects use logical pixels. 0 uses the default arrival threshold. Default: 0.
Avoid Others	boolean	Yes	Keep apart from other navigating instances instead of piling up. Default: true.

Pause Navigation

Lets the game own this instance’s velocity for a moment, such as for a knockback or a dash, then resumes the same walk. Without it, the walk steers over the knockback on its next step.

Reference key: pauseNavigation.

Editor category: Movement and Physics > Navigation.

Example: When hit: Set Velocity away from the blow, then Pause Navigation 0.2.

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

Parameter	Type	Optional	Details
Seconds	number	No	How long the walk lets go of the velocity before resuming. Default: 0.3.

Raycast

Casts one invisible straight line and publishes one typed result record with Vec3 position and normal values. Later expressions can read its fields directly; use Change Variable only to retain a copy.

Reference key: raycast.

Editor category: Movement and Physics > Physics Queries.

Example: A security laser Raycasts toward Player, then compares raycastResult.hit == true and raycastResult.object == “Player”.

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

Parameter	Type	Optional	Details
Angle (deg)	number	Yes	Direction to cast, in degrees — 0 aims right and 90 aims up. Ignored when Toward Object is set. Default: 0. Shown when Toward Object is blank.
Toward Object	thing:object	Yes	Aim at the nearest instance of this object instead of Angle. The aimed object can itself be hit when the filter allows it.
Max Distance (m)	number	Yes	How far the ray reaches, in meters. Blank = to the scene edge.
Hit What	enum	Yes	What the ray reacts to. ‘solid’ = solid objects, solid tiles and the 3D world (blocks, props, terrain, floor); ‘any object’ = every object with a collider, tiles ignored; ‘chosen object’ = only the Chosen Object below. Choices: solid, any object, chosen object. Default: “solid”.
Chosen Object	thing:object	Yes	With Hit What = ‘chosen object’: the ray only reacts to instances of this object (blank = any object). Shown when Hit What is chosen object.
Pitch (deg, 3D)	number	Yes	3D Scenes only: tilt the ray up (+) or down (-) in degrees. 2D Scenes ignore it.

Results

Field	Type	Description
hit	boolean
object	thing:object
position	vec3
position.x	number
position.y	number
position.z	number
distance	number
kind	enum
normal	vec3
normal.x	number
normal.y	number
normal.z	number

Reverse Velocity

Reverses horizontal velocity, vertical velocity, or both while preserving speed on each selected axis.

Reference key: reverseVelocity.

Editor category: Movement and Physics > Motion.

Example: In Collision, reverse Horizontal velocity when a ball hits a side wall.

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

Parameter	Type	Optional	Details
Axis	enum	No	Choose one of the listed options. Choices: horizontal, vertical, both. Default: “horizontal”.

Set Bounciness

Changes impact bounciness and keeps it through body reattachment. Surface grip is a separate Set Friction Atomic.

Reference key: setBounciness.

Editor category: Movement and Physics > Physics Body.

Example: Set Bounciness to 1 for a rubber ball.

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

Parameter	Type	Optional	Details
Value	number	Yes	Bounciness blank = 0.8; Friction (Grip) blank = 0.6. Zero grip makes ice; bounciness 1 reflects at full speed.

Set Direction

Turns the current velocity without changing its speed. The direction accepts numbers, variables, globals, and expressions.

Reference key: setDirection.

Editor category: Movement and Physics > Motion.

Example: In Step, point this instance toward a target angle.

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

Parameter	Type	Optional	Details
Direction (deg)	number	No	Expression or literal value.

Set Drag (Slow Down)

Slows the object’s own movement over time, like air resistance — no contact with anything needed. (This action was previously listed as “Set Friction”.) For surface grip where two bodies rub, use Set Friction (Grip) on the Physics tab or the object’s Friction field.

Reference key: setFriction.

Editor category: Movement and Physics > Movement Forces.

Example: In Create, Set Drag 3 so a flicked coin glides to a stop instead of sliding forever.

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

Parameter	Type	Optional	Details
Amount	number	No	How strongly the object slows itself — 0 coasts forever, higher numbers stop it sooner.

Set Friction (Grip)

Changes the object’s physics material grip while the game runs — how strongly it resists sliding along whatever it touches (the Physics panel’s Friction field). Make a floor icy for a winter level, or a crate sticky so it stops where it lands. Works in every engine; under Myth Rigid Body grip also drives rolling and tumbling.

Reference key: setSurfaceFriction.

Editor category: Movement and Physics > Physics Body.

Example: On Custom Event [freeze], set Friction (Grip) to 0 on Floor. Restore the previous grip value to end the ice effect.

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

Parameter	Type	Optional	Details
Grip (0–1)	number	No	0 = ice (no grip at all), around 0.6 feels like wood, 1 = rubber on concrete. A contact uses both sides — if EITHER surface is ice, nothing grips. Default: 0.6.

Set Gravity

Sets gravity for the target or game.

Reference key: setGravity.

Editor category: Movement and Physics > Movement Forces.

Example: In Create, set gravity to pull platformer objects downward.

Parameter	Type	Optional	Details
Amount	number	No	Number value; decimals are allowed.
Direction (deg)	number	No	0 pulls right, 90 up, 180 left, and 270 down.

Set Joint Motor

Powers existing pin joints by optional name. Joint limits and detaching are separate atomic actions.

Reference key: controlJoint.

Editor category: Movement and Physics > Physics Joints.

Example: Set the wheel motor to 360 degrees per second.

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

Parameter	Type	Optional	Details
Joint Name	text	Yes	A named joint to control. Blank controls every matching joint on this object.
Spin (deg/sec)	number	No	The turning speed a pin motor aims for. 0 acts as a brake. Default: 180.
Strength (max torque)	number	Yes	Maximum twist the motor may spend before it stalls. Default: 97.65625.

Set Speed

Changes the current velocity magnitude without changing its direction. The speed accepts numbers, variables, globals, and expressions.

Reference key: setSpeed.

Editor category: Movement and Physics > Motion.

Example: In Create, give a projectile a fixed speed.

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

Parameter	Type	Optional	Details
Speed	number	No	Expression or literal value. Default: 0.

Set Spin

Sets rotation speed in degrees per second. A Sprite without a Collider rotates visually. For an Object with a Collider, turn on Allow rotation in Physics. Under Myth physics models, its collision shape rotates with the body. Set Spin Drag when the rotation should slow over time.

Reference key: setAngularVelocity.

Editor category: Movement and Physics > Physics Forces.

Example: In Create, Set Spin 90 so the collectible gem slowly rotates; Set Spin 0 on click to stop it.

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

Parameter	Type	Optional	Details
Spin (deg/sec)	number	No	Turning speed in degrees per second — 360 is one full turn each second. Positive spins counter-clockwise; 0 stops the spin. Default: 180.

Set Velocity

Sets the exact horizontal velocity, vertical velocity, or both. A blank axis preserves its current speed.

Reference key: setVelocity.

Editor category: Movement and Physics > Motion.

Example: Set only X for horizontal movement, only Y for a jump, or both axes for complete motion.

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

Parameter	Type	Optional	Details
X Velocity	number	Yes	Blank keeps the current horizontal velocity. Accepts numbers, variables, globals, and expressions. World-space velocity uses metres per second. Zero stops this axis; blank preserves it.
Y Velocity	number	Yes	Positive moves up; negative moves down. Blank keeps the current vertical velocity. Accepts numbers, variables, globals, and expressions. World-space velocity uses metres per second. Zero stops this axis; blank preserves it.

Stop Navigation

Stops this instance’s Navigate To Point or Chase Object walk where it stands and clears its velocity.

Reference key: stopNavigation.

Editor category: Movement and Physics > Navigation.

Example: On Navigation Arrived: Stop Navigation.

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