API reference
Every public type and member, generated from the comments in the source. Members marked Lite are in both tiers; everything else is Pro.
All types are in the Cascade namespace. Durations are in seconds.
Start an animation
VisualElementAnimationExtensions class Lite
Entry points for the fluent API. These are the only symbols most users touch.element.Animate()… returns a TweenSequence you can chain and keep as a handle.
static TweenSequence Animate(this VisualElement element) Lite Begin a fluent animation on this element. The returned
TweenSequence is both the builder and the control handle. Dispatch is deferred to the next scheduler tick.static void StopAnimations(this VisualElement element) Lite Cancel every Cascade animation currently running on this element.
static bool StopAnimations(this VisualElement element, MotionChannel channel) Lite Stop animating ONE property of this element, e.g.
el.StopAnimations(MotionChannel.Opacity) freezes a running fade at its current value while a simultaneous move keeps going. O(1) via the engine's channel-claim registry. Only the cancelled tween is affected: it goes inert but keeps its place in the sequence timeline, so siblings keep running, .Then() steps still start at their authored time, and the sequence's OnComplete still fires (at the authored time) when something in it finishes naturally, unless the cancelled channel was the sequence's only content (then it's a cancel: no OnComplete, per the engine's Cancel ≠ complete rule). Scope caveats: this stops the tween currently animating that channel, a tween still in its .Delay(), queued in a later .Then() step, or dispatched this frame has no channel claim yet, is not targetable (returns false), and will play at its authored time as a separate animation. Closure-mode verbs (SlideIn/MoveTo/colors) have no channel identity, use StopAnimations for those.Returns: True when a live animation on that channel was stopped.
static StaggerBuilder AnimateEach(this IEnumerable<VisualElement> elements) Begin a staggered animation across a collection of elements: The same chain plays on every element, with element
i offset by i * stagger.static TweenSequence AnimateAll( this IEnumerable<VisualElement> elements, Func<VisualElement, float> captureFrom, float to, Action<VisualElement, float> apply, float duration, float stagger, EaseFunction ease = null, MotionChannel channel = MotionChannel.Custom) Coalesced staggered animation: one tween samples a shared eased curve and fans the value across every element (each offset by
i * stagger), instead of one independent tween per element. At 500-element scale that's ONE runner slot + one resolvedStyle read per element (captured once at start) rather than N tweens each re-stepping, far less dirty-flag and bookkeeping churn. Returns the group handle (pause/cancel the whole stagger at once). captureFrom reads each element's start value (captured at that element's own start, not the group's); apply writes the interpolated value; both run per element. The element collection is snapshotted at call time. For the common case use StaggerFade. The group lasts duration + (count-1) * stagger, not duration. A fixed per-element stagger therefore scales with the collection, see Stagger for TotalDuration (to schedule after a group) and StepForSpan (to pin its length). The group is ONE tween on the shared host, so cancelling it needs this handle; StopAnimations() on a member element will not stop it.Returns: The group handle, or null when elements is null/empty (no-op).
static TweenSequence AnimateAll( this IEnumerable<VisualElement> elements, Func<VisualElement, Color> captureFrom, Color to, Action<VisualElement, Color> apply, float duration, float stagger, EaseFunction ease = null, MotionChannel channel = MotionChannel.Custom) Coalesced staggered colour sweep, the same machinery as the float
AnimateAll, but capturing and interpolating a Color per element. This overload exists because the obvious way to write a colour sweep with the float version is wrong in a way that looks right. Lerping from resolvedStyle.backgroundColor inside the apply callback reads the value the previous frame wrote, so each frame blends a shorter remaining distance and the colour converges early instead of travelling the curve, it merely looks like a soft ease, which is why it ships. Here the start colour is captured once, at each element's own start, exactly like every other verb.Returns: The group handle, keep it if anything else will later write these elements, because a coalesced group is ONE tween hosted on the shared parent and StopAnimations() on an individual element does not reach it.
static TweenSequence StaggerFade(this IEnumerable<VisualElement> elements, float to, float duration, float stagger, EaseFunction ease = null) Coalesced staggered opacity fade across
elements, the cascade list entrance. One tween for the whole group (see AnimateAll).The animation handle
TweenSequence class Lite
What Animate() returns: you chain verbs on it to build the animation, and keep it to control the animation (Pause, Resume, Cancel, await). Verbs add to the current step and run together; Then() starts the next step. The animation starts on the element's next frame, so everything you chain in the same line applies.
TweenSequence Fade(float to, float duration) Lite Animate
opacity to to over duration seconds.TweenSequence FadeTo(float to, float duration) Lite Alias of
Fade, matches the FadeTo name used by the Interaction and Variant APIs (and the JSON "Fade" verb's C# alias), so converting between them is mechanical.TweenSequence MoveX(float to, float duration) Lite Animate the X component of
style.translate (pixels).TweenSequence MoveY(float to, float duration) Lite Animate the Y component of
style.translate (pixels).TweenSequence SlideIn(Edge edge, float duration, float distance = 48f) Lite Slide the element in from a screen
edge: it starts offset by distance px in that direction and animates style.translate to 0. Unlike the other verbs this uses an explicit "from" (the offset), and pre-positions the element immediately so there is no first-frame flash at its layout position. Pair with Fade for the classic cascading-menu entrance.TweenSequence ScaleTo(float to, float duration) Lite Animate uniform
style.scale to to.TweenSequence Scale(float to, float duration) Lite Alias of
ScaleTo, matches the JSON "Scale" verb name, so an AI converting JSON to fluent C# can use the same name instead of knowing the ScaleTo rename.TweenSequence Rotate(float toDegrees, float duration) Lite Animate Z rotation (degrees) via
style.rotate.TweenSequence MoveTo(Vector2 to, float duration) Lite Animate
style.translate to a target offset (pixels) on both axes at once.TweenSequence Nudge(float x, float y, float duration) Lite Displace the element by
x, y pixels and bring it straight back, the "your input was rejected" bump, a damage shake, an error wobble. Additive, and that is the whole point. A nudge does not claim TranslateX/Y, so it composes with whatever is already positioning the element instead of superseding it. A piece being animated toward a grid cell can bump against a wall without its follow animation being cancelled, which is impossible with MoveX, because a second value-mode tween on an owned channel cancels the first outright. Self-restoring: the offset follows a half-sine, so it is guaranteed to be back at zero when the tween ends, and it is released if the sequence is cancelled part-way.TweenSequence NudgeX(float x, float duration) Lite Horizontal-only
Nudge, the sideways bump.TweenSequence NudgeY(float y, float duration) Lite Vertical-only
Nudge, the impact drop.TweenSequence BackgroundColor(Color to, float duration) Lite Animate
style.backgroundColor.TweenSequence Value(float from, float to, float duration, Action<float> onValue) Lite Animate a plain number from
from to to, handing each frame's value to onValue. The one verb that writes nothing itself, it exists for everything a game HUD needs that is not a style property: a score counter rolling up, a health bar's backing value, a countdown, an audio duck. Composes with every modifier, so a rolling counter can spring: Interruption. A value tween has no style channel to own, so consecutive ones stack rather than supersede, two rolls at once will fight over the label. When the value can change again mid-roll (a score usually can), keep the handle and Cancel it before starting the next, and pass the currently-displayed value as from.onValue- Called once per frame with the interpolated value. Must tolerate being called a single time at
fromand then cancelled.
TweenSequence TextColor(Color to, float duration) Lite Animate
style.color (text/tint color).TweenSequence Width(float toPixels, float duration) Lite Animate
style.width (pixels). Layout-affecting: triggers a reflow each frame, costlier than transform verbs. Prefer ScaleTo where a visual size change suffices.TweenSequence Height(float toPixels, float duration) Lite Animate
style.height (pixels). Layout-affecting, see Width.TweenSequence Size(float toWidth, float toHeight, float duration) Lite Animate both
width and height (pixels). Layout-affecting, see Width.TweenSequence Top(float toPixels, float duration) Lite Animate
style.top (pixels). Layout-affecting, see Width.TweenSequence Left(float toPixels, float duration) Lite Animate
style.left (pixels). Layout-affecting, see Width.TweenSequence From(float value) Lite Start the most recent tween from
value instead of from wherever the element currently is. This is how you write an entrance. Verbs animate to a value and read from the live one at start, so Fade(1f, 0.3f) on an element that is already opaque is a legitimate no-op, correct, and not what "fade in" means. Naming the start makes the intent explicit: The start value is written immediately, at build time, so there is no frame of the old value before the animation's first write. Skipped when the current motion mode would snap rather than play, where priming would itself be the flash. Value verbs only (Fade/Scale/MoveX/MoveY/Rotate/…); ignored by SlideIn, which already positions its own start, and by the vector and colour verbs. Two consequences of writing the value early. Cancel before the sequence dispatches leaves the element AT the start value, cancelling does not undo the prime, because Cancel leaves things where they are by design. And if another tween is already animating that channel it keeps writing until this one supersedes it, so the no-flash guarantee holds on an idle channel, not on a contested one.TweenSequence Ease(EaseFunction ease) Lite
TweenSequence Spring(SpringPreset preset) Drive the most recent tween with a named spring instead of easing+duration. The duration you passed to the verb is discarded. A spring settles on its own physics, so
Fade(1f, 0.4f).Spring(SpringPreset.Gentle) does not take 0.4s, it takes however long that spring takes. Pass 0f to make that obvious to the next reader.TweenSequence Spring(SpringConfig config) Drive the most recent tween with a custom spring. As with the preset overload, the verb's duration argument is discarded, the spring decides when it has settled.
TweenSequence WithResponse(float response, float bounce = 0f) Drive the most recent tween with a perceptual spring (
response = period in seconds, bounce = arrival character); full model on FromResponse. Named distinctly from Spring(...) so the literal call Spring(0) can't become ambiguous with the enum overload.TweenSequence Delay(float seconds) Lite Delay the most recent tween by
seconds before it starts.TweenSequence Loop(LoopMode mode, int count = 0) Lite Loop the most recent tween.
count ≤ 0 loops forever.TweenSequence OnUpdate(Action onUpdate) Lite Per-frame callback for the most recent tween.
TweenSequence Then() Lite Open a new sequential step. Tweens added after run once the current step finishes.
TweenSequence OnComplete(Action onComplete) Lite Callback fired when the whole sequence completes (not on cancel).
TweenSequence OnSettled(Action<bool> onSettled) Lite Fired when the sequence stops, whichever way it stopped.
true if it completed naturally, false if it was cancelled or superseded. Same verdict the awaitable returns. Prefer this to OnComplete for anything a user can see. Cancel is not Complete: starting a new value-mode tween on the same element and channel supersedes the prior sequence, and OnComplete then never runs. That is correct, but it means a selection highlight, an enabled state, or a "now it's safe to repaint" step hung off OnComplete simply will not happen if the user interacted during the animation. The symptom is a UI that looks broken intermittently, with no error.TweenSequence IgnoreReducedMotion() Lite Always animate this sequence even when
ReduceMotion is on (e.g. an essential transition that must still play).bool IsActive Lite True while the sequence is dispatched and still running.
void Pause() Lite Pause the sequence in place; resume later with
Resume.void Resume() Lite Resume a sequence paused with
Pause.void Cancel() Lite Stop immediately, leaving the target at its current values. No completion callback.
Awaitable<bool>.Awaiter GetAwaiter() Lite Makes the sequence directly awaitable.
bool completed = await element.Animate().Fade(1f, 0.3f); Resumes on the main thread when the animation ends. The result mirrors OnComplete exactly.true when the sequence finished (OnComplete fired), false when it was cancelled or superseded, cancellation never throws, and the continuation can branch on the result instead of mistaking an interruption for completion (Cancel ≠ complete). Await a sequence once. Detaching the element resolves the await as false whether it happens mid-flight or in the same frame the sequence was built. Note: like OnComplete, an animation on an element that is never attached to a panel never starts and so never resolves, there is no detach to observe; Cancel resolves it immediately.Awaitable<bool> AsAwaitable() Lite The sequence's end as an
Awaitable{T} (see GetAwaiter). Allocated lazily on first call; already-ended sequences resolve immediately.LoopMode enum Lite
How a finished tween repeats.
None Lite
Restart Lite
PingPong Lite
Edge enum Lite
Which screen edge a slide transition enters from / exits toward.
Left Lite
Right Lite
Top Lite
Bottom Lite
Easing
Ease class Lite
Standard easing curves. Mirrors the set Unity exposes via UIElements.Experimental.Easing but lives in our namespace so the public API never depends on an Experimental.* type.
static readonly EaseFunction Linear Lite
static readonly EaseFunction InSine Lite
static readonly EaseFunction OutSine Lite
static readonly EaseFunction InOutSine Lite
static readonly EaseFunction InQuad Lite
static readonly EaseFunction OutQuad Lite
static readonly EaseFunction InOutQuad Lite
static readonly EaseFunction InCubic Lite
static readonly EaseFunction OutCubic Lite
static readonly EaseFunction InOutCubic Lite
static readonly EaseFunction InQuart Lite
static readonly EaseFunction OutQuart Lite
static readonly EaseFunction InOutQuart Lite
static readonly EaseFunction InExpo Lite
static readonly EaseFunction OutExpo Lite
static readonly EaseFunction InOutExpo Lite
static readonly EaseFunction InCirc Lite
static readonly EaseFunction OutCirc Lite
static readonly EaseFunction InOutCirc Lite
static readonly EaseFunction InBack Lite
static readonly EaseFunction OutBack Lite
static readonly EaseFunction InOutBack Lite
static readonly EaseFunction InElastic Lite
static readonly EaseFunction OutElastic Lite
static readonly EaseFunction InOutElastic Lite
static readonly EaseFunction OutBounce Lite
static readonly EaseFunction InBounce Lite
static readonly EaseFunction InOutBounce Lite
static EaseFunction FromCurve(AnimationCurve curve) Lite Wraps a Unity
AnimationCurve as an EaseFunction.static EaseFunction From(EaseKind kind) Lite Resolve a serializable
EaseKind (used by inspector presets) to its function.EaseKind enum Lite
Serializable selector for an easing curve, lets inspector presets / the codeless workflow pick an easing in a dropdown (an EaseFunction delegate can't be serialized). Resolve with From.
Linear Lite
InSine Lite
OutSine Lite
InOutSine Lite
InQuad Lite
OutQuad Lite
InOutQuad Lite
InCubic Lite
OutCubic Lite
InOutCubic Lite
OutQuart Lite
OutExpo Lite
OutCirc Lite
InBack Lite
OutBack Lite
InOutBack Lite
OutElastic Lite
OutBounce Lite
Springs
SpringPreset enum Pro
Named, hand-tuned spring feels exposed in the fluent API and inspector.
GentleSnappyBouncySpringConfig struct Pro
Physical spring parameters. Springs are the headline capability USS transitions and experimental.animation cannot express.
float Stiffness Restoring force toward the target. Higher = faster/tighter.
float Damping Velocity-proportional resistance. Higher = less bounce.
float Mass Inertia. Higher = slower, heavier feel.
bool ClampOvershoot When true the spring never overshoots the target: progress is clamped at 1 and the spring settles there. Opt in for layout channels (Width/Height/Size/Top/Left), where an overshoot means the box bounces past its final size and reflows on the way back. Note: the clamp is a hard arrival guarantee, a large relay-seeded velocity that would cross the target on its first step pins there immediately instead of carrying momentum through.
SpringConfig(float stiffness, float damping, float mass = 1f)static SpringConfig From(SpringPreset preset)static SpringConfig FromResponse(float response, float bounce = 0f, float mass = 1f) The perceptual spring model (iOS / Framer Motion): describe the feel, not the physics.
response is the oscillation period in seconds, smaller = faster/snappier (0.15 = a quick control, 0.5 = a large panel). bounce is how springy the arrival is: 0 = smooth, no overshoot (critically damped); toward 1 = very bouncy; negative = overdamped (a flattened, viscous arrival). Maps analytically onto stiffness/damping.k = m·(2π/response)², c = (1−bounce)·2·√(k·m).SpringConfig WithClampOvershoot() Copy of this config with
ClampOvershoot enabled (fluent).Stagger
StaggerBuilder class Pro
The builder AnimateEach() returns: the same verbs as an animation, played on every element of a list, each starting Stagger(seconds) after the previous one.
StaggerBuilder Fade(float to, float duration)StaggerBuilder MoveX(float to, float duration)StaggerBuilder MoveY(float to, float duration)StaggerBuilder ScaleTo(float to, float duration)StaggerBuilder SlideIn(Edge edge, float duration, float distance = 48f)StaggerBuilder From(float value) Start the most recent verb from
value on every element, the staggered entrance idiom, and the reason most people reach for stagger in the first place. Every element primes at dispatch and then animates on its own offset, so a list cascades in from hidden rather than each item popping at full opacity. Without this the only way to write a staggered entrance was to set the inline style on every element by hand first, which is what the shipped sample had to do.StaggerBuilder Ease(EaseFunction ease)StaggerBuilder Spring(SpringPreset preset)StaggerBuilder Spring(SpringConfig config)StaggerBuilder Delay(float seconds)StaggerBuilder Loop(LoopMode mode, int count = 0)StaggerBuilder Then()StaggerBuilder Stagger(float secondsBetween) Seconds between each element's start.
0 = all together (pure parallel).StaggerBuilder OnComplete(Action onComplete) Fires once, after the last element's sequence completes.
Stagger class Pro
Timing math for staggered groups, exposed so callers can schedule around one. A stagger does not take duration seconds, it takes duration + (count - 1) * stagger, because the last element has not started yet when the first one finishes. That means a fixed per-element stagger makes the group's length scale with the collection: the same code that spans 0.2 s over ten elements spans 0.9 s over forty. If anything is timed to happen after the group, a repaint, a state change, a second animation, it will be correct while you are testing with a small collection and wrong in production. Use TotalDuration to schedule after a group, or StepForSpan to pin the group's length regardless of how many elements it turns out to contain:
static float TotalDuration(int count, float duration, float stagger) Wall-clock seconds for a whole staggered group: the last element starts at
(count - 1) * stagger and then runs for duration.static float StepForSpan(int count, float spanSeconds, float maxStep = float.PositiveInfinity) The per-element stagger that spreads
count elements over spanSeconds of start offsets, so the group's total length is duration + spanSeconds whatever the count.maxStep- Upper bound on the gap between neighbours, so a small collection does not get an absurdly slow cascade just to fill the span. Defaults to unbounded.
Transitions
Transition struct Pro
A reusable enter/exit transition preset, fade, slide (from an Edge), scale, and their combinations. Build one with a factory and play it with the AnimateIn / AnimateOut / Show / Hide / SwapTo extensions (see TransitionExtensions). Easing or a spring is an optional refinement via WithEase / WithSpring. Springs + reusable presets are exactly what USS transitions can't express. This is a value type, modifiers return a copy.
bool DoFade Animate opacity (0↔1) as part of this transition.
bool DoSlide Animate a slide from
SlideEdge over SlideDistance.Edge SlideEdge Which edge the slide originates from (when
DoSlide).float SlideDistance How far (px) the element travels during the slide.
bool DoScale Animate uniform scale from
ScaleFrom to 1 (in) / 1 to it (out).float ScaleFrom The scale the element grows from on enter (e.g. 0.9 for a subtle pop).
float Duration Duration of the transition, in seconds.
EaseFunction Ease Easing for every component of the transition. Null ⇒ the engine default (OutCubic).
bool UseSpring When true, a physics spring drives the transition instead of
Ease.SpringConfig Spring The spring parameters used when
UseSpring is set.static Transition Fade(float duration) Opacity 0↔1.
static Transition Slide(Edge edge, float duration, float distance = 48f) Translate in from / out toward a screen edge.
static Transition Scale(float duration, float from = 0.85f) Scale between
from and 1.static Transition SlideFade(Edge edge, float duration, float distance = 48f) Slide + fade together, the classic panel entrance.
static Transition ScaleFade(float duration, float from = 0.85f) Scale + fade together.
static Transition Crossfade(float duration) Opacity swap for screen transitions (out and in overlap). Same shape as
Fade.Transition WithEase(EaseFunction ease) Use this easing (clears any spring).
Transition WithSpring(SpringPreset preset) Drive the transition with a named spring instead of easing.
Transition WithSpring(SpringConfig config) Drive the transition with a custom spring.
Transition WithResponse(float response, float bounce = 0f) Drive the transition with a perceptual spring (
response = period in seconds, bounce = arrival character); full model on FromResponse.Transition WithDistance(float distance) Override the slide distance in pixels.
TransitionExtensions class Pro
Play Transition presets on elements: enter/exit (AnimateIn/ AnimateOut), display-aware Show/Hide, and a minimal screen swap (SwapTo).
static TweenSequence AnimateIn(this VisualElement element, Transition t) Animate the element from its hidden state to fully visible. The hidden "from" is primed synchronously (opacity 0 / scaled down / slid off-edge); the actual tween dispatches on the next scheduler tick, so there's no flash and the USS single-frame trap doesn't apply.
static TweenSequence AnimateOut(this VisualElement element, Transition t) Animate the element from visible to its hidden state (does not toggle display, see
Hide).static TweenSequence Show(this VisualElement element, Transition t) Set
display:flex, then animate the element in.static TweenSequence Hide(this VisualElement element, Transition t) Animate the element out, then set
display:none, but only on natural completion (a cancelled hide leaves it shown, per the engine's Cancel ≠ complete rule).static void SwapTo(this VisualElement container, VisualElement target, Transition t) Minimal screen swap: animate out every currently-shown sibling of
target in container, and animate target in. With Crossfade the out/in overlap.Hover, press and focus
InteractionExtensions class Pro
Entry points for declarative micro-interactions.
static Interaction OnHover(this VisualElement element) Animate on pointer hover (enter → active, leave → rest).
static Interaction OnPress(this VisualElement element) Animate while pressed (pointer down → active, up → rest).
static Interaction OnFocus(this VisualElement element) Animate on focus (focus → active, blur → rest).
Interaction class Pro
A declarative hover / focus / press micro-interaction bound to a VisualElement: on activation it animates to an "active" look (e.g. scale 1.05), on release it settles back to the resting look. Driven by pointer/focus events, it is interruption-safe, each transition cancels the previous one and re-captures the current value, so rapid in/out never snaps. Created via element.OnHover() / OnPress() / OnFocus() (see InteractionExtensions):
Interaction ScaleTo(float scale, float duration, EaseFunction ease = null) Scale to
scale while active; settle back to rest on release.Interaction FadeTo(float opacity, float duration, EaseFunction ease = null) Fade to
opacity while active; settle back to rest on release.Interaction RotateTo(float degrees, float duration, EaseFunction ease = null) Rotate to
degrees while active; settle back to rest on release.Interaction BackgroundColorTo(Color color, float duration, EaseFunction ease = null) Tint
style.backgroundColor while active; settle back to the resting colour on release. With OffsetTo, this is what a menu row actually needs: the surface lifts and the label slides. Scaling a full-width row instead grows its text with it, which is why scale-only interactions never looked right on lists.Interaction TextColorTo(Color color, float duration, EaseFunction ease = null) Tint
style.color (text) while active; settle back on release.Interaction OffsetTo(float x, float y, float duration, EaseFunction ease = null) Translate by
x, y pixels relative to where the element was resting when the interaction first fired, and slide back on release. Transform-only, so it never reflows the list around it.Interaction OffsetXTo(float x, float duration, EaseFunction ease = null) Horizontal-only
OffsetTo, the label-slide of a selected menu row.Interaction WithSpring(SpringPreset preset) Drive this interaction with a spring instead of easing. Combined with the velocity relay, rapid hover in/out hands momentum across, no dead-stop.
Interaction WithSpring(SpringConfig config) Drive this interaction with a custom spring.
Interaction WithResponse(float response, float bounce = 0f) Drive this interaction with a perceptual spring (
response = period in seconds, bounce = arrival character); full model on FromResponse.InteractionTrigger enum Pro
Which input state drives a micro-interaction.
HoverPressFocusNamed states
VariantExtensions class Pro
Entry points for named-state ("variants") animation.
static VariantSet Variants(this VisualElement element) Get (or lazily create) the named-state set for this element.
static TweenSequence To(this VisualElement element, string state) Animate this element to a previously-defined variant state (no-op if undefined).
VariantSet class Pro
Framer-Motion-style named states for an element. Define states with State, then animate between them with To. Interruption-safe, a new To cancels the previous transition.
VariantSet State(string name, Action<VariantState> build) Define (or replace) a named state, configured via the
build callback.TweenSequence To(string name) Animate the element to the named state. Returns the sequence, or null if unknown.
VariantState class Pro
One named visual state in a VariantSet, a target look (any of scale / opacity / translate / rotation / background color) plus its timing. Only the properties you set are animated.
VariantState ScaleTo(float scale)VariantState FadeTo(float opacity)VariantState MoveTo(Vector2 translate)VariantState RotateTo(float degrees)VariantState ColorTo(Color background)VariantState In(float duration) Duration in seconds for this state's transition (default 0.3).
VariantState With(EaseFunction ease) Drive this state's transition with an easing curve (clears any spring).
VariantState WithSpring(SpringPreset preset) Drive this state's transition with a named physics spring preset.
VariantState WithSpring(SpringConfig config) Drive this state's transition with explicit spring parameters.
VariantState WithResponse(float response, float bounce = 0f) Drive this state's transition with a perceptual spring (
response = period in seconds, bounce = arrival character); full model on FromResponse.Settings and accessibility
MotionSettings class Lite
Global Cascade settings. The headline one is Mode, wire it to the OS "reduce motion" accessibility setting (or a user toggle).Reduced keeps animation but calms it, Crossfade replaces movement with fades, None snaps instantly. Opt a single animation out with element.Animate()…IgnoreReducedMotion().
static MotionMode Mode Lite The global motion accessibility mode (WCAG 2.3.3), see
MotionMode. Applied per-channel when a sequence dispatches; opt a single essential animation out with element.Animate()…IgnoreReducedMotion(). Mode changes affect animations dispatched AFTER the change (in-flight animations keep their constraints).static bool ReduceMotion Lite
static MotionManifest Describe() The machine-readable capability manifest, every verb + its required fields, the ease/spring/edge vocabularies, and the numeric ranges. One runtime source of truth that the JSON parser reads from and that generates the discoverable AI docs, so the parser, schema, and guide can't drift. Handy for an AI tool to introspect what Cascade can animate.
static MotionStats Stats Lite A read-only snapshot of live engine load (active runners/sequences/tweens + pooled tweens), for a debug HUD, a perf assertion, or confirming animations have stopped. Cheap and allocation-free.
MotionMode enum Lite
Graded motion accessibility (WCAG 2.3.3 "Animation from Interactions"). Set via Mode; applied per-channel when a sequence dispatches.
Full Lite All animation plays as authored (default).
Reduced Lite Everything still animates, briefly and without bounce.
Crossfade Lite Vestibular-safe: positional motion (translate/scale/rotate/layout, and closure-mode verbs like SlideIn/MoveTo) snaps to its end state instantly; opacity animations play as authored, so every transition reads as a crossfade.
None Lite No animation at all: sequences snap to their end state and fire OnComplete immediately (the old
ReduceMotion = true behavior).MotionChannel enum Lite
Which style property an engine-driven ("value-mode") tween animates, the identity used for velocity handoff, channel supersede, and per-channel cancel (element.StopAnimations(MotionChannel.Opacity)).
Custom Lite A closure-mode tween (SlideIn/MoveTo/colors/…): no channel identity, so it can't be targeted by a per-channel stop or participate in the velocity relay.
Opacity Lite
TranslateX Lite
TranslateY Lite
Scale Lite
Rotate Lite
Width Lite
Height Lite
Top Lite
Left Lite
MotionStats struct Lite
A cheap, read-only snapshot of Cascade's live engine load, for a debug HUD, a perf test, or just confirming animations actually stop. Read it via Stats. Counting is O(active sequences) and allocation-free.
readonly int ActiveRunners Lite Panels (per
IPanel) that currently have a running Cascade ticker.readonly int ActiveSequences Lite Sequences currently animating across all panels.
readonly int ActiveTweens Lite Tweens being stepped this frame (the live tweens of each sequence's current step).
readonly int PooledTweens Lite Idle tweens sitting in the shared pool, ready to be reused without allocating.
JSON sequences and presets
SequencePreset class Pro
Declarative JSON round-trip for SequencePreset, a stable, constrained schema an external tool (an AI assistant, a code generator, a content pipeline) can emit to describe an animation, which Cascade then validates and plays. This is the "AI-first" front door: emitting constrained JSON is far more reliable for a language model than generating freeform C#. Format and copy-paste examples.md. Machine-readable schema.schema.json.
TweenSequence Play(VisualElement element) Build and start this sequence on
element. Returns the handle.static SequencePreset FromJson(string json) Parse a JSON sequence description into a runtime
SequencePreset instance. Throws ArgumentException with a human-readable message on any invalid input, use TryFromJson in tooling/AI loops that want to recover and self-correct. JSON shape.{ "steps": [ { "actions": [ { "verb": "...", ... } ] } ] }, steps run in sequence, actions within a step run in parallel. Verbs: Fade, MoveX, MoveY, MoveTo, Scale, Rotate, SlideIn, BackgroundColor, TextColor, Width, Height, Size, Top, Left. Float verbs take "to"; MoveTo/Size take "x" and "y"; color verbs take "color" (e.g. "#FF8800"); SlideIn takes "edge" (Left/Right/Top/Bottom) and "distance". Shared."duration" (seconds), "delay", and either "ease" (e.g. OutCubic, OutBack, Linear) or "spring" (Gentle/Snappy/Bouncy, which overrides ease). Full vocabulary and prompt→animation examples.md.static bool TryFromJson(string json, out SequencePreset preset, out string error) Non-throwing parse. On success,
preset is a fresh instance and error is null. On failure, preset is null and error describes the problem (e.g. "step 0, action 1: verb 'Fade' requires a numeric \"to\"") so a generator can fix its output. For an AI/codegen self-correction loop that wants to branch on the failure and apply a fix, pre-check with Validate, which returns a structured MotionError (code + offending field path + nearest-name suggestion). Note: the returned preset is a ScriptableObject the caller owns, to just check validity in a loop without allocating, use Validate.static bool Validate(string json, out string error) Validate JSON without allocating a preset, for tooling/AI loops that test candidate output before committing. Returns true if it would parse; on false,
error says why (same messages as TryFromJson). For the machine-readable form (code + field path + suggestion) use Validate.static MotionError Validate(string json) Validate JSON and return a structured
MotionError, the self-correction entry point for AI/codegen loops. Returns None (whose IsError is false) when the JSON is valid; otherwise a struct carrying the Code, the offending Path (steps[0].actions[1].to), the human message, and a Suggestion (e.g. "FadeIn" → "Fade"), so the caller can apply the fix instead of guessing it. Allocates no preset.static TweenSequence PlayJson(VisualElement element, string json) Parse + play a JSON sequence on
element in one call (no asset needed). Throws on invalid JSON; catch or pre-validate with Validate.string ToJson(bool pretty = true) Serialize this preset to the same JSON schema
FromJson accepts. Round-trips.FromJson(p.ToJson()) reproduces an equivalent preset (numbers preserved to 6 decimals). Emits only the fields each verb uses; null actions are skipped (matching playback).static List<MotionAdvice> Lint(string json) Report actions that are valid but inert, the companion to
Validate in an AI/codegen loop. Why this exists. Verbs animate to a value and read from the live one, so {"verb":"Fade","to":1} on a visible element is a legitimate no-op. It parses. It validates. It does nothing. A generator told only "MotionError.None" has no way to learn that its entrance never appeared, measured on this package's own documentation, six of fourteen shipped examples had exactly this defect and four did nothing whatsoever. Advisory, never fatal: an element genuinely hidden by USS is a real case, and Validate keeps answering only "will this parse and run". Returns an empty list for valid-and-sensible JSON, and also for JSON that does not parse, linting is a second opinion on something already valid, so check Validate first.List<MotionAdvice> Lint() Lint an authored preset, the same check the JSON path gets, for the inspector.
static string LintSummary(string json) Every advisory on one line, or
null when there is nothing to say, the shape a console warning or an AI's next prompt wants.MotionError struct Pro
A structured validation failure from the JSON front door, returned by Validate (which gives None when the JSON is valid). The Code lets a generator branch, Path points at the exact offending field (steps[0].actions[1].to), and Suggestion offers a nearest-name fix ("FadeIn" → "Fade"), turning "guess the fix" into "apply the fix". The out string overloads of TryFromJson and Validate return just the Message.
readonly MotionErrorCode Code Machine-readable failure category.
readonly string Path Dotted/indexed path to the offending field.
steps[0].actions[1].to. Empty for a whole-document failure (empty/invalid JSON).readonly string Message The same human-readable text the string-returning overloads produce.
readonly string Suggestion Nearest valid name for an unknown enum value (verb/ease/spring/edge), or null.
MotionError(MotionErrorCode code, string path, string message, string suggestion = null)bool IsError True when this represents a real failure (any code other than
None).static MotionError None The "no error" value.
MotionErrorCode enum Pro
A machine-readable category for a JSON-sequence validation failure. Pairs with the human message so an AI/codegen loop can branch on the failure instead of regex-ing a string.
None No error (default).
EmptyJson The input was null/empty/whitespace.
InvalidJson The text wasn't valid JSON, or the root wasn't an object with a "steps" array.
MissingField A required field for the verb was absent (e.g. a float verb with no "to").
UnknownVerb The "verb" value isn't a known
MotionVerb.UnknownEase The "ease" value isn't a known
EaseKind.UnknownSpring The "spring" value isn't a known
SpringPreset.UnknownEdge The "edge" value isn't a known
Edge.NotFinite A numeric field was NaN or Infinity.
OutOfRange A numeric field was finite but outside its allowed range (e.g. duration > 600s).
InvalidColor A "color" string couldn't be parsed.
MotionAdvice struct Pro
One thing a linter noticed about a sequence that is nonetheless valid. Advisory: the JSON parses, and it will run. It just may not do what whoever wrote it meant.
readonly MotionAdviceCode Code What kind of problem this is.
readonly string Path Where it is, in the same dotted form
Path uses (steps[0].actions[1]), so a generator can address the exact action.readonly string Message What is wrong, in a sentence.
readonly string Suggestion The concrete edit that would fix it, ready to apply.
MotionAdvice(MotionAdviceCode code, string path, string message, string suggestion)MotionAdviceCode enum Pro
Kinds of advisory Lint can report.
None No advice, the zero value, so
default(MotionAdvice) is meaningful. Matches None.NoOpAction The action will run and change nothing: its target equals the property's natural resting value, no earlier action in the sequence moved that channel, and it names no
from. Overwhelmingly this is an entrance that forgot to say where it starts.DurationIgnored The action sets both
duration and spring. A spring is driven by its own physics and never reads the duration, so the number is inert, and reads as if it controlled the timing, which is the misunderstanding worth catching.FieldIgnored A
"from" on a verb with no float target (SlideIn, MoveTo, Size, the colour verbs). It parses and is then discarded, which for a self-correcting API is worse than rejecting it.TransitionPreset class Pro
An asset (Create ▸ Cascade ▸ Transition Preset) holding an enter/exit transition for the UI Animator component or for code: preset.ToTransition().
bool fadebool slideEdge slideEdgefloat slideDistancebool scalefloat scaleFromfloat durationbool useSpringEaseKind easeSpringPreset springTransition ToTransition() Build the runtime
Transition this preset describes.InteractionPreset class Pro
An asset (Create ▸ Cascade ▸ Interaction Preset) holding a hover, press or focus look for the UI Animator component or for code: preset.Apply(element, trigger).
bool scalefloat scaleActivebool fadefloat fadeActivebool rotatefloat rotateActivefloat durationEaseKind easeInteraction Apply(VisualElement element, InteractionTrigger trigger) Bind this preset's look to
element for the given trigger.Effects
DropShadowElement class Pro
A soft drop shadow or outer glow drawn with a mesh: no shaders, works in any render pipeline. Put the element you want shadowed inside it as a child. For a glow, set both offsets to 0 and use a bright color with more spread. Usable from UXML as <Cascade.DropShadowElement>.
Color shadowColorfloat blurfloat spreadfloat offsetXfloat offsetYDropShadowElement()FilterEffects class Pro
Animated USS filter effects, BlurTo and TintTo as fluent verbs on Unity 6.3+ (where UI Toolkit ships the filter pipeline). Opt-in and measured: a filter repaints the element through a post-processing pass every frame it animates, profile on target hardware. On older Unity versions the verbs compile but no-op with a one-time warning, so shared code stays portable. Coexists with (does not replace) the mesh-based DropShadowElement; backdrop blur is intentionally NOT offered.
static TweenSequence BlurTo(this TweenSequence seq, float toRadius, float duration) Animate a
filter: blur() radius (px) to toRadius over duration seconds. Captures the current radius at start (0 if none); other filter functions already on the element are preserved.static TweenSequence TintTo(this TweenSequence seq, Color to, float duration) Animate a
filter: tint() color to to over duration seconds. Captures the current tint at start (white = identity); other filter functions already on the element are preserved.