A texture packer utilizing (fork of) Runtime-TextureAtlas using LÖVE and Python.
-
LÖVE 11.x - to run
packerguin
folder. -
Python 3.10 - tu run
fasterguin
module. 3.9 works but there's issue with their typing module. -
ImageMagick 7 - ImageMagick 6 is not supported!
-
ASTCEnc - ASTC encoder required to run
android
profile (see below). -
EtcTool - ETC2 encoder required to run
low
profile (see below). -
(Optional) Black - Code reformatter, with maximum lines of 120 (
-l 120
).
For the usage, please run python fasterguin/main.py
. You can also install the package with
pip install .
if you want, but you'll lose ability to auto-find Packer Guin.
Make sure you have cloned with submodules before running. For example, git clone $URL --recurse-submodules
,
or run git submodule update --init --recursive
if you have already cloned it.
List of possible profiles:
-
pc
(default) - Only re-encode image to PNG. Resulting texture has.png
extension. -
android
- Encodes image to ASTC texture. Resulting texture has.astc.ktx
extension. -
low
- Encodes image to ETC2 texture. Resulting texture has.etc2.ktx
extension.
The input file format is composed as one or more commands. The command pattern are:
<command> <input> [option_1 <value>] [option_2 <value>] ... [option_n <value>]
In most cases, <input>
is the input file in your raw assets directory. #
at beginning
and empty lines are ignored.
List of commands:
Copy directory recursively to the output path. <input>
is the directory to copy.
Copy file to the output path. <input>
is the file to copy.
Include image file as part of the assets. <input>
is the image file.
Accepts dimension
and resize
options.
Include directory containing images non-recursively as part of the asets. <input>
is the directory.
Accepts destination
, dimension
, and resize
options.
Set the output file for the metadata.json
(<input>
parameter). The metadata contains the all original
dimensions and resized non-PO2'd images included in the assets in that order. The key is the path to the
image with prefix.
{
"path/to/image.png": [original image w, original image h, resized image w, resized image h]
}
The default is metadata.json
.
Run Packer Guin. <input>
is the Packer Guin input file. See below for the file syntax.
Accepts algorithm
option.
Set the output asset prefix for the metadata. <input>
is the desired prefix. To illustrate
how this parameter works, consider this LOVE game structure:
path/to/game
| conf.lua
| main.lua
+---assets
| | image1.png
| | image2.png
If you access your images with assets/image1.png
and you set the output directory of the script
to path/to/game/assets
, then you need to specify "assets"
as the prefix.
The command can accept one or more options.
List of options:
Set the packer algorithm for the pack
command. Valid options are:
-
tree
- Use Tree node packing algorithm. -
grid
- Use RTA's custom packing algorithm.
The default is grid
if this option is absent.
Set output destination relative to the output assets directory.
Set the assumed image dimensions, ie. what size the metadata reports the image to be. This can be used as reference for drawing the image at the appropriate size as defined by the original artwork. Valid values are:
-
<w>x<h>
- Assume it's exactly specified. -
original
- Use the original image dimension as-is.
If this option is absent, the image dimension is set to the original image or the
resized image (if resize
option is present).
Resize the input image. Valid values are:
-
<w>x<h>
- Resize exactly to specified dimensions. -
x<h>
- Automatically compute the width based on the ratio with fixed height. -
<w>x
- Automatically compute the height based on the ratio with fixed width. -
<scale>%
- Scale by percentage.
If this option is absent, the image is not resized.
The file format for pack
command is as follows
output output.packed
size 2048
extrude -1
prefix assets
file <input>
file <input>
...
file <input>
folder <input>
folder <input>
...
folder <input>
To explain, the output
tells where to put the packed .png
and the .json
metadata
containing the slice information relative to the output directory in the Python script.
The size
is the maximum square dimensions allowed for this particular texture atlas.
extrude
extrudes by specified amount of pixels, but if -1
is specified, the best
amount of pixels is computed for you (usually ceil(log2(max(final_width, final_height)))
).
Finally the prefix
is same as above.
After those information, one or more file
or folder
must be specified. file
specify
one image to be added to atlas and folder
specify a directory of images to be added to
atlas (non-recursive).
Currently, you must place this Packer Guin file in the root folder of your input assets directory, usually in same directory as the input file for Faster Guin. This hopefully change in the future.
MIT.