Skip to content

@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:

TraitChangesInterpolation
TweenPositionPositionlinear per axis
TweenScaleScalelinear per axis
TweenRotationRotationspherical (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) ​

OptionDefaultMeaning
fromcurrent valueStart value; taken from the entity when the tween starts.
duration1Seconds per play.
delay0Seconds before the first play.
easing"linear"Name of a curve in Easing, or a function from linear progress (0 to 1) to eased progress.
repeat0Extra plays after the first; Infinity loops forever.
enableYoyofalsePlay 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 }));
ParamDefaultMeaning
on"click"Entity event that plays the tween.
off""Entity event that plays it back; empty to go there and back on on.
scale1Scale to reach, as a multiple of the resting scale.
lift0How far to rise along Y.
turn0How far to turn around Y, in radians.
duration0.2Seconds 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.