API reference

aster_blueprint::motion

Pre-1.0: signatures are not frozen. Generated from rustdoc JSON of the compiled crate; rustdoc JSON format version 60. Only public items are listed.

Caller-clock motion capability for the blueprint graph runtime.

This module owns only time-parameter evaluation and an explicit, caller-driven playback state machine. It never reads a clock, spawns a thread, registers a timer, or schedules a tick: every advance is supplied by the caller as a validated [Seconds] reading, so evaluated results are deterministic for a given sequence of caller clock readings.

motion depends only on std; it does not import model or compiler types. The runtime can therefore call this seam without a cycle:

  • [Curve::evaluate] maps a normalized progress in [0, 1] to an eased scalar for a single segment.
  • [KeyframeClip::seek] maps an absolute [Seconds] to a keyframed value.

Playback is explicit: [Motion] exposes start / pause / resume / seek / reverse / cancel commands that each return a raw [CommandReport] (accepted, refusal reason, and the resulting state), plus a tick that consumes a caller clock reading. needs_tick is true only while the phase is [Phase::Playing]; a finished or paused motion never asks for an idle frame.

A spring is a stateful simulation with persistent velocity and its own seek/reset semantics. A stateless easing curve does not solve it, so this module does not pretend otherwise: [Curve::spring] returns [MotionError::SpringDeferred]. Implementing springs requires a bounded explicit integrator plus an honest "seek resets velocity" policy, which is not part of this work.

Structs

structaster_blueprint::motion::CommandReport

pub struct CommandReport { /* see fields */ }

Raw result of a command: what was asked, whether it was accepted, the refusal reason if not, whether it interrupted active playback, and the resulting state.

Public fields

fieldtype
commandCommand
acceptedbool
refusalOption<MotionError>
interruptionbool
stateMotionState

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::motion::Keyframe

pub struct Keyframe { /* see fields */ }

One authored keyframe in a [KeyframeClip].

Public fields

fieldtype
timeSecondsAbsolute time from the start of the clip. Non-negative and finite.
valuef64The value sampled at this time. Finite and bounded by [VALUE_LIMIT].
easingCurveEasing used for the segment from this keyframe to the next. Ignored on the final keyframe.

Methods

  • fn new(time: Seconds, value: f64, easing: Curve) -> Result<Self, MotionError> — Build a keyframe.

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::motion::KeyframeClip

pub struct KeyframeClip { /* see fields */ }

An immutable, strictly increasing keyframe sequence with a derived duration.

Methods

  • fn new(keyframes: Vec<Keyframe>, limits: MotionLimits) -> Result<Self, MotionError> — Build a clip from keyframes.
  • fn duration(&self) -> Seconds
  • fn keyframes(&self) -> &[Keyframe]
  • fn len(&self) -> usize
  • fn is_empty(&self) -> bool
  • fn seek(&self, at: Seconds) -> f64 — Sample the clip at at, clamped into [0, duration].

Trait implementations: Clone, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::motion::Motion

pub struct Motion { /* see fields */ }

Caller-clock playback over an immutable [KeyframeClip].

No thread, timer, global clock or renderer hook: the caller owns time and supplies each reading to [Motion::tick]. The same sequence of caller readings therefore yields the same sequence of states.

Methods

  • fn new(clip: KeyframeClip, limits: MotionLimits, loop_mode: LoopMode, policy: InterruptionPolicy) -> Result<Self, MotionError> — Build a motion. Refuses loop counts that are zero, over the limit, or attached to a zero-duration clip (an unbounded repeat).
  • fn clip(&self) -> &KeyframeClip
  • fn loop_mode(&self) -> LoopMode
  • fn policy(&self) -> InterruptionPolicy
  • fn phase(&self) -> Phase
  • fn direction(&self) -> Direction
  • fn position(&self) -> Seconds — Current playhead, always within [0, duration].
  • fn value(&self) -> f64 — Value sampled at the current playhead.
  • fn is_active(&self) -> bool — Playing or paused (not idle, not finished).
  • fn needs_tick(&self) -> bool — Whether the caller should schedule another tick. True only while playing; false when idle, paused or finished.
  • fn state(&self) -> MotionState
  • fn start(&mut self) -> CommandReport — Begin playback from the start.
  • fn pause(&mut self) -> CommandReport — Pause active playback, keeping the position. No-op refusal otherwise.
  • fn resume(&mut self) -> CommandReport — Resume paused playback. The next tick re-establishes its own baseline, so no time is charged for the paused interval.
  • fn seek(&mut self, at: Seconds) -> CommandReport — Move the playhead to at (clamped into [0, duration]).
  • fn reverse(&mut self) -> CommandReport — Flip the playback direction, keeping the position.
  • fn cancel(&mut self) -> CommandReport — Cancel playback and return to [Phase::Idle] at position zero.
  • fn tick(&mut self, now: Seconds) -> Result<TickOutcome, MotionError> — Advance by a caller clock reading.
  • fn tick_with<E>(&mut self, now: Seconds, callback: impl FnOnce(&TickOutcome) -> Result<(), E>) -> Result<TickOutcome, TickCommitError<E>> — Advance by a caller clock reading and commit the result through a callback.

structaster_blueprint::motion::MotionLimits

pub struct MotionLimits { /* see fields */ }

Bounds on clip size and playback looping. Keeps all work finite.

Public fields

fieldtype
max_keyframesusize
max_loopsu32

Trait implementations: Clone, Copy, Debug, Default, Eq, PartialEq, StructuralPartialEq

structaster_blueprint::motion::MotionState

pub struct MotionState { /* see fields */ }

Immutable snapshot of a motion after a command or tick.

Public fields

fieldtype
phasePhase
directionDirection
positionSeconds
valuef64
activebool
needs_tickbool
completed_loopsu32

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

structaster_blueprint::motion::Seconds

pub struct Seconds(..)

A validated finite, non-negative duration or clock reading in seconds.

The only way to build a Seconds is [Seconds::new], which refuses NaN, infinities and negatives. All time that enters the state machine therefore passes through this gate exactly once.

Methods

  • const ZERO: Seconds — The only valid zero duration.
  • fn new(value: f64) -> Result<Self, MotionError> — Validate value as a finite, non-negative number of seconds.
  • fn get(self) -> f64 — The raw value. Finite and non-negative by construction.

Trait implementations: Clone, Copy, Debug, Display, PartialEq, PartialOrd, StructuralPartialEq

structaster_blueprint::motion::TickOutcome

pub struct TickOutcome { /* see fields */ }

Raw result of a caller-clock tick.

Public fields

fieldtype
advancedboolThe playhead actually moved this tick.
finishedboolThe motion reached its terminal edge and is now [Phase::Finished].
loops_completedu32Loop boundaries consumed so far.
stateMotionState

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

Enums

enumaster_blueprint::motion::Command

pub enum Command { Start, Pause, Resume, Seek, Reverse, Cancel }

A playback command, carried on a [CommandReport].

Variants

  • Start
  • Pause
  • Resume
  • Seek
  • Reverse
  • Cancel

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::Curve

pub enum Curve { Linear, SmoothStep, CubicBezier }

A normalized easing curve over [0, 1].

Every curve is stateless and exact at the endpoints: evaluate(0.0) == 0.0 and evaluate(1.0) == 1.0.

Methods

  • fn cubic_bezier(x1: f64, y1: f64, x2: f64, y2: f64) -> Result<Self, MotionError> — Build a cubic bezier, refusing non-finite controls, x outside [0, 1], or y magnitude beyond [CONTROL_LIMIT].
  • fn spring(_stiffness: f64, _damping: f64) -> Result<Self, MotionError> — Springs are explicitly deferred, never silently faked.
  • fn validate(self) -> Result<(), MotionError> — Check that this curve obeys the documented bounds.
  • fn evaluate(self, t: f64) -> Result<f64, MotionError> — Evaluate the curve at normalized progress t.

Variants

  • Linear — Identity easing: f(t) = t.
  • SmoothStep — Smoothstep: f(t) = t^2 (3 - 2t).
  • CubicBezier — Cubic bezier with control points P0 = (0, 0), P1 = (x1, y1), P2 = (x2, y2), P3 = (1, 1).

Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::Direction

pub enum Direction { Forward, Reverse }

Playback direction.

Variants

  • Forward
  • Reverse

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::InterruptionPolicy

pub enum InterruptionPolicy { Interrupt, Refuse }

How the motion treats a start while it is already active.

Variants

  • Interrupt — An active motion is reset to the beginning and restarted.
  • Refuse — An active motion refuses the command; the caller must pause or cancel.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::LoopMode

pub enum LoopMode { Once, Repeat, PingPong }

Loop policy. Counts are bounded by [MotionLimits::max_loops].

Variants

  • Once — Play once and finish.
  • Repeat — Play times forward passes and finish.
  • PingPong — Bounce times passes (reversing at each edge) and finish.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::MotionError

pub enum MotionError { InvalidSeconds, NonFinite, InvalidKeyframeValue, NonIncreasingKeyframes, EmptyClip, TooManyKeyframes, TooManyLoops, InvalidLoopCount, ZeroDurationRepeat, InvalidCurve, SpringDeferred, AlreadyActive, NotActive, NotPlaying, NotPaused, NotReversible, ClockWentBackwards, ArithmeticOverflow, LoopBudgetExceeded }

Refusals from motion construction, evaluation and playback commands.

Variants

  • InvalidSeconds — A Seconds was non-finite or negative.
  • NonFinite — A curve parameter was non-finite.
  • InvalidKeyframeValue — A keyframe value was non-finite or beyond [VALUE_LIMIT].
  • NonIncreasingKeyframes — Keyframe timestamps were not strictly increasing (covers duplicates).
  • EmptyClip — A clip had no keyframes.
  • TooManyKeyframes — More keyframes than the configured limit.
  • TooManyLoops — A loop count exceeded the configured limit.
  • InvalidLoopCount — A loop count was zero, which is meaningless.
  • ZeroDurationRepeat — A repeating/looping clip had zero duration; that repeats forever.
  • InvalidCurve — A cubic-bezier control was out of the accepted range.
  • SpringDeferred — Springs are a deferred stateful simulation, not a stateless curve.
  • AlreadyActive — A command required the motion to be idle, but it was active.
  • NotActive — A seek required the motion to be playing or paused.
  • NotPlaying — A command required active playback, but the motion was not playing.
  • NotPaused — A command required a paused motion, but it was not paused.
  • NotReversible — A reverse command was issued while the motion was neither playing nor paused.
  • ClockWentBackwards — The caller clock moved backwards between two ticks.
  • ArithmeticOverflow — An arithmetic step would have left the finite range.
  • LoopBudgetExceeded — A single tick would traverse more loop boundaries than allowed.

Trait implementations: Clone, Copy, Debug, Display, Eq, Error, From<MotionError>, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::Phase

pub enum Phase { Idle, Playing, Paused, Finished }

Explicit playback phase.

Variants

  • Idle — Never started, or reset by cancel.
  • Playing — Advancing under caller ticks. The only phase that needs a tick.
  • Paused — Held at the current position; no tick needed.
  • Finished — Reached the terminal edge; no tick needed.

Trait implementations: Clone, Copy, Debug, Eq, PartialEq, StructuralPartialEq

enumaster_blueprint::motion::TickCommitError

pub enum TickCommitError<E> { Motion, Callback }

Refusal from [Motion::tick_with].

Either the simulated [Motion::tick] was refused, or the tick succeeded but the caller callback refused. In both cases the motion is left exactly as it was before the call: the commit is all-or-nothing.

Variants

  • Motion — The underlying [Motion::tick] was refused; the motion is unchanged.
  • Callback — The tick succeeded but the callback returned Err; the motion is unchanged.

Trait implementations: Clone, Copy, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

Constants

constaster_blueprint::motion::BEZIER_ITERATIONS

pub const BEZIER_ITERATIONS: u32

Fixed bisection budget for inverting a monotonic cubic-bezier x axis.

constaster_blueprint::motion::CONTROL_LIMIT

pub const CONTROL_LIMIT: f64

Largest magnitude accepted for a cubic-bezier y control point.

x controls are restricted to [0, 1] to keep x(t) monotonic; y controls may overshoot but stay bounded so evaluation cannot overflow.

constaster_blueprint::motion::HARD_ITERATION_LIMIT

pub const HARD_ITERATION_LIMIT: u64

Independent hard ceiling on the boundary crossings a single tick may consume.

A motion's own loop limit ([MotionLimits::max_loops]) may be as large as u32::MAX, which would let one caller step spin for billions of iterations. This constant is the ceiling that keeps a tick's work bounded regardless of the configured loop limit: a step that would cross more boundaries is refused with [MotionError::LoopBudgetExceeded] and rolled back. It is deliberately far larger than the default max_loops (65_536), so ordinary clips never reach it.

constaster_blueprint::motion::VALUE_LIMIT

pub const VALUE_LIMIT: f64

Largest magnitude accepted for a keyframed scalar value.

This keeps interpolation arithmetic finite: with bounded easing controls the interpolation of two bounded values cannot overflow f64.