Transform

Transform describes how a displayable element changes on screen: where it moves, how it scales, how it rotates, and how visible it is.

The easiest way to read the API is:

Chain the visual changes you want.
Call commit() to turn those changes into one animation step.
Keep chaining more steps if the animation should continue.

import { Transform } from "narraleaf-react";
 
const bounce = Transform.create()
    .position({ yoffset: -10 })
    .commit({ duration: 120, ease: "easeOut" })
    .position({ yoffset: 0 })
    .commit({ duration: 100, ease: "easeOut" })
    .repeat(2);
 
scene.action([
    characterImage.transform(bounce),
]);

Most animations can be built with Transform.create(), one or more property methods, and commit().

Mental Model

Stage changes

Methods like position(), zoom(), rotation(), and opacity() do not immediately add a new animation step. They stage changes on the current step.

Transform.create()
    .position({ xalign: 0.5 })
    .opacity(1)

Commit a step

commit() records the staged changes as one sequence. Its options describe how that sequence runs.

Transform.create()
    .position({ xalign: 0.5 })
    .opacity(1)
    .commit({ duration: 300, ease: "easeOut" })

Chain the next step

After a commit, the staging area is cleared. The next property calls build the next sequence.

Transform.create()
    .position({ xalign: 0.35 })
    .commit({ duration: 300, ease: "easeOut" })
    .position({ xalign: 0.65 })
    .commit({ duration: 300, ease: "easeInOut" })

Common Recipes

Move to a side

Use the built-in helpers when all you need is a stage position.

scene.action([
    characterImage.transform(Transform.left(250, "easeOut")),
    characterImage.transform(Transform.center(250, "easeInOut")),
    characterImage.transform(Transform.right(250, "easeOut")),
]);

Move and fade together

Put multiple property calls before one commit() to animate them at the same time.

const enter = Transform.create()
    .position({ xalign: 0.5, yoffset: 0 })
    .opacity(1)
    .commit({ duration: 300, ease: "easeOut" });

Build a tiny timeline

Each commit() appends a step, so the transform reads in playback order.

const lookAround = Transform.create()
    .rotation(-4)
    .commit({ duration: 180, ease: "easeOut" })
    .rotation(4)
    .commit({ duration: 240, ease: "easeInOut" })
    .rotation(0)
    .commit({ duration: 180, ease: "easeOut" });

Apply a state immediately

Use immediate() when you want a visual state without a transition.

scene.action([
    characterImage.transform(
        Transform.immediate({ opacity: 0 })
    ),
]);

Chained API vs Raw Sequences

The chained API and the constructor create the same kind of Transform. Prefer the chained API for everyday animation because it keeps the timing next to the change it belongs to.

const bounce = Transform.create()
    .position({ yoffset: -10 })
    .commit({ duration: 120, ease: "easeOut" })
    .position({ yoffset: 0 })
    .commit({ duration: 100, ease: "easeOut" });

A raw sequence has two parts:

props contains the visual changes for that step, such as position, rotation, zoom, scaleX, scaleY, opacity, or fontColor.
options contains timing options for that step, such as duration, ease, delay, or at.

For the full property types, see TransformDefinitions.

Static Methods

left

Move the image to the left side of the stage.

duration: number - The duration of the movement in milliseconds.
easing?: TransformDefinitions.EasingDefinition - The easing function. See EasingDefinition.
Returns Transform<T>

right

Move the image to the right side of the stage.

duration: number - The duration of the movement in milliseconds.
easing?: TransformDefinitions.EasingDefinition - The easing function. See EasingDefinition.
Returns Transform<T>

center

Move the image to the center of the stage.

duration: number - The duration of the movement in milliseconds.
easing?: TransformDefinitions.EasingDefinition - The easing function. See EasingDefinition.
Returns Transform<T>

immediate<T extends TransformDefinitions.Types>

Create a transform that applies the given properties immediately.

props: SequenceProps<T> - A single SequenceProps object.
Returns Transform<T>

create<T extends TransformDefinitions.Types>

Create an empty transform that can be built with chained property methods.

config?: Partial<TransformDefinitions.TransformConfig> - The transform config. See TransformConfig.
Returns Transform<T>

Public Methods

constructor<T extends TransformDefinitions.Types>

Use the constructor when you already have a sequence object or when generated code produces sequence arrays.

Overload 1 of 2

This overload accepts an array of sequences.

new Transform<TransformDefinitions.ImageTransformProps>([
    {
        props: {
            position: {
                xalign: 0.3,
            },
        },
        options: {
            duration: 120,
            ease: "easeOut",
        },
    },
    {
        props: {
            position: {
                xalign: 0.6,
            },
        },
        options: {
            duration: 100,
            ease: "easeOut",
        },
    },
], {
    repeat: 2,
});

sequences: TransformDefinitions.Sequence<T>[] - The sequence array.
transformConfig?: Partial<TransformDefinitions.TransformConfig> - Transform-level options.

Overload 2 of 2

This overload accepts a single sequence.

new Transform<TransformDefinitions.ImageTransformProps>({
    position: {
        xalign: 0.3,
    },
}, {
    duration: 120,
    ease: "easeOut",
});

props: SequenceProps<T> - A single SequenceProps object.
options?: Partial<TransformDefinitions.CommonTransformProps> - Timing options for that sequence. See CommonTransformProps.

repeat

Repeat the transform.

transform
    .repeat(2)
    .repeat(3);
// repeats 6 times

n: number - The number of times to repeat the transform.
Returns this

copy

Copy the transform.

Returns Transform<T>

commit

Commit all staged changes into one transform sequence. If there are no staged changes, commit() returns the current instance without changing it.

transform
    .position({ x: 100, y: 100 })
    .opacity(1)
    .commit()
    .position({ x: 200, y: 200 })
    .opacity(0)
    .commit({ duration: 1000 });

The first commit creates a sequence with position and opacity. The second commit creates another sequence with its own timing options.

options?: Partial<TransformDefinitions.SequenceOptions> - Sequence timing options. See SequenceOptions.
Returns this

scale

Stage scale changes for both axes.

scaleX: TransformDefinitions.Types["scaleX"] - The X-axis scale. Negative values invert the element on the X axis.
scaleY: TransformDefinitions.Types["scaleY"] - The Y-axis scale. Negative values invert the element on the Y axis.
Returns this

scaleX

Stage an X-axis scale change.

scaleX: TransformDefinitions.Types["scaleX"] - The X-axis scale.
Returns this

scaleY

Stage a Y-axis scale change.

scaleY: TransformDefinitions.Types["scaleY"] - The Y-axis scale.
Returns this

scaleXY

Stage scale changes for both axes.

scaleX: TransformDefinitions.Types["scaleX"] - The X-axis scale.
scaleY: TransformDefinitions.Types["scaleY"] - The Y-axis scale.
Returns this

zoom

Stage a zoom change. This is the recommended method for normal image scaling.

zoom: TransformDefinitions.Types["zoom"] - The zoom level.
Returns this

rotation

Stage a rotation change.

rotation: TransformDefinitions.Types["rotation"] - The rotation value.
Returns this

position

Stage a position change.

position: TransformDefinitions.Types["position"] - The position value.
Returns this

opacity

Stage an opacity change.

opacity: TransformDefinitions.Types["opacity"] - The opacity value.
Returns this

fontColor

Stage a text color change.

fontColor: TransformDefinitions.Types["fontColor"] - The font color value.
Returns this

Animation Transition