Motion.sway
luastra/motionMotion.sway(options: any?): MotionMap
Returns a repeating rotation MotionMap that alternates around the resting angle, producing a gentle rocking effect. Iteration and duration options control whether it settles or continues.
Before you use it
Add luastra/motion to this module's dependencies in luastra.json, then import it with require("luastra/motion"). Motion itself needs no capability; a visible result requires ui.render and a component that accepts the returned descriptor through its motion field.
How it fits
The function returns immutable motion data synchronously. Assign a preset MotionMap directly, or place Tween/Sequence values under supported motion channel names; the host animates without rerunning app.render on every frame.
When to use it
Use Motion.sway for occasional ambient motion on a decorative or game-like object, such as a hidden card. Keep the angle small, stop it when the object is inactive, and rely on host reduced-motion handling.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| options | any? | Optional angle, duration, and iteration settings for the rotation preset. |
| options.angleDeg | number (0..45]? | Optional peak rotation in degrees; defaults to 2. |
| options.durationMs | number (0..60000)? | Duration of each one-way movement; defaults to 180 ms. |
| options.pauseMs | number (0..60000)? | Delay before each continuous sway cycle; defaults to 2400 ms. |
| options.easing | "linear" | "easeOutCubic" | "easeInOutCubic"? | Optional interpolation curve; defaults to "easeInOutCubic". |
Returns
MotionMap — a complete property-to-motion map that can be assigned directly to a supported component motion field.
What happens next
A descriptor or MotionMap ready to attach to a supported UI node.
Failures and fixes
Unknown options, invalid bounds, or unsupported channels fail validation. Motion must not drive application logic; use Timer for state changes, and rely on the host to present the final state when reduced motion is enabled.
Availability
Public-source alpha API in 0.5.0-alpha; presentation follows host and reduced-motion policy.
Focused example
local Motion = require("luastra/motion")
local motion = Motion.sway { angleDeg = 2, durationMs = 2400, iterations = 0 }