Appearance
@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/threets
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 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 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.