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 output location your asset manifest invite.config.ts - 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');
    });
  }
}

Alternative ways to check for assets loaded status

Asset loading is built-in to Dill Pixel during scene transitions, or during application bootstrap. However, there are a few alternative ways to check if an asset is loaded in Pixi.js:

1. Using Assets.cache.has()

import { Assets } from 'pixi.js';


// Check if an asset exists in the cache
const isLoaded = Assets.cache.has('myAssetKey');

2. Using Assets.get()

import { Assets } from 'pixi.js';


// Try to get the asset - returns undefined if not loaded
const asset = Assets.get('myAssetKey');
if (asset) {
  // Asset is loaded
  console.log('Asset is loaded!');
} else {
  // Asset is not loaded
  console.log('Asset is not loaded');
}

3. Checking for Specific Asset Types

import { Assets, Texture, Spritesheet } from 'pixi.js';


// For textures
function isTextureLoaded(key: string): boolean {
  const asset = Assets.get(key);
  return asset instanceof Texture;
}


// For spritesheets
function isSpriteSheetLoaded(key: string): boolean {
  const asset = Assets.get(key);
  return asset instanceof Spritesheet;
}

4. Safe Asset Access with Error Handling

function getLoadedAsset(key: string) {
  try {
    if (!Assets.cache.has(key)) {
      throw new Error(`Asset "${key}" not loaded into Pixi cache`);
    }
    return Assets.get(key);
  } catch (error) {
    console.error(`Failed to get asset: ${error.message}`);
    return null;
  }
}