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

Особенно для игр с онлайн-ресурсами соблюдение правил загрузки крайне важно, чтобы избежать долгого ожидания и обеспечить плавный игровой процесс.

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

Использование псевдонимов для загрузки ресурсов

Для загрузки ресурса всегда используйте его псевдоним — уникальный идентификатор, заданный в манифесте или при регистрации ресурса. Использование пути src напрямую настоятельно не рекомендуется: это привязывает код к расположению файла, делая его уязвимым при изменении путей или хостинга.

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

const texture = await Assets.load("eggHead");

{
    "bundles": [
        {
            "name": "default",
            "assets": [
                {
                    "alias": "eggHead",
                    "src": "./assets/eggHead.png"
                }
            ]
        }
    ]
}

Организация ресурсов в бандлы

Рекомендуемая практика — группировать ресурсы в бандлы, а не регистрировать их по отдельности. Бандлы позволяют загружать целый набор ресурсов одним вызовом и откладывать загрузку до того момента, когда ресурсы действительно потребуются.

Рекомендуется называть каждый бандл по месту его использования. Например:

• используйте id нарративного узла (label) (например, startLabel.id) как имя бандла для ресурсов, используемых в конкретном нарративном узле (label)
• используйте путь маршрута (например, "/") как имя бандла для ресурсов, используемых на соответствующем экране, например главном меню

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

import { startLabel } from "@/content/labels/start.label";
import type { FileRouteTypes } from "@/routeTree.gen";
import type { AssetsManifest } from "@drincs/pixi-vn";

export const manifest: AssetsManifest = {
    bundles: [
        // screens
        {
            // main menu
            name: "/" as FileRouteTypes["fullPaths"],
            assets: [
                {
                    alias: "background_main_menu",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/main-menu.png",
                },
            ],
        },
        // labels
        {
            name: startLabel.id,
            assets: [
                {
                    alias: "bg01-hallway",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/breakdown/bg01-hallway.webp",
                },
            ],
        },
    ],
};

Когда загружать ресурсы

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

Ниже перечислены наиболее распространённые и рекомендуемые моменты для предварительной загрузки ресурсов: