Animate (motion)

Pixi’VN allows developers to animate canvas components using a function called animate. This function is a re-implementation of the animate function from the motion library, adapted to use PixiJS tickers for triggering animation events.

What is motion?
motion is a popular JavaScript library that provides a simple and powerful way to create animations. You can read more about it here.

There are two variants of this function:

• animate: Intended for animating PixiJS or Pixi’VN elements used for UI. Pixi’VN does not save the current state of animations created with this function. Since it is identical to motion’s animate function, it will not be explained further here.
• canvas.animate: Designed for animating Pixi’VN canvas components. It saves the current state of animations, allowing you to restore the state of an animation from a save. This function has some differences from the original animate function, which will be explained in detail below.

Use

The canvas.animate function works as follows: The developer defines a component state to be reached (for example, its x-y position). Once the animation starts, an event is continuously triggered to update the component until it reaches the desired state. You can further customize the animation with various options.

This function has the following parameters:

• components: The PixiJS component(s) to animate. This can be a single component, an array of components, or a string representing the component's alias.
• keyframes: This is an object containing the properties to animate and the values to reach.
• options (Optional): Additional options for the animation, including duration, easing, and ticker. The following options extend those from motion:
  • aliasToRemoveAfter (Optional): An array of strings containing the aliases of the canvas components to remove after the animation completes.
  • tickerIdToResume (Optional): A string containing the ticker ID to resume after the animation completes.
  • tickerAliasToResume (Optional): If you want to resume tickers that were previously paused, provide the aliases of the canvas components whose tickers should be resumed.
  • forceCompleteBeforeNext (Optional): A boolean indicating whether the animation must complete before the next step of the game. If true, the game will force the animation to finish before proceeding.
• priority (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is UPDATE_PRIORITY.NORMAL.

The function returns the ID of the ticker created to animate the component(s).

Here are some examples:

Sequence

The canvas.animate function can also be used to create sequences of animations.

To create a sequence, you can pass arrays as properties values in the keyframes object. In this case, you can use the times property to specify the timing of each keyframe.

For example:

import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        const alien = await showImage("alien"); 
        canvas.animate( 
            alien, 
            { 
                xAlign: [0, 1, 1, 0, 0], 
                yAlign: [0, 0, 1, 1, 0], 
            }, 
            { repeat: Infinity, duration: 10 } 
        ); 
    },
]);

Timeline sequences

Another way to create animation sequences with canvas.animate is by using a timeline. This is useful when you want to chain multiple animations that are not strictly linear. You can provide an array of keyframes, where each keyframe is an object with the properties to animate and their values, along with optional animation options.

For example:

import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        const alien = await showImage("alien"); 
        canvas.animate( 
            alien, 
            [ 
                [{ xAlign: 0, yAlign: 0 }, { ease: "circInOut" }], 
                [{ xAlign: 1, yAlign: 0 }, { ease: "backInOut" }], 
                [{ xAlign: 1, yAlign: 1 }, { ease: "linear" }], 
                [{ xAlign: 0, yAlign: 1 }, { ease: "anticipate" }], 
                [{ xAlign: 0, yAlign: 0 }, { ease: "easeOut" }], 
            ], 
            { repeat: 10, duration: 10 } 
        ); 
    },
]);

Methods

The canvas.animate function is built on Pixi’VN Tickers, so you can use all the functions available to control Pixi’VN Tickers.