AssetPack

AssetPack is a configurable asset pipeline designed for the web. It allows you to transform, combine, and compress assets to optimize them for web performance.

Key features include:

• Asset Optimization: Transform and optimize any asset type for web use.
• Framework Agnostic: Works with any web framework or engine, including PixiJS, Three.js, and Phaser.
• Plugin-based Architecture: Uses a plugin system that allows developers to create custom plugins for specialized asset processing tasks.

AssetPack uses a pipeline (or "pipe") of plugins to process and optimize assets. Each plugin performs a specific task, such as compression, conversion, or manifest generation.

Important: The order of plugins in your configuration is critical because each plugin processes the asset in sequence, passing the result to the next plugin in the chain.

Tags are used to instruct plugins on which assets to process. They are typically added to folder or file names. Each plugin has its own specific set of tags.

Built-in Tags

• {copy}: Forces an asset to be copied to the output directory without any processing.
• {ignore}: Ensures the asset is neither processed by AssetPack nor copied to the output directory.

Tag Syntax

• Multiple Tags: You can apply multiple tags to a single asset: asset{tag1}{tag2}.
• Data Tags: You can append data to a tag: asset{tag1=myData}.
• Multiple Data Values: You can provide multiple values for a single tag: asset{tag1=100&200}.
• Data Tags for Manifests: Some plugins use data tags to pass properties to the generated manifest. For example, the webfont plugin uses a family tag to specify the font family name.

You can control how assets are treated in the manifest by applying tags to your folders or files:

• m: Applied to a folder. Generates a bundle entry in the manifest file for the contents of that folder.
• mIgnore: Applied to both folders and files. Ignores the item from the manifest file entirely.

AssetPack provides sdfFont() and msdfFont() pipes to generate signed distance field (SDF) and multi-channel signed distance field (MSDF) fonts from ttf files. These are useful for high-quality text rendering at various scales.

Add the desired pipe to your configuration's pipes array.

import { sdfFont, msdfFont } from "@assetpack/core/webfont";

export default {
  ... 
  pipes: [
    ... 
    sdfFont(),
    msdfFont(),
  ],
};

The spineAtlasMipmap plugin generates multiple resolutions (mipmaps) for images in a Spine atlas. This is useful for optimizing graphics across different screen sizes and device capabilities.

Important: This plugin must be used in conjunction with the mipmap plugin to ensure that both the atlas file and the images are mipped. You should pass the same options to both plugins.

import { mipmap } from "@assetpack/core/image";
import { spineAtlasMipmap } from "@assetpack/core/spine";

const options = {
  template: "@%%x",
  resolutions: { default: 1, low: 0.5 },
  fixedResolution: "default",
};

export default {
  // ...
  pipes: [
    // ...
    mipmap(options),
    spineAtlasMipmap(options),
  ]
};

The spineAtlasCompress plugin uses the Sharp library to compress images within a Spine atlas into formats like JPEG, PNG, WebP, AVIF, or various texture compression standards (ASTC, ETC, ETC2, BCn, and Basis).

Important: This plugin must be used in conjunction with the compress plugin to ensure that both the atlas file and the associated images are compressed. You should pass the same options to both plugins to maintain consistency.

import { compress } from "@assetpack/core/image";
import { spineAtlasCompress } from "@assetpack/core/spine";

const options = {
  jpg: {},
  png: { quality: 90 },
  webp: { quality: 80, alphaQuality: 80 },
  avif: false,
  bc7: false,
  astc: false,
  basis: false,
  etc: false
};

export default {
  // ...
  pipes: [
    // ...
    compress(options),
    spineAtlasCompress(options),
  ]
};

The webfont() pipe converts ttf, otf, woff, and svg files into woff2 webfonts.

To use this, add webfont() to your configuration's pipes array. You can control which files are processed using asset tags.

import { webfont } from "@assetpack/core/webfont";

export default {
  ... 
  pipes: [
    ... 
    webfont(),
  ],
};

AssetPack requires a configuration file named .assetpack.js in your project root. This file must export a default object defining the asset entry point, the output directory, and the list of pipes (plugins) to run.

Basic configuration structure:

• entry: The directory containing your raw assets.
• output: The directory where optimized assets will be written.
• pipes: An array of plugins/transformations to apply.

// .assetpack.js
export default {
    entry: './raw-assets',
    output: './public/assets',
    pipes: [],
};

The texturePacker plugin is an AssetPack plugin that uses the sharp library to generate texture atlases. It is specifically designed to work with the spritesheet format used by PixiJS.

Note: If you are using the mipmap plugin, you should pass the same options to texturePacker as you do to mipmap to ensure consistency.

import { texturePacker } from "@assetpack/core/texture-packer";

export default {
  ... 
  pipes: [
    ... 
    texturePacker({
      texturePacker: {
        padding: 2,
        nameStyle: "relative",
        removeFileExtension: false,
      },
      resolutionOptions: {
        template: "@%%x",
        resolutions: { default: 1, low: 0.5 },
        fixedResolution: "default",
        maximumTextureSize: 4096,
      },
    })
  ]
};

The cacheBuster plugin ensures that assets are correctly updated by generating unique hashes and appending them to file names. This forces browsers to re-download assets when they change, bypassing stale cached versions.

Important: The cacheBuster pipe must be added to your pipeline after any plugins that generate files.

// assetpack.config.ts
import { cacheBuster } from "@assetpack/core/cache-buster";

export default {
  // ...
  pipes: [
    // ...
    // make sure these pipes are added after plugins that generate files
    cacheBuster(),
  ],
};