🗃️ TextureUnpacker

Overview

TextureUnpacker is a Node.js tool written in TypeScript which can be used to unpack .png sprite sheets packed with TexturePacker into separate sprites if provided with corresponding .json or .plist data file.

Supported data formats:

• JSON (Array)
• JSON (Hash)
• Phaser (JSONArray)
• Phaser (JSONHash)
• Phaser 3
• PixiJS
• Cocos2d-x
• Cocos2d
• Cocos2d v2 (old, CocoStudio)

Contributing

If you have noticed a bug or would like us to support additional data formats, feel free to open an issue describing said bug or requested format (and provide matching sprite sheet and data files), or even better open a pull request with code changes which fixes the bug or adds support for new data format.

Dependencies

• sharp
• plist.js
• TypeScript
• Node.js

Usage

# Clone the repository
$ git clone https://github.com/pavle-goloskokovic/texture-unpacker.git
$ cd texture-unpacker

# Install dependencies
$ npm install

# Run TextureUnpacker tool usage command
$ npm run unpack -- -h
# Usage: npm run unpack [-- <options>]
#
# Options:
#   -i, --inputPath   Directory or sprite sheet path/name   [string] [default: ""]
#   -f, --dataFormat  Data format type ('json' or 'plist')  [string] [default: ""]
#   -d, --dataPath    Custom data file path                 [string] [default: ""]
#   -o, --outputPath  Custom output directory path          [string] [default: ""]
#   -c, --clean       Clean the output directory before unpacking
#                                                       [boolean] [default: false]
#   -v, --version     Show version number                                [boolean]
#   -h, --help        Show help                                          [boolean]

Example

We have sprite sheet and data files Sprite.png, Sprite.json, and Sprite.plist available in the example directory. The tool assumes that sprite sheet and data files have the same name with different extensions.

Running the command below will read json data file, create Sprite directory at the same level as the sprite sheet file, and populate it with individual sprites:

$ npm run unpack -- -i example/Sprite.png -f json

In case we have multiple data files available, like in this example, you can explicitly provide plist as the format argument to give it precedence:

$ npm run unpack -- -i example/Sprite.png -f plist

Omitting the format argument in the command above will use json data since it is the default expected format:

$ npm run unpack -- -i example/Sprite.png

In case you have only plist data file available, the above command would work the same since the tool can automatically detect available data file.

You can also omit the sprite sheet extension .png when running the tool for the same effect:

$ npm run unpack -- -i example/Sprite

Providing directory path as the input path will scan provided directory for .png sprite sheets with accompanying data files to unpack:

$ npm run unpack -- -i example

Note that providing example/Sprite as the input path will give priority to example/Sprite.png sprite sheet file, rather than to the generated example/Sprite directory, to avoid undesired behavior if you run the tool repeatedly.

And finally, omitting the input path argument completely will scan the entire project structure to find all available .png sprite sheets with accompanying data files to unpack:

$ npm run unpack

If you want to override the default data path, you can pass a custom one as an argument:

$ npm run unpack -- -i example/Sprite -d example/Sprite_custom.json

Note that custom data file path must include file extension, and if data format is also passed it will be ignored.

If you want to override the default output path, you can pass a custom one as an argument:

$ npm run unpack -- -i example/Sprite -o example/Sprite_unpacked

If you want to clean the output directory before unpacking you can indicate that by passing another argument:

$ npm run unpack -- -i example/Sprite -c

---

Originally ported from onepill/texture_unpacker_scirpt archive written in python.