Phaser.js: всё об играх и разработке

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

При создании игровых интерфейсов, инвентаря или мини-карт часто возникает задача вписать изображение в заданные рамки. Ручной подбор масштаба через `setScale` — это долго и неточно. Метод `setDisplaySize` решает эту проблему, автоматически рассчитывая нужный масштаб под целевые размеры в пикселях. В этой статье разберем, как им пользоваться для точного позиционирования графики.

Версия 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.image('frame', 'assets/pics/scrollframe.png');
        this.load.image('pic', 'assets/pics/cougar-face-of-nature.png');
    }

    create ()
    {
        this.add.image(0, 0, 'frame').setOrigin(0);

        //  setDisplaySize will adjust the scale of an image to make it fit the given pixel dimensions:

        this.add.image(32, 32, 'pic').setOrigin(0).setDisplaySize(352, 240);
    }
}

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

const game = new Phaser.Game(config);

В чем проблема ручного масштабирования

Классический способ изменить размер спрайта или изображения — использовать метод setScale. Он умножает исходные размеры текстуры на заданный множитель.

sprite.setScale(0.5, 0.5);

Чтобы вписать изображение в область 352x240 пикселей, вам нужно знать исходный размер текстуры, затем вычислить коэффициент для ширины и высоты. Это лишние расчеты в коде. setDisplaySize делает это за вас.

Работа метода setDisplaySize

Метод setDisplaySize(width, height) принадлежит любому игровому объекту, наследующему от Phaser.GameObjects.Image или Phaser.GameObjects.Sprite. Он автоматически вычисляет и применяет значения масштаба по осям X и Y, чтобы итоговый размер объекта в пикселях стал равен заданным аргументам.

this.add.image(32, 32, 'pic').setOrigin(0).setDisplaySize(352, 240);

В данном примере изображение с ключом 'pic' будет отрисовано с такими значениями scaleX и scaleY, что его ширина станет 352 пикселя, а высота — 240, независимо от исходного разрешения загруженной текстуры. Важно: точка преобразования (origin) установлена в (0, 0) (левый верхний угол), поэтому масштабирование происходит относительно этой точки, и левый верхний угол изображения останется в координатах (32, 32).

Практический пример: Картинка в рамке

Рассмотрим код из примера. Сначала загружается изображение рамки ('frame') и основная картинка ('pic').

preload ()
{
    this.load.setBaseURL('https://raw.githubusercontent.com/phaserjs/examples/master/public/');
    this.load.image('frame', 'assets/pics/scrollframe.png');
    this.load.image('pic', 'assets/pics/cougar-face-of-nature.png');
}

В методе create сначала добавляется рамка в начало координат сцены. Затем добавляется основное изображение. Ключевая строка — вызов setDisplaySize(352, 240). Размеры 352x240 подобраны так, чтобы картинка идеально разместилась внутри видимой области загруженной рамки, с учетом отступа в 32 пикселя от ее края.

create ()
{
    this.add.image(0, 0, 'frame').setOrigin(0);
    this.add.image(32, 32, 'pic').setOrigin(0).setDisplaySize(352, 240);
}

Таким образом, мы гарантированно и точно размещаем контент внутри UI-элемента без каких-либо предварительных вычислений размеров исходной текстуры.

Отличия от setScale и setSize

Важно не путать три метода: - setScale(factorX, factorY) — меняет масштаб. - setSize(width, height) — меняет **прямоугольник взаимодействия** (hit area) объекта, не влияя на его визуальный размер. Используется для физических тел или зон ввода. - setDisplaySize(width, height) — меняет **визуальный размер** объекта в пикселях, автоматически подстраивая его масштаб.

setDisplaySize — это ваш инструмент, когда вы работаете с целевыми пиксельными размерами из дизайна, а не с относительными коэффициентами.

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

Метод setDisplaySize — это мощный и удобный способ контролировать визуальный размер игровых объектов, оперируя понятными пиксельными значениями. Он незаменим для создания интерфейсов, галерей или любого контента, который должен точно вписываться в заданные области. Попробуйте поэкспериментировать: создайте интерфейс инвентаря с ячейками фиксированного размера и используйте setDisplaySize, чтобы автоматически подгонять в них иконки предметов разного исходного размера.