Binpacker

CLI tool for packing multiple files into a single Binpack binary in order to save network requests in the browser. You can use Binpacker as an efficient replacement for spritesheets.

Inspired by GLB File Format Specification, MM.Loader, MM.Packer, Magipack.js and this Twitter thread.

Live demo

Live demo.

Installation

Make sure you have Node.js installed.

$ npm install -g --save @timvanscherpenzeel/binpacker

CLI Usage

$ node ./bin/binpacker.js -i ./input -o ./output/example.binpack -vb

$ node ./bin/binpacker.js -i ./input/manifest.json -o ./output/example.binpack -vb

Manifest structure

{
  "path": "./input/",
  "manifest": [
    {
      "src": "icon-twitter.svg"
    },
    {
      "src": "spritesheet (2).json"
    },
    {
      "src": "texture.jpg"
    }
  ]
}

File structure

A .binpack file has the following structure (very similar to the GLB File Format Specification):

Figure from the GLB File Format Specification.

Endianness

Binpack is little endian.

12-byte header

The 12-byte header consists of three 4-byte entries:

uint32 magic
uint32 version
uint32 length

• magic equals 0x504e4942. It is ASCII string BINP, and can be used to identify data as Binpack.

• version indicates the version of the Binpack. This specification defines version 1.

• length is the total length of the Binpack file, including Header and all Chunks, in bytes.

JSON chunk header

A single JSON chunk header

The JSON chunk header has a field that marks the length of the JSON chunk (uint32 chunkLength) and a type (uint32 chunkType) marked JSON in ASCII.

JSON chunk

A single JSON chunk

The JSON chunk (ubyte[] chunkData) contains a stringified JSON description of the processed files: name, bufferStart, bufferEnd and mimeType. The difference between bufferStart and bufferEnd describe the length of the file. This length is used to extract the correct amount of bytes per file from the binary chunk that follows next.

Binary chunk header

A single binary chunk header

The binary chunk header has a field that marks the length of the binary chunk (uint32 chunkLength) and a type (uint32 chunkType) marked BIN in ASCII.

Binary chunk

A single binary chunk

The binary chunk (ubyte[] chunkData) contains a single Uint8Array typed array buffer that has been constructed out of concatenated files. Using the data described in the JSON chunk one can correctly extract the file from the binary chunk.

Flags

Required

-i, --input [example: ./input (glob) or ./input/manifest.json (manifest)] [required]
-o, --output [example: ./output/example.binpack] [required]

Optional

-vb, --verbose [true / false, default: false] [not required]

License

My work is released under the MIT license.