Assets

Gli asset possono essere archiviati localmente all'interno del progetto o ospitati online. Gli asset utilizzati frequentemente — come gli sprite dei personaggi, gli sfondi e la musica di sottofondo — è meglio tenerli in locale. Gli asset utilizzati una sola volta o i file opzionali di grandi dimensioni sono meglio ospitati online. Ogni approccio presenta dei compromessi:

Asset locali

Per salvare e utilizzare asset localmente, puoi usare qualsiasi cartella — non ci sono restrizioni. Tuttavia, si raccomanda di utilizzare la cartella src/assets. All'interno di questa cartella puoi creare sottocartelle per organizzare meglio i tuoi asset.

PixiJS AssetPack è già preconfigurato nei template di progetto di Pixi’VN tramite l'integrazione con Vite.js — automatizzando l'elaborazione e l'ottimizzazione dei tuoi asset così da permetterti di concentrarti sulla costruzione del progetto.

Durante lo sviluppo (vite dev) monitora la cartella src/assets per le modifiche e le elabora al volo. Durante il build di produzione (vite build) esegue un passaggio di ottimizzazione completo prima del bundling.

Le ottimizzazioni che applica includono:

• Compressione — riduce le dimensioni dei file per un caricamento più rapido.
• Conversione di formato — converte le immagini in formati moderni (es. WebP, AVIF) quando supportati.
• Atlanti di texture — combina più immagini piccole in un unico sprite sheet per ridurre le chiamate di disegno.

Una volta completata l'elaborazione, genera file ottimizzati in public/assets e il file src/assets/manifest.gen.json, che contiene l'elenco di tutti i bundle di asset e i loro percorsi. Questi output vengono poi utilizzati da PixiJS per caricare gli asset in modo efficiente.

{
    "bundles": [
        {
            "name": "audio",
            "assets": [
                {
                    "alias": "bgm_cheerful",
                    "src": "./assets/audio/bgm_cheerful.wav"
                },
                {
                    "alias": "sfx_whoosh",
                    "src": "./assets/audio/sfx_whoosh.wav"
                }
            ]
        },
        {
            "name": "mainmenu",
            "assets": [
                {
                    "alias": "background_main_menu",
                    "src": "./assets/mainmenu/background_main_menu.png"
                }
            ]
        },
        {
            "name": "start",
            "assets": [
                {
                    "alias": "bg01-hallway",
                    "src": "./assets/start/bg01-hallway.webp"
                }
            ]
        },
        {
            "name": "mc",
            "assets": [
                {
                    "alias": "mc-neutral",
                    "src": "./assets/mc/mc-neutral.png"
                }
            ]
        }
    ]
}

Hosting degli asset

Puoi salvare i tuoi asset online. È una buona opzione se vuoi risparmiare spazio nel progetto o se vuoi creare un gioco giocabile online senza la necessità di scaricarlo prima. Puoi utilizzare qualsiasi servizio cloud che ti permetta di caricare file e generare un URL pubblico (devi assicurarti che il servizio cloud che stai usando consenta le richieste CORS).

Ecco alcune opzioni popolari per l'hosting online degli asset:

Una volta che i tuoi asset sono pronti, devi definire manualmente quali di essi il gioco può usare e come vengono raggruppati in bundle.

Tutti i template di Pixi’VN includono un file src/assets/index.ts che puoi modificare per registrare i tuoi asset:

import generatedManifestJson from "@/assets/manifest.gen.json";
import { AUDIO_BUNDLE_NAME } from "@/constants";
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: [
        ...generatedManifestJson.bundles,
        {
            name: AUDIO_BUNDLE_NAME,
            assets: [
                {
                    alias: "bgm_cheerful",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/audio/bgm_cheerful.wav",
                },
                {
                    alias: "sfx_whoosh",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/audio/sfx_whoosh.wav",
                },
            ],
        },
        // 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",
                },
            ],
        },
        // characters
        {
            name: "mc",
            assets: [
                {
                    alias: "mc-neutral",
                    src: "https://raw.githubusercontent.com/user/project/refs/heads/main/characters/mc-neutral.png",
                },
            ],
        },
    ],
};

Altre funzionalità