ayebear / pack

Simple, multi-threaded texture packer in Go

pack

Simple, multi-threaded texture packer in Go

Native CLI Usage

Build

go build

Run

./pack -in=images -out=sheets -name=textures

For info on more flags, run:

./pack -h

JS Usage

Install

Yarn

yarn add --dev @ayebear/pack

NPM

npm i -D @ayebear/pack

Run

Run with JS wrapper (slower)

yarn run pack -h

Run natively (faster)

./node_modules/@ayebear/pack/pack -h

Client usage

Pixi.js v6

With static files

Pack outputs a single json file along with (potentially) multiple png files. A pixi.js plugin is included with pack, to load this json file and all associated images in parallel.

import { Loader } from '@pixi/loaders'
import { PackSpritesheetLoader } from '@ayebear/pack'

Loader.registerPlugin(PackSpritesheetLoader)
Loader.shared.add('images/textures.json').load(...)

With bundled files

If you'd like to avoid using static files, and want to "properly" bundle the images and metadata, you can use the loadSheets function. The imports for sheetData and sheets might look a bit different depending on your bundler - in this example, parcel v2 is being used:

import { Loader } from '@pixi/loaders'
import { loadSheets } from '@ayebear/pack'
import sheetData from 'sheets/textures.json'
import * as sheets from 'sheets/*.png'

// Globbing only gives the "*" part, but we need full path
// to match up with sheetData keys
const images = {}
for (const key in sheets) {
    images[`sheets/${key}.png`] = sheets[key]
}
loadSheets(Loader.shared, sheetData, images).load(...)

About

Pack doesn't do any complicated, slow, puzzle-fitting of sprites. It just bins sprites based on size into separate sprite sheets, in left-to-right grid order. It does this making balanced use of multi-threading to achieve very high performance.

Tested in a real-world project with 300+ sprites. Pack produced 10 sprite sheets in just ~65ms.

pack's Issues

Refactor into multiple files

Errors loading images still being written to

Continue retrying when an image fails to open, for that specified amount of time. Default should be 0 (no retries). This should help improve reliability when saving images while pack is being run automatically by a file watcher. If there's still more issues after this, then look into making a more perfect solution (in a new issue) which might involve checking open file handles for writing.

Handle padding (edge repeats)

Implement edge pixel repeats, to avoid sub-pixel issues between sprites. Use the existing "padding" param - it is better to solve this issue with edge repeats over actual transparent padding. Transparent padding can cause transparent pixels to bleed into edges of tile sprites, causing visual glitches. So, there isn't a need for a 2nd option for this IMHO, and I'd like to keep the number of options down to a minimum for whatever is absolutely necessary to customize. Having this feature customizable means it will support no-AA up to 16x AA, or other configurations. A padding value of 0 means no edge-repeating.

Example of a 4x4 sprite:

CEEC
EMME
EMME
CEEC

What it looks like with a padding value of 2:

CCCEECCC
CCCEECCC
CCCEECCC
EEEMMEEE
EEEMMEEE
CCCEECCC
CCCEECCC
CCCEECCC

Notice how the padding is a radius value. Just 1 padding will add 1 thickness of border around all edges. The corner pixels should be repeated for the entire extended corner blocks. If any edge or corner pixels are transparent, these will be repeated as expected as well.

Improve integration with pixi.js and modern bundlers (parcel v2/webpack)

Remove the need for static files (normal relative paths to json and images). Have pack generate a .js file directly as a "client" that imports all the spritesheet images and have the metadata set in the code. Each time the input sprites are changed, pack will re-generate the spritesheet images and .js file.

Support automatic splitting

If a sheet size limit param is specified, split textures into multiple sheets. Ideally there would be a prioritization algorithm that puts images from the same directory into the same sheets. Each directory level up would be a secondary priority. There would still be a sort which would keep the output completely deterministic between runs as long as the input doesn't change.

Param example: -maxSize=1024. This would set both the max width and height to 1024 pixels.

Upgrade resource loader middleware to pixi.js v6

Can keep all loader versions. Default will be latest, but could just import the specific version you need. Update docs on how to use this.