Pixi'VN - Управление ресурсами

Организация, привязка и загрузка ресурсов (изображений, звуков, видео) в Pixi'VN с помощью псевдонимов и манифестов.

Редактировать на GitHub Перевести на Crowdin Спросить ChatGPT Patreon

Чтобы загружать и управлять ресурсами (изображениями, гифками, видео и т. д.) вам необходимо использовать Assets. Assets — это класс с множеством функций, который принадлежит библиотеке PixiJS. Для получения дополнительной информации, ознакомьтесь здесь.

Во всех функциях Pixi'VN можно напрямую использовать URL-адрес изображения, даже если он не определен в Assets.

let alien1 = await showImage("alien", "https://pixijs.com/assets/eggHead.png");

Этот метод имеет несколько недостатков:

Изменение URL-адреса ресурса из одной версии в другую может привести к несовместимости.
The player will have to wait for a short loading time every time they press "continue" and a step is started that uses assets.
Запись всего URL в коде увеличит его длину и сделает менее читабельным.

По этим причинам рекомендуется работать с ресурсами следующим образом.

Инициализация матрицы ресурсов в начале проекта

Инициализация матрицы ресурсов в начале проекта позволяет ссылаться на ресурсы по уникальному псевдониму без необходимости использовать URL/путь. Используя псевдоним, вы можете изменить URL-адрес ресурсов, не заботясь о совместимости версий.

Для этого рекомендуется создать асинхронную функцию defineAssets, которая будет вызываться при старте проекта. В функции defineAssets используйте Assets (например, Assets.add, Assets.addBundle и Assets.init) для назначения псевдонимов URL. Более подробную информацию о них можно найти здесь, чтобы назначить псевдоним каждым ресурсам.

import { Assets, sound } from "@drincs/pixi-vn";
import manifest from "../assets/manifest";

export async function defineAssets() {
    // manifest
    Assets.init({ manifest });
    // single asset
    Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
    Assets.add({ alias: 'flowerTop', src: "https://pixijs.com/assets/flowerTop.png" })
    Assets.add({ alias: 'video', src: "https://pixijs.com/assets/video.mp4" })
    sound.add('bird', 'https://pixijs.io/sound/examples/resources/bird.mp3');
    sound.add('musical', 'https://pixijs.io/sound/examples/resources/musical.mp3');
    // bundle
    Assets.addBundle('liam', {
        "liam-head": 'liam_head.png',
        "liam-body": 'liam_body.png',
        "liam-arms": 'liam_arms.png',
    });
}

Загрузка ресурсов

По умолчанию ресурсы загружаются только при необходимости.

Но если ресурсы сохранены не локально, а на "хостинге ресурсов", их загрузка может занять некоторое время. Это означает, что начало шага может быть не мгновенным. So, after starting the execution of the next step (for example with the "next" button), the player may have to wait some time to "view" the changes and be able to run another step.

Выполнение этих загрузок на каждом шаге может раздражать игрока, даже если они очень короткие.

Чтобы решить эту проблему, разработчик может сгруппировать несколько загрузок на определенном этапе игры. Таким образом, игрок будет испытывать не постоянные загрузки, а меньшие, пусть и более длительные.

Вот различные способы загрузки ресурсов:

Загрузка ресурсов при запуске проекта

Возможно загружать ресурсы при запуске проекта, прежде чем игрок сможет взаимодействовать с проектом, например при загрузке экрана. Рекомендуется использовать эту процедуру только для ресурсов, используемых на главной странице или часто используемых, и не превышающих 100МБ.

Для этого вы должны использовать функцию Assets.load и дождаться ее завершения (с помощью await), когда проект запустится. Подробнее о функции Assets.load вы можете узнать здесь.

import { Assets, sound } from "@drincs/pixi-vn";
import manifest from "../assets/manifest";

export async function defineAssets() {
    // manifest
    Assets.init({ manifest });
    // single asset
    Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
    Assets.add({ alias: 'flowerTop', src: "https://pixijs.com/assets/flowerTop.png" })
    Assets.add({ alias: 'video', src: "https://pixijs.com/assets/video.mp4" })
    sound.add('bird', 'https://pixijs.io/sound/examples/resources/bird.mp3');
    sound.add('musical', 'https://pixijs.io/sound/examples/resources/musical.mp3');
    // bundle
    Assets.addBundle('liam', {
        "liam-head": 'liam_head.png',
        "liam-body": 'liam_body.png',
        "liam-arms": 'liam_arms.png',
    });

    // The game will not start until these assets are loaded.
    await Assets.load('eggHead') 
    await Assets.loadBundle('liam') 
}

Загрузка ресурсов в фоновом режиме при запуске проекта

Возможно загружать ресурсы в фоновом режиме при запуске проекта, что сокращает время загрузки при запуске проекта. Рекомендуется не превышать размер 2ГБ.

Для этого можно использовать функцию Assets.backgroundLoad при запуске проекта. Подробнее о функции Assets.backgroundLoad вы можете узнать здесь.

import { Assets, sound } from "@drincs/pixi-vn";
import manifest from "../assets/manifest";

export async function defineAssets() {
    // manifest
    Assets.init({ manifest });
    // single asset
    Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
    Assets.add({ alias: 'video', src: "https://pixijs.com/assets/video.mp4" })
    sound.add('bird', 'https://pixijs.io/sound/examples/resources/bird.mp3');
    sound.add('musical', 'https://pixijs.io/sound/examples/resources/musical.mp3');
    // bundle
    Assets.addBundle('liam', {
        "liam-head": 'liam_head.png',
        "liam-body": 'liam_body.png',
        "liam-arms": 'liam_arms.png',
    });

    // The game will not start until these assets are loaded.
    await Assets.load('eggHead')

    // The game will start immediately, but these assets will be loaded in the background.
    Assets.backgroundLoadBundle(['liam']); 
    // Load an individual asset in the background
    Assets.backgroundLoad({ alias: 'flowerTop', src: 'https://pixijs.com/assets/flowerTop.png' }); 
}

Загрузка ресурсов при запуске части

ink

You can use this method with the ink syntax. See more here.

Чтобы сгруппировать загрузку от одного шага до другой части в одну загрузку, возможно загрузить все или часть ресурсов, используемых частью, до её запуска. Поскольку это не уменьшает время ожидания для игрока, а добавляет его к одной загрузке, рекомендуется загружать их в фоновом режиме.

Для этого вы должны использовать функцию Assets.load и дождаться ее завершения (с помощью await), когда часть запустится. Вы будете использовать функцию onLoadingLabel.

Чтобы код был чище, рекомендуется определить в манифесте пакет с id, соответствующим id части, и определить в нем ресурсы, которые будут использоваться в этой части.

labels/startLabel.ts

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

const startLabel = newLabel("start", [
    () => {
        await showImage("eggHead")
    },
    () => {
        await showImage("flowerTop")
    },
], {
    onLoadingLabel: async (_stepId, label) => { 
        // The label will not start until these assets are loaded.
        await Assets.loadBundle(label.id) 
    } 
})
export default startLabel;

import { AssetsManifest } from "@drincs/pixi-vn";
import startLabel from "../labels/startLabel";

/**
 * Manifest for the assets used in the game.
 * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
 */
const manifest: AssetsManifest = {
    bundles: [
        // labels
        {
            name: startLabel.id,
            assets: [
                {
                    alias: "eggHead",
                    src: "https://pixijs.com/assets/eggHead.png",
                },
                {
                    alias: "flowerTop",
                    src: "https://pixijs.com/assets/flowerTop.png",
                },
            ],
        },
    ],
};
export default manifest;

Загрузка ресурсов в фоновом режиме при запуске части

Already present in the templates

In all templates, when a label is started, the background loading of the bundle (if it exists) with the id corresponding to the label will be started. Поэтому достаточно создать манифест с пакетом для каждой части. Вот реализация, используемая для этого:

main.ts

import { Assets, Game } from "@drincs/pixi-vn";

Game.onLoadingLabel((_stepId, { id }) => Assets.backgroundLoadBundle(id));

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

Для этого можно использовать функцию Assets.backgroundLoad при запуске части. Подробнее о функции Assets.backgroundLoad вы можете узнать здесь. И вы будете использовать функцию onLoadingLabel.