bdr76 / gimpspriteatlas

GIMP plug-in to create a spriteatlas (aka spritetexture or spritesheet). Takes all layers as images and compiles them into one sprite atlas texture, using a 2D packing algorithm so that the final texture image takes as little space as possible. Also outputs a TexturePacker JSON, LibGDX, CSS or XML coordinates file.

GIMP SpriteAtlas

GIMP SpriteAtlas is a plug-in to compile sprite textures for use in games and websites.

The plug-in takes several smaller images and compiles them into a single image. It uses a packing algorithm to use as little space as possible in the final texture. And it exports a JSON, Atlas, XML or CSS file with the sprite names and their coordinates within the compiled texture.

How to install

First install GIMP, then place the Python script file create_spriteatlas.py in the GIMP folder, typically under program files:

Windows (all users)
%PROGRAMFILES%\GIMP 2\lib\gimp\2.0\plug-ins\
Windows (single user)
%USERPROFILE%\AppData\Roaming\GIMP\2.10\plug-ins\

Linux
~/.config/GIMP/2.10/plug-ins/

After you've copied the file in this directory, open GIMP and the plug-in is available in the menu:

Filters -> Animation -> Sprite Atlas

How to use it

1. Open GIMP
2. Open your images as layers (Ctrl + Alt + O)
3. Start the plug-in from Filters > Animation > Sprite Atlas
4. Select an export folder
5. Press OK to generate the sprite texture

So first open all your images as layers. You can do this from the menu Open As Layers (Ctrl + Alt + O), select all your files and click Open. Alternatively, you can first open one image (preferably the largest one), and then drag and drop all the remaining images onto the layers window.

Note: opening images as layers can be remarkably slow (see issue report).

Then go to the menu Filters > Animation > Sprite Atlas to open the GIMP SpriteAtlas plug-in, you'll see the following dialog.

Make sure to select an export folder, this is where the output image and coordinates datafile will be exported to. The default export folder is \tmp\, if you don't change this to an actual existing folder you will get the following error message:

RuntimeError: Could not open '\tmp\sprites.png' for writing: No such file or directory

Press OK to generate the spriteatlas and export the sprite texture and sprite metadata file.

Options

Export filename: Export filename for both the texture image and the coordinates file, for example, set it to sprites123 and the output files will be named sprites123.png and sprites123.json.

Export folder: Output folder for both the texture image and the coordinates file.

Export filetype

• JSON TexturePacker-array, compatible with the TexturePacker format
• JSON TexturePacker hash, compatible with the TexturePacker format
• libGDX TextureAtlas, .atlas text file
• CSS sprites, can be used for html and websites
• XML, plain xml format

The TexturePacker-array/hash output is the preferred format for use with Phaser.io. If you need any other format, you can edit the Python code and add a custom function or you can post an issue here.

Pad one pixel between sprites separate all sprites by at least one pixel, recommended to avoid texture bleeding. If a sprite texture contains sprites that are right next to each other, in some graphics engines the texture tiles can "overflow" and pick up parts of neighboring tiles.

Extending sprites the plug-in can automatically extend the edges on some sprites Up Down Left and/or Right. This can be useful to make tiles in a tilemap align seemlessly, so without any lines between tiles. For example if you want to extend a sprite Down and Rright you can add [ext=DR] to the name like this

mytile01 [ext=dr].png

In the compiled texture, the plug-in will extend this sprite by one pixel down and one pixel right, meaning it will copy the bottom row pixels and the right-most column of pixels of that sprite.

Sprite Sheet

This repository also includes a create_spritesheet.py plugin, for the sake of completeness. It creates a sprite sheet where all the sprites are the same size in a simple grid layout. This doesn't require a coordinates file. The tile size will be the width and height of the original image.

It is based on a plug-in by Spydarlee but with some bugfixes and additional options

Trouble shooting / Known issues

• Opening images as layers is remarkably slow in GIMP (see issue report). Once you've created a sprite texture, it's best to also save the original image with the layers as a .xcf. If you want to make changes to the texture at a later time (add/remove sprites) then you can more quickly open the .xcf instead of having to re-add all the images as layers again.

• You can use this plug-in create any custom coordinates format or custom preprocessing by editing the Python file. Alternatively you can also create sprite atlas/textures using the TexturePacker Online (free) or Leshy SpriteSheet Tool

History

26-may-2022 - v0.1 first release
14-oct-2023 - v0.2 json bugfix
09-mrt-2024 - v0.3 fix pad-pixel option

BdR©2023 Free to use - send questions or comments: Bas de Reuver - [email protected]

gimpspriteatlas's Issues

Padding added on *No Padding Option* on SpriteAtlas

So, when I set this "Pad one pixel between sprites" to "No", I expect them to not add padding between sprites, as you can see image below this, the atlas has 1 pixel padding between sprite.

json not being generated correctly

{
	"frames":[
		{"filename":"image-1","frame":{"x":0,"y":0,"w":400,"h":400},"rotated":"false","trimmed":"false","spriteSourceSize":{"x":0,"y":0,"w":400,"h":400},"sourceSize":{"w":400,"h":400}},
		{"filename":"image-2","frame":{"x":401,"y":0,"w":400,"h":400},"rotated":"false","trimmed":"false","spriteSourceSize":{"x":0,"y":0,"w":400,"h":400},"sourceSize":{"w":400,"h":400}},
		 [...]
		{"filename":"image-n","frame":{"x":802,"y":3208,"w":400,"h":400},"rotated":"false","trimmed":"false","spriteSourceSize":{"x":0,"y":0,"w":400,"h":400},"sourceSize":{"w":400,"h":400}}
	]
	"meta":{
		"app":"https://github.com/BdR76/GimpSpriteAtlas/",
		"version":"GIMP SpriteAtlas plug-in v0.1",
		"image":"[image].png",
		"size":{"w":2806,"h":3608},
		"scale":1
	}
]

The problem lies in the fact that the parentheses are mismatched in the first and last lines, and that there is no comma between

"frames":[
    [insert frames here]
]

and

"meta":{
    "app": etc.
}