О чем этот пример

Создание последовательных и повторяющихся анимаций — частая задача в игровой разработке. Ручное управление временными задержками и очередностью твинов быстро становится сложным и подверженным ошибкам. Встроенный класс `Timeline` в Phaser 3 решает эту проблему, позволяя планировать выполнение анимаций по временной шкале. Это особенно полезно для создания скриптованных кат-сцен, поведения боссов или сложных цикличных движений персонажей.

Версия Phaser: код и демо в этой статье рассчитаны на Phaser 3.90.0.

Живой запуск

Ниже встроен рабочий билд примера. Оригинальный источник: GitHub.

Исходный код


class Example extends Phaser.Scene
{
    preload ()
    {
        this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
        this.load.atlas('timeline', 'assets/atlas/timeline.png', 'assets/atlas/timeline.json');
        this.load.image('bg', 'assets/skies/spookysky.jpg');
    }

    create ()
    {
        this.add.image(400, 300, 'bg');

        this.thread = this.add.graphics();

        this.spider = this.add.sprite(400, 100, 'timeline', 'spider');

        const timeline = this.add.timeline([
            {
                at: 2000,
                tween: {
                    targets: this.spider,
                    y: 400,
                    ease: 'bounce.out',
                    duration: 5000,
                    onComplete: () => {
                        console.log("Tween completed");
                    }
                }
            },
            {
                at: 4000,
                tween: {
                    targets: this.spider,
                    x: 200,
                    angle: 30,
                    ease: 'sine.out',
                    duration: 1000,
                    yoyo: true,
                    repeat: -1,
                    repeatDelay: 2000
                }
            },
            {
                at: 6000,
                tween: {
                    targets: this.spider,
                    x: 600,
                    angle: -30,
                    ease: 'sine.out',
                    duration: 1000,
                    yoyo: true,
                    repeat: -1,
                    repeatDelay: 2000
                }
            }
        ]);

        timeline.play();

        this.time.delayedCall(3000, () => {
            timeline.destroy();
            console.log("Timeline destroyed");
        })
    }

    update ()
    {
        this.thread.clear();
        this.thread.lineStyle(1, 0xffffff, 0.7);
        this.thread.lineBetween(400, 0, this.spider.x, this.spider.y);
    }
}

const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#000000',
    parent: 'phaser-example',
    scene: Example
};

const game = new Phaser.Game(config);

Что такое Timeline?

Timeline — это менеджер временной шкалы, который позволяет назначать твины на определённые моменты времени относительно старта самой шкалы. В отличие от ручного вызова this.time.delayedCall для каждого действия, таймлайн инкапсулирует всю логику последовательности.

В примере создаётся шкала с тремя ключевыми точками (ат 2000, 4000 и 6000 миллисекунд). После запуска методом play() таймлайн сам позаботится о своевременном старте каждого твина.

Создание и конфигурация временной шкалы

Таймлайн создаётся с помощью метода this.add.timeline(), который принимает массив объектов-событий. Каждое событие определяется временной меткой at и конфигурацией tween.

const timeline = this.add.timeline([
    {
        at: 2000,
        tween: {
            targets: this.spider,
            y: 400,
            ease: 'bounce.out',
            duration: 5000,
            onComplete: () => { console.log("Tween completed"); }
        }
    }
]);

Ключ at указывает задержку в миллисекундах от момента запуска таймлайна. Объект tween — это стандартная конфигурация для this.tweens.add(). Phaser автоматически создаст и запустит этот твин в заданное время.

Практический разбор примера: Паук на паутине

В примере анимация паука разделена на три этапа.

**Первый этап (at: 2000):** Паук падает вниз с эффектом отскока (bounce.out). Это твин выполнится один раз.

{
    at: 2000,
    tween: {
        targets: this.spider,
        y: 400,
        ease: 'bounce.out',
        duration: 5000
    }
}

**Второй и третий этапы (at: 4000 и at: 6000):** После падения паук начинает раскачиваться между двумя точками. Обратите внимание на параметры yoyo: true и repeat: -1, которые создают бесконечное возвратно-поступательное движение. repeatDelay: 2000 добавляет паузу между повторами.

{
    at: 4000,
    tween: {
        targets: this.spider,
        x: 200,
        angle: 30,
        ease: 'sine.out',
        duration: 1000,
        yoyo: true,
        repeat: -1,
        repeatDelay: 2000
    }
}

Метод update() в сцене рисует линию («паутину») от верхней точки к пауку, используя Graphics.lineBetween().

Управление жизненным циклом Timeline

Таймлайном можно управлять: запускать, приостанавливать, возобновлять и уничтожать. В примере показано принудительное уничтожение шкалы через 3 секунды после старта сцены, что останавливает все запланированные, но ещё не начатые твины.

this.time.delayedCall(3000, () => {
    timeline.destroy();
    console.log("Timeline destroyed");
})

Важно: уничтожение таймлайна (destroy()) не останавливает и не отменяет уже запущенные твины. Они продолжат своё выполнение до завершения. Для полной остановки анимации нужно управлять самими твинами отдельно.

Что попробовать дальше

Timeline — мощный инструмент для декларативного описания сложных анимационных последовательностей. Он идеально подходит для неинтерактивных сцен, где важна точность времени. Для экспериментов попробуйте

  1. Связать событие onComplete одного твина с запуском следующего для цепочек
  2. Использовать таймлайн для управления не только положением спрайтов, но и их свойствами, например alpha или scale
  3. Создать несколько параллельных таймлайнов для независимых групп объектов