v4-new-features

Новые функции Phaser 4

Новые функции и возможности Phaser 4: Фильтры (заменяющие FX/BitmapMask), RenderNodes (заменяющие Pipelines), игровые объекты CaptureFrame, Gradient, Noise, SpriteGPULayer, TilemapGPULayer, компонент Lighting, RenderSteps и новые режимы оттенков.

Связанные навыки:../v3-to-v4-migration/SKILL.md, ../filters-and-postfx/SKILL.md, ../game-object-components/SKILL.md, ../tilemaps/SKILL.md

Переходите с версии v3? Ознакомьтесь с Руководством по переходу с v3 на v4, где приведены пошаговые инструкции по изменению кода, список удалённых API и контрольный список для перехода.

Обзор: что изменилось в версии v4

Phaser 4 представляет собой полную переработку движка рендеринга WebGL. В версии v3 каждый подсистемный компонент управлял состоянием WebGL независимо, что приводило к конфликтам (например, некоторые эффекты нарушали работу масок). В версии v4 управление состоянием WebGL централизовано с помощью графа RenderNode, в котором каждый узел обрабатывает ровно одну задачу рендеринга.

Основные удаления

Основные дополнения

• Новые GameObjects: CaptureFrame, Gradient, Noise, NoiseCell2D/3D/4D, NoiseSimplex2D/3D, SpriteGPULayer, Stamp, TilemapGPULayer
• Новые компоненты: Lighting, RenderSteps, RenderNodes
• Новые режимы оттенка: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT
• Новые фильтры: Blend, Blocky, CombineColorMatrix, GradientMap, ImageLight, Key, Mask, NormalTools, PanoramaBlur, ParallelFilters, Quantize, Sampler, Threshold
• Ориентация GL: в версии 4 используется стандартная ориентация GL (Y=0 внизу для текстур)

Система фильтров (заменяет FX и BitmapMask)

Полное руководство: filters-and-postfx.md

Фильтры объединяют системы FX и Mask версии v3. Каждый фильтр принимает входное изображение и генерирует выходное изображение посредством прохода шейдера. Фильтры можно применять к любому игровому объекту или камере — в версии v3 существовали ограничения на то, какие объекты поддерживали FX.

// Подход v3 (FX):
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);// Подход v4 (фильтры):
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);// Подход версии 3 (BitmapMask):
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);// Подход v4 (FilterMask):
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

Внутренние и внешние фильтры: внутренние фильтры запускаются до преобразования камеры (локальное пространство объекта, меньшая нагрузка). Внешние фильтры запускаются после (пространство экрана, полное разрешение).

RenderNodes (замена конвейеров)

В версии v3 конвейер представлял собой систему рендеринга, которая часто выполняла несколько задач. В версии v4 каждый RenderNode обрабатывает одну задачу рендеринга с помощью метода run(). Некоторые узлы также имеют метод batch() для накопления состояния перед рисованием.

Архитектура

RenderNodeManager (в рендерере WebGL) управляет всеми узлами рендеринга. Игровые объекты обращаются к узлам через карты, основанные на ролях.

// Роли RenderNode на игровом объекте:
// - «Submitter»: запускает другие роли узлов для каждого элемента
// - «Transformer»: предоставляет координаты вершин
// - «Texturer»: обрабатывает текстуры// Игровые объекты имеют карты узлов рендеринга по умолчанию и настраиваемые:
gameObject.defaultRenderNodes  // встроенные узлы по ролям
gameObject.customRenderNodes   // переопределения по ролям
gameObject.renderNodeData      // данные, индексированные по имени узла

Настройка пользовательских узлов рендеринга

// Переопределить конкретную роль узла рендеринга:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');// Передать данные узлу рендеринга:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});// Удаление пользовательского узла (используется значение по умолчанию):
gameObject.setRenderNodeRole('Submitter', null);

Встроенные типы узлов рендеринга

Обработчики пакетов (накапливают и рисуют несколько объектов за один вызов рисования):

• BatchHandlerQuad — стандартная пакетная обработка четырехугольников (Image, Sprite, BitmapText и т. д.)
• BatchHandlerQuadSingle — вариант с одним квадрантом
• BatchHandlerTileSprite — пакетная обработка TileSprite
• BatchHandlerTriFlat — пакетная обработка плоских треугольников (Graphics, Shape)
• BatchHandlerPointLight — пакетная обработка точечных источников света
• BatchHandlerStrip — пакетная обработка полос треугольников

Submitters (координатное рендеринг по типу объекта):

• SubmitterQuad, SubmitterTile, SubmitterTileSprite
• SubmitterSpriteGPULayer, SubmitterTilemapGPULayer

Трансформаторы (вычисление координат вершин):

• TransformerImage, TransformerStamp, TransformerTile, TransformerTileSprite

Текстуризаторы (управление привязкой текстур):

• TexturerImage, TexturerTileSprite

Фильтры (постобработка — см. filters-and-postfx.md):

• BaseFilter, BaseFilterShader
• FilterBarrel, FilterBlend, FilterBlocky, FilterBlur (варианты Low/Med/High)
• FilterBokeh, FilterColorMatrix, FilterCombineColorMatrix
• FilterDisplacement, FilterGlow, FilterGradientMap, FilterImageLight
• FilterKey, FilterMask, FilterNormalTools, FilterPanoramaBlur
• FilterParallelFilters, FilterPixelate, FilterQuantize
• FilterSampler, FilterShadow, FilterThreshold, FilterVignette, FilterWipe

Прочее:

• Camera, FillCamera, FillRect, FillPath, FillTri
• DrawLine, StrokePath, ShaderQuad
• ListCompositor, RebindContext, YieldContext
• DynamicTextureHandler

Расширение: Пользовательские узлы рендеринга

// Регистрация конструктора пользовательского узла:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);// Или добавление готового экземпляра узла:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

Новые игровые объекты

CaptureFrame

Захватывает текущее содержимое фреймбуфера в текстуру в той точке списка отображения, где он находится. Сам по себе ничего не рендерит. Только для WebGL.

// Все, что находится выше этого в списке отображения, будет захвачено:
const image1 = this.add.image(400, 300, 'background');// Включить использование фреймбуфера на камере:
this.cameras.main.setForceComposite(true);// Создать точку захвата:
const capture = this.add.captureFrame('myCapturedTexture');// Использование захваченной текстуры на другом объекте:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Добавление фильтров к наложению для искажения захваченной сцены

Важные детали:

• Требуется camera.setForceComposite(true) или контекст фреймбуфера (фильтры, DynamicTexture, камера с частичным альфа-каналом)
• Внутри контейнера с фильтрами захватывается только содержимое этого контейнера
• Установка visible = false останавливает захват
• Компоненты: BlendMode, Depth, RenderNodes, Visible

Источник: src/gameobjects/captureframe/CaptureFrame.js

Gradient

Отображает цветовые градиенты, прорисованные на GPU. Является производным от Shader. Поддерживает линейный, радиальный и другие режимы градиента с настраиваемым объектом ColorRamp, содержащим объекты ColorBand.

// Простой линейный градиент:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);// Сложный радиальный градиент с несколькими цветовыми полосами:
const halo = this.add.gradient({
   bands: [
        { start: 0.5, end: 0.6, colorStart: [0.5, 0.5, 1, 0], colorEnd: 0xffffff, colorSpace: 1, interpolation: 4 },
        { start: 0.6, end: 1, colorStart: 0xffffff, colorEnd: [1, 0.5, 0.5, 0], colorSpace: 1, interpolation: 3 }
    ],
    dither: true,
    repeatMode: 1,
    shapeMode: 2,       // радиальный
    start: { x: 0.5, y: 0.5 },
    shape: { x: 0.5, y: 0.0 }
}, 400, 300, 800, 800);// Анимация:
halo.offset = 0.1 * (1 + Math.sin(time / 1000));

Ключевые параметры:

• Конфигурация: GradientQuadConfig с параметрами bands, shapeMode, repeatMode, start, shape, dither
• Цвета задаются с помощью ColorRamp с объектами ColorBand (поддерживает HSV, различные режимы интерполяции)
• Вызов gradient.ramp.encode() после изменения данных градиента во время выполнения

Источник: src/gameobjects/gradient/Gradient.js

Объекты шума

Все типы шума наследуются от Shader и доступны только в WebGL. Доступно шесть вариантов:

// Базовый белый шум:
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);// Клеточный шум с настройками:
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
   noiseIterations: 3,
    noiseNormalMap: true    // вывод в виде карты нормалей для освещения
}, 200, 200, 256, 256);// Шум Simplex для естественных эффектов:
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // анимируйте этот параметр для эволюции
   noiseIterations: 4,
    noiseWarpAmount: 0.5,   // турбулентность
    noiseSeed: 42,
    noiseNormalMap: false
}, 300, 300, 256, 256);

Общие свойства для всех типов шума:

• noiseOffset — массив [x, y] для прокрутки узора
• noisePower — регулирует уровни выходного сигнала (большее значение подавляет высокие значения)
• noiseNormalMap — выходная карта нормалей (для интеграции с освещением)
• noiseIterations — уровень детализации (для типов cellular/simplex)

Математические эквиваленты: Phaser.Math.Hash(), Phaser.Math.HashCell(), Phaser.Math.HashSimplex()

Источник: src/gameobjects/noise/

SpriteGPULayer

Осуществляет рендеринг очень большого количества квадров (до миллионов) за один вызов рисования, сохраняя данные в статическом буфере GPU. Работает до 100 раз быстрее, чем отдельные спрайты. Только для WebGL.

const layer = this.add.spriteGPULayer(texture, size); // size = максимальное количество элементов// Добавление элементов (делайте это за один раз, а не постепенно):
const member = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);// Для эффективности при миллионах записей повторно используйте объект элемента:
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);// Включить освещение на слое:
layer.setLighting(true);

Ключевые детали:

• Только одна текстура (без мультиатласа), одно изображение на слой
• Члены поддерживают анимации типа твинов (затухание, отскок, волна, смена цвета), заданные при создании
• Обновление содержимого буфера требует значительных ресурсов — заполняйте его один раз и оставляйте без изменений
• Для пиксельной графики рекомендуется использовать текстуры размером, кратным двум, чтобы избежать видимых стыков
• Визуальное «удаление» элементов путем установки scaleX/scaleY/alpha в 0 (это позволяет избежать перестроения буфера)
• Компоненты: Alpha, BlendMode, Depth, ElapseTimer, Lighting, Mask, RenderNodes, TextureCrop, Visible

Источник: src/gameobjects/spritegpulayer/SpriteGPULayer.js

Новые компоненты

Полный справочник по компонентам: game-object-components.md

Компонент освещения

Заменяет подход версии 3, в котором назначался конвейер освещения. Только для WebGL.

// Подход v3:
sprite.setPipeline('Light2D');// Подход v4:
sprite.setLighting(true);// Самозатенение (имитирует тени на поверхности на основе яркости текстуры):
sprite.setSelfShadow(true, 0.5,1/3);
// Аргументы: enabled, penumbra (чем меньше, тем четче), diffuseFlatThreshold (0–1)// Использовать общеигровое значение по умолчанию для самозатенения:
sprite.setSelfShadow(null);  // считывается из config.render.selfShadow

Поддерживается в: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, TilemapGPULayer.

Примечание по пакетной обработке: освещение изменяет шейдер, что нарушает пакеты. Для наилучшей производительности группируйте освещённые объекты вместе, а неосвещённые — отдельно.

Источник: src/gameobjects/components/Lighting.js

Компонент RenderSteps

Позволяет внедрять пользовательскую логику в процесс рендеринга игрового объекта. Только для WebGL. Система Filters использует RenderSteps внутренне.

// Добавление пользовательского шага рендеринга:
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Пользовательская логика рендеринга здесь
    // Вызов следующего шага, когда все готово:
   var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

Ключевые моменты:

• Шаги хранятся в массиве _renderSteps и выполняются с помощью renderWebGLStep()
• Первый шаг запускается первым и отвечает за вызов последующих шагов
• Именно так фильтры откладывают и управляют потоком renderWebGL

Источник: src/gameobjects/components/RenderSteps.js

Компонент RenderNodes

Предоставляет на игровых объектах карты defaultRenderNodes, customRenderNodes и renderNodeData. См. раздел «RenderNodes» выше для ознакомления с использованием.

Источник: src/gameobjects/components/RenderNodes.js

TilemapGPULayer

Полное руководство по тайл-мапам: tilemaps.md

Высокопроизводительный рендеринг тайл-карты на базе GPU. Осуществляет рендеринг всего слоя в виде одного квадрата с помощью специализированного шейдера. Только для WebGL.

// Создание с помощью Tilemap с флагом gpu:
const map = this.make.tilemap({ key: 'level1' });
const tileset = map.addTilesetImage('tiles', 'tilesImage');
const gpuLayer = map.createLayer('Ground', tileset, 0, 0, true);  // последний аргумент: gpu = true

Возможности:

• Один набор плиток с одним текстурным изображением
• Максимум 4096x4096 плиток, до 2^23 уникальных идентификаторов плиток
• Поддерживается зеркальное отражение плиток и анимация
• Только ортогональные карты тайлов (без изометрических/гексагональных)
• Идеальная фильтрация текстур в режиме LINEAR (без швов между плитками)
• Стоимость рассчитывается за пиксель, а не за плитку — отсутствие потери производительности при большом количестве видимых плиток

Ограничения:

• Невозможно использовать несколько наборов тайлов
• Для обновления при редактировании требуется ручной вызов generateLayerDataTexture()
• Только ортогографический режим

Внутренние данные: Данные тайлов хранятся в текстуре (4 байта на тайл: 2 бита переворачивания, 1 бит анимации, 1 неиспользуемый бит, 28-битный индекс тайла). Данные анимации — в отдельной текстуре.

Источник: src/tilemaps/TilemapGPULayer.js

Подробные параметры настройки, таблицы справочника API и карты исходных файлов см. в справочном руководстве.