Tweens & Motion¶

Smoothly animate things over time — move, rotate, scale, fade, tint, punch, shake, or drive any number — with a single call. Tween.* gives you eased motion (ease-in/out, bounce, elastic, …), looping, delays and completion callbacks, with zero setup: the first tween just works.

Every Tween.* that starts an animation returns an int handle. Keep it if you want to control the tween later (pause, kill, loop); ignore it if you just want it to play.

public class Door : NexusBehaviour
{
    public void Open()
    {
        Tween.LocalMove(gameObject, 0f, 3f, 0f, 1.0f, 6);   // slide up 3m over 1s, ease InOutQuad
    }
}

Three ways to tween

This page is the scripting way. You can also add a Tween component to an object (a step list with a live preview, no code), or add a Tween action to an interactable or World Trigger event — all three drive the same engine.

Starting a tween¶

obj is a GameObject (use gameObject for the object your script is on, or any object you've found). ease is a number — see Easing.

Call	Animates
`Tween.Move(obj, x, y, z, duration, ease)`	World position to `(x,y,z)`.
`Tween.LocalMove(obj, x, y, z, duration, ease)`	Local position (relative to the parent).
`Tween.Rotate(obj, x, y, z, duration, ease)`	Local rotation to the euler angles `(x,y,z)`.
`Tween.Scale(obj, x, y, z, duration, ease)`	Local scale to `(x,y,z)`.
`Tween.Fade(obj, alpha, duration, ease)`	Transparency to `alpha` (0 = invisible, 1 = opaque). Works on a UI CanvasGroup, a sprite, text, or a material.
`Tween.Color(obj, r, g, b, a, duration, ease)`	Colour (each channel `0..1`).
`Tween.Value(from, to, duration, ease)`	A plain number from `from` to `to` — each step is delivered to your `OnTweenValue` callback (below). Great for scores, timers, gauges.
`Tween.Punch(obj, x, y, z, duration)`	A quick decaying "punch" offset that springs back — good for impacts/feedback.
`Tween.Shake(obj, duration, strength)`	A random shake that settles — screen/object shake.

// A coin that spins, rises and fades as it's collected
public void Collect()
{
    Tween.Rotate(gameObject, 0f, 360f, 0f, 0.6f, 5);
    Tween.LocalMove(gameObject, 0f, 1.5f, 0f, 0.6f, 8);
    Tween.Fade(gameObject, 0f, 0.6f, 5);
}

Easing¶

ease is a number choosing the acceleration curve. Common ones:

Ease	Number	Feel
Linear	`0`	Constant speed.
Out Quad	`5`	Eases out — natural slow-to-stop.
In Out Quad	`6`	Eases in and out — smooth both ends.
Out Cubic	`8`	Stronger slow-to-stop.
Out Back	`17`	Overshoots then settles.
Out Elastic	`20`	Springy wobble at the end.
Out Bounce	`23`	Bounces to a stop.

The full set is In/Out/InOut of Sine, Quad, Cubic, Quart, Expo, Back, Elastic, Bounce (numbers 1–24, in that order), plus Linear = 0. For a fully bespoke curve, use the Tween component or Event action, which let you draw an animation curve.

Controlling a tween¶

Pass the handle a tween returned:

Call	What it does
`Tween.Kill(handle)`	Stop it where it is.
`Tween.Complete(handle)`	Jump to the end (and fire its completion callback).
`Tween.Pause(handle)` / `Tween.Resume(handle)`	Pause / resume.
`Tween.IsPlaying(handle)`	`true` while it's still running.

Controlling an unknown or finished handle does nothing — it's always safe to call.

Loops, delays & relative — chainable¶

These take a handle and return the same handle, so you can wrap them around a create call:

Call	What it does
`Tween.SetLoop(handle, count, pingpong)`	Repeat `count` times (`-1` = forever). `pingpong` true = play forward then back each loop.
`Tween.SetDelay(handle, seconds)`	Wait `seconds` before starting.
`Tween.SetRelative(handle, relative)`	When `true`, the target value is treated as a delta from the current value (e.g. "move up 3" instead of "move to y=3").
`Tween.SetFrom(handle, from)`	When `true`, the tween runs backwards from the value you gave to the object's current value — a "from" animation. Perfect for intros: fade in from 0, slide in from off-screen. (Not for Punch/Shake.)

// Bob up and down forever, starting after half a second
int h = Tween.SetLoop(Tween.LocalMove(gameObject, 0f, 0.5f, 0f, 1f, 6), -1, true);
Tween.SetDelay(h, 0.5f);
Tween.SetRelative(h, true);   // "up 0.5", not "to y=0.5"

// Fade IN: start invisible, animate up to the object's current opacity
Tween.SetFrom(Tween.Fade(gameObject, 0f, 0.4f, 5), true);

Reacting to a tween¶

The engine calls these methods by name on your script — declare only the ones you want:

Callback	When it fires
`OnTweenComplete(id)`	A tween finishes (naturally or via `Tween.Complete`). `id` is that tween's handle.
`OnTweenValue(id, value)`	Each frame of a `Tween.Value`, with the current number.

public class Score : NexusBehaviour
{
    int _tween;

    public void CountUp(float target)
    {
        _tween = Tween.Value(0f, target, 1.5f, 8);   // roll the score up over 1.5s
    }

    public void OnTweenValue(int id, float value)
    {
        if (id == _tween)
            Debug.Log("Score: " + (int)value);       // update your label/text here
    }

    // Chain: when the roll finishes, punch the label
    public void OnTweenComplete(int id)
    {
        if (id == _tween)
            Tween.Punch(gameObject, 0f, 0.1f, 0f, 0.3f);
    }
}

Sequencing

To play tweens one after another from a script, start the next one inside OnTweenComplete. For a fixed timeline you set up visually, the Tween component's step list is the easier path.

Notes¶

Tweens are visual/client-local — they animate what you see. A tween on a networked object doesn't replicate on its own; it's for local feedback, UI and cosmetics.
A tween is automatically stopped if its object is destroyed — handles never dangle.

Quick reference¶

Group	Calls
Start	`Tween.Move · LocalMove · Rotate · Scale · Fade · Color · Value · Punch · Shake`
Control	`Tween.Kill · Complete · Pause · Resume · IsPlaying`
Chain	`Tween.SetLoop · SetDelay · SetRelative · SetFrom`
Callbacks	`OnTweenComplete(id)` · `OnTweenValue(id, value)`

→ Prefer no scripting? Add a Tween component or a Tween action on an Interactable / World Trigger.