motion — Luau Binding
The require("motion") API: compile a path string into an op list, play it on a target in the background, stop it, and ask whether it is still running. The programmatic surface of the motion subsystem — every AntOS tool, app, or command drives motion through here, and AntBASIC's DRAW / MOVE are wrappers over it. Every function is [antos].
Status: design. Not built yet. Signatures are the intended surface, settled against the motion model; expect refinement during implementation.
local motion = require("motion")
Paths and targets
| Call |
Returns |
Does |
motion.compile(path) |
oplist, err |
parse and validate a path string into a reusable op list; a bad path returns err = { col, message } — the single parse point |
motion.target(kind, id?) |
target |
a target handle — "turtle", "sprite" (with id), or a table exposing x / y / heading for a custom target |
Play, stop, query
| Call |
Returns |
Does |
motion.play(target, path_or_oplist, opts?) |
ok, err |
start a sequence on target, in the background — returns at once. opts is { loop = false, speed = 1.0, scale = 1.0, rotation = 0, easing = "linear" } — speed a float (0.5 half, 2 double, "instant" = one tick), scale / rotation applied to this playback (playback parameters), and easing ("linear" / "ease-in" / "ease-out" / cubic-bezier(…)) reshaping progress→time (curves and easing). Replaces any sequence already running on target. A raw string is compiled inline (its err surfaces here); an op list from compile plays directly |
motion.stop(target) |
ok |
cancel the target's sequence |
motion.running(target) |
bool |
whether a sequence is still playing on target |
motion.wait(target) |
— |
block until the target's sequence completes — for callers that want to sequence rather than fire-and-forget |
-- compile once, play many; await completion
local motion = require("motion")
local sq = assert(motion.compile("REPEAT 4 (FD 100 RT 90)"))
local t = motion.target("turtle")
motion.play(t, sq) -- draws in the background
motion.wait(t) -- ...block until done
motion.play(motion.target("sprite", 3), sq, { loop = true, speed = 8 }) -- sprite loops forever
Transforms
| Call |
Returns |
Does |
motion.transform(target, xf) |
ok |
set the target's master transform — xf = { x, y, scale, rot, speed } — composed over any sequence playing on it, live and mid-sequence; see per-target transforms. Omitted fields keep their current value; motion.transform(target) with no table reads the current one back |
Introspection
| Call |
Returns |
Does |
motion.check(path) |
status, err |
validate a path without compiling a playable list — "ok" / "invalid" (with col), for an editor or importer; mirrors basic.check |
motion.verbs() |
list |
the path verbs and their syntax, for HELP / completion — reads the same grammar compile uses |
Where to go next
- The subsystem, path language, and executor roadmap → motion
- The BASIC front door (
DRAW / MOVE) → AntBASIC
- The
basic binding this parallels in house style → luau_basic