Skip to content
dill pixel

Assets

Assets are the static resources that your game loads to run. These can be:

Asset Management

An asset manifest is a JSON file that describes the assets that will be used in your game. Dill Pixel uses Pixi’s AssetPack to manage assets. You can define the location your asset manifest should go in your vite.config.ts file - by default it will be generated in the public/assets.json file, and auto-loaded during bootstrap.

Required Assets

Your application can define required assets that will be loaded before any scenes are initialized. These can be configured in your application options:

import { createApplication } from 'dill-pixel';


const app = await createApplication({
  assets: {
    // Path to your asset manifest file
    manifest: './assets.json',


    // Assets to preload before the application starts
    preload: {
      // Individual assets
      assets: {
        logo: '/assets/logo.png',
        fonts: '/assets/fonts.css',
        ui: {
          src: '/assets/ui.svg',
          data: { parseAsGraphicsContext: true },
        },
      },
      // Asset bundles defined in your manifest
      bundles: ['common-ui', 'shared-sprites'],
    },


    // Assets to load in the background after the app starts
    background: {
      assets: {
        'level-music': '/assets/music.mp3',
      },
      bundles: ['background-content'],
    },


    // Optional Pixi.js asset initialization options
    initOptions: {
      // ... any Pixi.js Assets.init() options
    },
  },
});

You can listen for application-level asset loading events:

app.assets.onLoadStart.connect(() => {
  console.log('Started loading required assets');
});


app.assets.onLoadProgress.connect((progress) => {
  console.log(`Loading progress: ${progress * 100}%`);
});


app.assets.onLoadComplete.connect(() => {
  console.log('All required assets loaded');
});


// For background assets
app.assets.onBackgroundLoadStart.connect(() => {
  console.log('Started loading background assets');
});


app.assets.onBackgroundAssetLoaded.connect((asset) => {
  console.log('Background asset loaded:', asset);
});


app.assets.onBackgroundBundlesLoaded.connect(() => {
  console.log('All background bundles loaded');
});

Scenes can define their assets using the assets export, which also supports both preloaded and background-loaded assets:

export const assets = {
  // Assets that must be loaded before the scene starts
  preload: {
    // Individual assets
    assets: {
      player: '/assets/player.png',
      // Support for asset objects with additional options
      background: {
        src: '/assets/background.png',
        // For SVGs, you can enable parsing as graphics
        data: { parseAsGraphicsContext: true },
      },
    },
    // Asset bundles (defined in your asset manifest)
    bundles: ['level-1', 'ui-elements'],
  },
  // Assets that will load after the scene is running
  background: {
    assets: {
      'level-2': '/assets/level-2.png',
      'level-3': '/assets/level-3.png',
    },
    bundles: ['level-2-assets'],
  },
};


// Control whether assets are automatically unloaded when leaving the scene
export const autoUnloadAssets = true;

Asset Loading Events

You can listen for background asset loading events in your scene:

class MyScene extends Scene {
  initialize() {
    // Listen for background asset loading events
    this.app.assets.onBackgroundLoadStart.connect(() => {
      console.log('Background assets started loading');
    });


    this.app.assets.onBackgroundAssetLoaded.connect((asset) => {
      console.log('Background asset loaded:', asset);
    });


    this.app.assets.onBackgroundBundlesLoaded.connect(() => {
      console.log('All background bundles loaded');
    });
  }
}