---
url: /pawn/docs/packages/tween.md
description: Tweens of Position, Rotation and Scale, easings and tweenend.
---

# @pawnjs/tween

Tweens of `Position`, `Rotation` and `Scale`, driven by engine time.

```bash
bun add @pawnjs/core @pawnjs/tween koota@0.6.6 three
bun add -d @types/three
```

```ts
import { TweenPosition, TweenScale, tween } from "@pawnjs/tween";

entity.add(
  TweenPosition(tween({ x: 0, y: 2, z: 0 }, { duration: 0.5, easing: "cubicOut" })),
);
```

Three spheres slide with three easings, `linear`, `cubicInOut` and
`backOut`; each `tweenend` starts the next slide:

```ts
import { Engine, Position, Shape, View } from "@pawnjs/core";
import { type EasingName, TweenPosition, tween } from "@pawnjs/tween";
import { AmbientLight, DirectionalLight, PerspectiveCamera } from "three";

export default function tweenDemo(canvas: HTMLCanvasElement): Engine {
  canvas.style.cssText = "display:block;width:100%;height:100%";
  const engine = new Engine({ canvas });
  engine.scene.add(new AmbientLight(0xffffff, 0.7));
  const sun = new DirectionalLight(0xffffff, 2);
  sun.position.set(3, 6, 5);
  engine.scene.add(sun);

  // One sphere per easing, sliding from side to side.
  const easings: EasingName[] = ["linear", "cubicInOut", "backOut"];
  easings.forEach((easing, i) => {
    const y = 0.9 - i * 0.9;
    const ball = engine.world.spawn(
      Shape({ kind: "sphere", color: ["#94a3b8", "#6366f1", "#f59e0b"][i] }),
      Position({ x: -2, y }),
    );
    let x = 2;
    const slide = () => {
      ball.add(TweenPosition(tween({ x, y, z: 0 }, { duration: 1.2, easing })));
      x = -x;
    };
    // Each tween that plays to its end starts the next one.
    engine.events.on(ball, "tweenend", slide);
    slide();
  });

  const camera = new PerspectiveCamera(45, 1, 0.1, 100);
  camera.position.set(0, 0, 6);
  engine.views.add(new View({ camera, background: 0x09090b }));

  engine.fitToElement(canvas);
  engine.start();
  return engine;
}

```

The `Tween` plugin runs one system in the `update` phase. An engine
installs it when an entity first gets a tween trait; to move the system
within the phase, `engine.use(new Tween({ order }))` before that. Each tween trait changes one transform trait:

| Trait | Changes | Interpolation |
|---|---|---|
| `TweenPosition` | `Position` | linear per axis |
| `TweenScale` | `Scale` | linear per axis |
| `TweenRotation` | `Rotation` | spherical (quaternion slerp) |

A tween trait is removed when its tween ends, so `entity.has(TweenScale)`
tells you whether one is still running. A tween that plays to its end also
emits a `tweenend` [entity event](/guide/behaviors#entity-events) with the
`property` it changed (`"position"`, `"rotation"` or `"scale"`):

```ts
engine.events.on(entity, "tweenend", ({ property }) => {
  if (property === "scale") entity.add(TweenPosition(tween(next)));
});
```

An entity missing the tweened trait gets it with its default value (scale 1, for example).

## `tween(to, options)`

| Option | Default | Meaning |
|---|---|---|
| `from` | current value | Start value; taken from the entity when the tween starts. |
| `duration` | `1` | Seconds per play. |
| `delay` | `0` | Seconds before the first play. |
| `easing` | `"linear"` | Name of a curve in `Easing`, or a function from linear progress (0 to 1) to eased progress. |
| `repeat` | `0` | Extra plays after the first; `Infinity` loops forever. |
| `enableYoyo` | `false` | Play every other repeat backwards. |

A pulse that grows and returns:

```ts
entity.add(
  TweenScale(
    tween({ x: 1.5, y: 1.5, z: 1.5 }, { duration: 0.2, enableYoyo: true, repeat: 1, easing: "backOut" }),
  ),
);
```

## Easing

`Easing` has `linear`, `quadIn`, `quadOut`, `quadInOut`, `cubicIn`,
`cubicOut`, `cubicInOut`, `sineInOut` and `backOut`; `EASING_NAMES` lists
them. Pass a curve by name (`easing: "quadOut"`) so tween state stays
plain data that can be saved. Any `(t: number) => number` works too, as an
`EasingFunction`, but does not serialize.

## `TweenOn`

A [behavior](/guide/behaviors) that plays a tween when an entity event
reaches the entity: it scales, lifts or turns the entity from where it
rests, taken when a run starts while no tween moves it.

```ts
import { Clickable } from "@pawnjs/core";
import { TweenOn } from "@pawnjs/tween";

button.add(
  Clickable,
  TweenOn({ on: "click", scale: 1.1, duration: 0.15 }),
);
// Down while pressed, back up on release:
key.add(TweenOn({ on: "pointerdown", off: "pointerup", lift: -0.1 }));
```

| Param | Default | Meaning |
|---|---|---|
| `on` | `"click"` | Entity event that plays the tween. |
| `off` | `""` | Entity event that plays it back; empty to go there and back on `on`. |
| `scale` | `1` | Scale to reach, as a multiple of the resting scale. |
| `lift` | `0` | How far to rise along Y. |
| `turn` | `0` | How far to turn around Y, in radians. |
| `duration` | `0.2` | Seconds to get there (and as many to get back). |
| `easing` | `"quadOut"` | Curve, by name in `Easing`. |

Events bubble, so a click on a child entity plays the parent's `TweenOn`.
The plugin installs `Tween` if the engine has none.
