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
| field | type | |
|---|---|---|
command | Command | |
accepted | bool | |
refusal | Option<MotionError> | |
interruption | bool | |
state | MotionState |
Trait implementations: Clone, Copy, Debug, PartialEq, StructuralPartialEq
structaster_blueprint::motion::Keyframe
pub struct Keyframe { /* see fields */ }One authored keyframe in a [KeyframeClip].
Public fields
| field | type | |
|---|---|---|
time | Seconds | Absolute time from the start of the clip. Non-negative and finite. |
value | f64 | The value sampled at this time. Finite and bounded by [VALUE_LIMIT]. |
easing | Curve | Easing 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 fromkeyframes.fn duration(&self) -> Secondsfn keyframes(&self) -> &[Keyframe]fn len(&self) -> usizefn is_empty(&self) -> boolfn seek(&self, at: Seconds) -> f64— Sample the clip atat, 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) -> &KeyframeClipfn loop_mode(&self) -> LoopModefn policy(&self) -> InterruptionPolicyfn phase(&self) -> Phasefn direction(&self) -> Directionfn 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) -> MotionStatefn 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 toat(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
| field | type | |
|---|---|---|
max_keyframes | usize | |
max_loops | u32 |
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
| field | type | |
|---|---|---|
phase | Phase | |
direction | Direction | |
position | Seconds | |
value | f64 | |
active | bool | |
needs_tick | bool | |
completed_loops | u32 |
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>— Validatevalueas 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
| field | type | |
|---|---|---|
advanced | bool | The playhead actually moved this tick. |
finished | bool | The motion reached its terminal edge and is now [Phase::Finished]. |
loops_completed | u32 | Loop boundaries consumed so far. |
state | MotionState |
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
StartPauseResumeSeekReverseCancel
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,xoutside[0, 1], orymagnitude 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 progresst.
Variants
Linear— Identity easing:f(t) = t.SmoothStep— Smoothstep:f(t) = t^2 (3 - 2t).CubicBezier— Cubic bezier with control pointsP0 = (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
ForwardReverse
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— Playtimesforward passes and finish.PingPong— Bouncetimespasses (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— ASecondswas 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 bycancel.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 returnedErr; the motion is unchanged.
Trait implementations: Clone, Copy, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq
Constants
constaster_blueprint::motion::BEZIER_ITERATIONS
pub const BEZIER_ITERATIONS: u32Fixed bisection budget for inverting a monotonic cubic-bezier x axis.
constaster_blueprint::motion::CONTROL_LIMIT
pub const CONTROL_LIMIT: f64Largest 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: u64Independent 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: f64Largest 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.