Class Tween

Prefer animate or tween; the constructor is public only so a Tween can be built by name where that reads better.

Length of one cycle in seconds, as passed to Tween.to.

Whether an advance has carried local time to Tween.totalDuration.

A playback fact, not a time fact: Tween.seek never sets or clears it, so scrubbing a finished tween back inspects its earlier values without pretending it is running again, and scrubbing an unfinished tween past its end does not silently consume the completion its next advance owes. Restarting a finished tween is deliberately not offered — build a new tween, or let a Timeline (§16) own repeated playback.

Seconds since Tween.play, including the delay.

Eased progress currently being written, in [0, 1] for the standard easings. Derived from Tween.localTime alone.

Current playback state.

The object paths are resolved against.

delay + duration × (repeat + 1) seconds — the local time at which the tween finishes. Infinity for repeat(Infinity), and just the delay for a zero-duration tween (where 0 × Infinity would otherwise be NaN).

Advances local time by deltaSeconds × speed and writes the resulting values. Called by the fixed-step AnimationSystem (plan P4-1); a tween never advances itself and never reads a clock (§33).

A no-op unless the tween is "running" and unfinished. The advance that reaches Tween.totalDuration clamps local time to it, writes the exact end values, frees the properties it held, and fires Tween.onComplete — in that order, so the callback observes the final pose.

Declares which node's §42 authority gates this tween's transform writes.

The inference is honest about its limits. When the tween's target is a Node, the node is found automatically and nothing needs declaring. But §15's own example animates node.position — a bare Vector3 — and a math object carries no back-reference to the node that owns it, so animate(node.transform.position) cannot infer the node and its transform writes are ungated unless this method is called:

animate(node.transform.position).to({ x: 10 }, 1).authority(node).play();
Copy

A declared node gates only the properties that actually resolve inside its transform (identity-tested against transform and its authored members); declaring a node for a tween that touches no transform of that node is inert rather than an error, since a tween may legitimately animate a mix.

Seconds of local time to consume before progress starts. The start pose is written throughout the delay, so a delayed tween holds its start values rather than leaving the property wherever it was.

Sets the easing curve, by §15 name ("cubic-out") or as a bare (t) => number. Unknown names throw through resolveEasing.

Overrides the start values that would otherwise be captured from the live properties at Tween.play.

Values are cloned at play, so the objects passed here stay the caller's. Paths may be a subset of Tween.to's; anything omitted is still captured live. A path that is not in to is a mistake and throws at play (it cannot be caught here — from may legally be chained before to).

Callback for the advance that finishes the tween. It fires exactly once — after the final values are written and the property claims released — and never for Tween.seek, matching §16's rule that "seek and scrubbing suppress" event callbacks.

Suspends advancing. A no-op unless the tween is "running".

Resolves bindings, captures start values, claims properties (§16), and starts playback at local time 0 — writing the start pose immediately, so Tween.from takes effect without waiting for an advance.

A no-op on a tween that is not "idle": replaying is seek(0) plus Tween.resume, and silently re-capturing start values from a half-animated property would make playback depend on when play was called rather than on local time.

Number of additional cycles after the first, so repeat(1) plays twice and repeat(0) (the default) plays once. Infinity never finishes.

Resumes advancing. A no-op unless the tween is "paused".

Positions playback at localTimeSeconds and writes the values for that time. Pure: seeking to the same time twice writes identical values, and seeking backwards is as valid as forwards (§16 scrubbing).

Neither Tween.state nor Tween.finished changes — a paused tween stays paused, a finished one stays finished — so a seek is only ever an evaluation, never a playback decision. onComplete therefore never fires from a seek (§16: "seek and scrubbing suppress them by default"); seeking past the end does not consume the completion that the next advance still owes.

A "stopped" tween repositions but writes nothing: it released its properties. A "finished" one still writes, which is what scrubbing means; if another tween has since claimed those properties, that scrub competes with it unwarned — stop a finished tween you intend to keep scrubbing past.

Multiplier applied to every Tween.advance delta.

Must be positive and finite. Reverse playback is deliberately not spelled speed(-1): §16 lists "reversing" as a Timeline requirement, and a negative multiplier here would make "the advance that finishes the tween" ambiguous. Scrub backwards with Tween.seek instead.

Stops the tween and releases its property claims, leaving every animated value exactly where the last write put it. A stopped tween never writes again, and the properties it held are free for another tween to claim without a §16 conflict warning.

A no-op on an "idle" tween, which holds nothing.

Declares the properties to animate and the cycle length in seconds (§7a — never milliseconds).

Callable once. A second call throws rather than guessing whether it meant "add properties" or "append a second segment": sequencing is §16's Timeline, not a tween's job.

Reflects every odd cycle, so a repeating tween walks back to its start value instead of jumping. Easing is applied after the reflection, which is what makes an eased yoyo symmetric in shape.