pixi-tileset-loader

Webpack loader for generating tilesets for PIXI.js

Install

npm install pixi-tileset-loader -D

Usage

1. Add a .tileset (or other filename) file in frames directory

animation
├── .tileset
├── 001.png
├── 002.png
└── 003.png

2. See Image processing params to configure .tileset in YAML format

skip: 1
colors: 16
scale: 0.5

3. Add pixi-tileset-loader in webpack.config.js:

{
  test: /\.tileset/i,
  use: [
    {
      loader: 'pixi-tileset-loader',
      options: {
        process: true,
        mode: 'file',
        output: './output',
        name: '[name]_[hash:6].[ext]',
        limit: false,
        outputPath: 'res'
        output: 'game/images',
        // image: {
        //   outputPath: 'res',
        //   publicPath: './'
        // },
        // json: {
        //   outputPath: 'res',
        //   publicPath: './res'
        // }
      }
    }
  ]
}

4. import or require the .tileset file in your module

import tilesetAnimationJSON from './resources/animation/.tileset';
// Will get a JSON file path in return，and the image path will be replaced in JSON file

Processing

1. Read from cache to know weather images and tileset are change or not
2. Spritesheet：genarate PNG and JSON files using spritesheet.js
3. Image optimizing：use node-pngquant to reduce colors amount of PNG image
4. Write the PNG and JSON files into game/images directory (specified by query.output)
5. Build PNG and JSON files in example/output directory into dist (specified by output.path in webpack config) by url-loader. This will replace meta.image in JSON with path or base64

example
└── resources
│   ├── animation # where source images are stored
│   │   ├── .tileset
│   │   ├── 001.png
│   │   ├── 002.png
│   │   └── 003.png
│   └── index.js
├── output # where JSON and image file are stored after process
│   ├── tileset-animation.json
│   └── tileset-animation.png
└── dist # final built result
    ├── main.js
    └── res
        ├── tileset-animation_1512a1.json
        └── tileset-animation_eee48e.png

System dependencies

First to ensure these packages installed in system:

• ImageMagick: identify and convert command are required to get image information and resize image
• pngquant：pngquant command is required to reduce colors of PNG image

Options

• options.output: the directory to cache PNG and JSON file, we recommend specifying a source code directory and commit this directory as well. The cache will be disabled when not specified
• options.mode: how webpack will build tileset JSON. file by default to generate JSON file; inline to generate JSON module source code; none to do nothing
• options.process: to process frames or not. It will directly read JSON and PNG cache from the directory where output option specified to perform the build when false
• options.cacheable: cache process result or not. false by default, true to read image and JSON files from options.output directory which are built already, if source image files and tileset file are not changed
• options.name: url-loader name option for image and JSON files
• options.outputPath: url-loader outputPath option for image and JSON files
• options.publicPath: url-loader publicPath option for image and JSON files
• options.image: url-loader webpack loader options for PNG file
• options.json: url-loader webpack loader options for JSON file. Not required when options.mode specified as inline
• options.verbose: log the entire error stack or not, default is false

The option specified in options will be overwrite by the same option specified in options.image or options.json. When options.process is specified false, the 1 - 4 steps of processing will be skipped, PNG and JSON cache will be directly read from the directory query.output specified, and webpack will emit these files via url-loader , but a webpack warning will be emitted as well. This ensure the build in remote server, where ImageMagick or pngquant package is missing. We recommend to specify options.cacheable as true to improve webpack building performance, by skipping 2 - 4 steps of processing, and avoid unwanted image and json file change due to different system environment(e.g. different version of ImageMagick) when source images and tileset file are not changed options.resource can be specified 'window.baseRoot + "$url"' for example, baseRoot is a path similar to /path/to/image. Used to concat image path when code running in browser

Image processing params

• trim：trim the whitespace in PNG image or not, default is false
• scale: scale factor, based on imagemagick-stream to reduce the size of PNG image, default is 1
• padding: padding in the spritesheet, default is 10
• skip：ignore N frames in every N + 1 frames, default is 0
• colors：colors amount for pngquant, default is 0
• files: file paths in [path]-[name] format, frames will be read from the directory files specified instead of the directory where .tileset is in
• excludes: the file paths to exclude
• interpolate: string template to specify the prefix, such as $name$-tileset and tileset

files specifies the paths relative to the directory where .tileset is in, for example:

files:
  ../animation-a/001.png: animation-a
  ../animation-b/001.png: animation-b
  ../animation-c/001.png: animation-c