Introducing Leshy SpriteSheet Tool
Posted by
Doug Haber on 2013-12-03
Introduction 
Leshy SpriteSheet Tool is a browser-based utility for creating, packing, and modifying sprite sheets and texture atlases. This post discusses the various features and how to use them.
This is unrelated to
Leshy SpriteSheet Animator which is used for previewing, editing, and testing animations from sprite sheets.
Launch Leshy SpriteSheet Tool Features - Build and pack a new sprite sheet from images and other sprite sheets
- Add or remove images from an existent sprite sheet
- Modify or maintain sprite map/texture atlas layout details
- Convert sprite map/texture atlas layout files into a different format (including things like CSS, JSON, XML)
- Create a new mapping for an existent sprite sheet
- Repack an existent sprite sheet to get a better file size
- Create maps for sprite sheets that are missing them by automatically detecting the sprites within them
- Create ImageMagick scripts to rebuild sprite sheets from the command line or as part of a build process
Introduction
Leshy SpriteSheet Tool can be used to perform a large number of different sprite sheet related tasks. Everything is done client side in the web browser. Assets are never sent to any server.
I use the term "sprite sheet" as a synonym for "texture atlas." There is some debate about this, and some people believe there are subtle differences. The term "sprite sheet" seems to have lost some popularity over the years, except possibly when dealing with animations. This tool always uses the term sprite sheet, but nearly anything here should apply just as well to texture atlases.
Usage
Adding New Sprites
Sprites are added to a sprite sheet by dragging and dropping them onto the application's web page. PNG files are preferred, but GIF and JPEG should work as well. Multiple files may be dropped at once.
Zooming and Dragging
The viewport may be zoomed in or out from a position using the mouse wheel. The + and - keys can be used to zoom in and from the center of the viewport.
By pressing and holding the right mouse button over the viewport and moving the mouse, it is possible to drag the viewport.
At any time the viewport may be restored to its default settings the 0 key, or by clicking the refresh icon in the upper right corner of the viewport.
Importing Sprite Maps
If an existent sprite sheet is dropped onto the page it will assume that the image is one large sprite. In order to get it to recognize the individual sprites you may either
remap the sprite sheet or import a sprite map.
A sprite map is imported by dragging and dropping it onto the page. The current version supports dropping sprites in Text, JSON, and JSON-TP formats. Once a sprite map is dropped, all sprites in it should show up as separate entities with names associated with each them. It is then possible to do any other operation, such as editing or repacking the sprite sheet.
Replacing Sprites
Sprites may be replaced by dropping a new sprite with the same file name. If a sprite sheet and map are loaded, this makes it possible to easily replace files.
If a dropped file has different dimensions than then current sprite with that name, then the sprite sheet will automatically be repacked. This will invalidate any sprite map, but it is necessary in or for things to fit.
Packing Sprite Sheets 
When new images are added the sprite sheet is automatically repacked. The Repack button may be used to force a repack to be done. The Optimize button does the same thing as the Repack button, but it spends 5 seconds attempting to randomly manipulate the resulting sprite sheet to see if it can find a tighter fit. Since it is random, multiple presses may in some cases yield increasingly better results. If an attempt to repack does not result in a better fit, then no change will be made.
The Padding option defines the amount of padding to use between sprites in pixels. The default is 1 pixel. This may be disabled by using the value 0. Changing the amount of padding forces a repack.
Remapping Sprite Sheets
If a sprite sheet is dropped into the application and no sprite map is available, then remapping can be used to attempt to create a new sprite map. It does this by detecting the edges between sprites. In order for this to work the background must be transparent and there must be 1 pixel or more of padding between sprites. To perform a remap, press the Remap button located above the sprite map.
Before a remap, hovering the mouse over a dropped sprite sheet image will show that the selection is the entire image. After the remap, the selections should show as the individual sprites. If a sprite is detected that lines up with an existent sprite, the name will be preserved. Otherwise, names are just will be automatically assigned, such as "sprite123".
Grid Based Remapping
UPDATE: This was added in version 0.8.1 (2014-05-29)
A grid remap allows a sprite sheet to be mapped out into a perfect grid of rectangles of the same size. To use this tool, press the
Grid Remap button located above the sprite map. In the dialog that appears, enter the height and width of the sprites and then press submit. The image will then be converted into a perfect grid of sprites of the specified dimensions. Empty cells will be left empty, and any that are exact matches for existent sprites will maintain their name and other settings.
This tool is very useful for working with images that are perfect grid of sprites. After doing a grid remap, each sprite can be named and other actions can be performed, such as adding sprites, removing sprites, repacking, or exporting sprite maps.
This tool maps out the grid including any defined padding, so if a grid remap is being done off of multiple sprites, be sure to set the padding appropriately.
Grid remaps currently only work with perfect grids, and no padding or offsets are supported.
Joining Sprites
Sprites can be joined by selecting a sprite and then another while holding down the shift key. This will merge the original sprite, the selected sprite, and all others that fall within the rectangle that they fit into.
Deleting Sprites
Sprites can be deleted either with the Delete button, or by selecting them and pressing CTRL+DELETE. To delete an area of sprites, first join them together, then delete them.
Editing Sprite Maps 
Sprite maps are edited in the "Sprite Settings" area. When a sprite is selected all the settings fill into this area for that sprite. Sprites may be selected by clicking on them.
The Name of a sprite may be modified. This name will be used in various export formats as the name of the sprite. Sprite names must be unique. Some sprite map formats will not support certain characters in the name. These will be automatically converted to '_', and may possibly result in name collisions. To be safe, sprite map names should contain alphanumeric characters and the underbar.
The Ignore control is used to indicate a sprite should not show up in sprite map exports. The sprite still remains in the image file for the sprite sheet, but is not referenced in the map.
The "Prev" and "Next" buttons cycle through to the previous or next sprite. From the keyboard this can be done with the bracket keys ([ and ]). A keyboard shortcut also exists for cycling only through unnamed sprites. This is done with CTRL+[ or CTRL+] and can be useful for making sure each sprite has a proper name before exporting.
Exporting Sprite Maps 
Sprite maps may be exported into a variety of formats:
Text
A very simple CSV (comma separated values) format.
name,x,y,width,height
For Example:
burrito_warrior,100,100,64,64
This is the easiest format. It is very basic, but it gets the job done.
SpriteSheet Tool supports loading sprite maps from this format.
JSON
A simple JSON (JavaScript Object Notation) format.
[
{
"name": "burrito_warrior",
"x": 100,
"y": 100,
"width": 64,
"height": 64
}
] This provides a straightforward JSON list of objects. One object will exist for each non-ignored sprite.
CSS
A CSS (Cascading Style Sheet) format.
.burrito_warrior {
background: url('spritesheet.png') no-repeat -100 -100;
width: 64px;
height: 64px;
} This format creates a style sheet with a class for each sprite. Each class references the name of the export PNG file, which can be set with the "File Name" field for the Sprite Sheet.
There are many ways to make usage of the sprites. Usually they start with including the stylesheet in the <head> section of the web page. For example:
<link rel="stylesheet" href="sprites.css"></link>
Once the style sheet is loaded, elements can be set to the class. This can be used on its own or combined with other CSS, to do things like positioning the element. For example:
<div class="burrito_warrior"></div>
<!-- Or, with some positioning: -->
<div class="burrito_warrior" style="position: fixed; left: 250px; top: 250px"></div>
JSON-TP-Hash
UPDATE: This was previous known as the JSON-TP format. It was changed to JSON-TP-Hash, since we now support JSON-TP-Array as well. (2014-02-11)
A JSON format aiming for compatibility with TexturePacker's JSON export format. This is the hash version, where the frame list is stored as an hash, where the key is the filename. If an array is preferred, see
JSON-TP-Array.
{
"frames": {
"burrito_warrior": {
"frame": {
"x": 100,
"y": 100,
"w": 64,
"h": 64
},
"rotated": false,
"trimmed": false,
"spriteSourceSize": {
"x": 100,
"y": 100,
"w": 64,
"h": 64
}
}
},
"meta": {
"app": "https://www.leshylabs.com/apps/sstool/",
"version": "Leshy SpriteSheet Tool v0.8",
"size": {
"w": 64,
"h": 64
},
"scale": 1
}
} This is fairly similar to the intended format. If further changes are needed for compatibility, post in the comments.
JSON-TP-Array
UPDATE: This was added in version 0.8 (2014-02-11)
A JSON format aiming for compatibility with TexturePacker's JSON export format. This is the array version, where the frame list is stored as an array, and each frame object contains a "filename" key. If a hash of frames is preferred, see
JSON-TP-Hash.
{
"frames": [
{
"filename": "burrito_warrior",
"frame": {
"x": 100,
"y": 100,
"w": 64,
"h": 64
},
"rotated": false,
"trimmed": false,
"spriteSourceSize": {
"x": 100,
"y": 100,
"w": 64,
"h": 64
}
}
],
"meta": {
"app": "https://www.leshylabs.com/apps/sstool/",
"version": "Leshy SpriteSheet Tool v0.8",
"size": {
"w": 64,
"h": 64
},
"scale": 1
}
} XML
An XML format aiming for compatibility with a popular XML export format.
<textureatlas imagepath="spritesheet.png">
<subtexture name="burrito_warrior" x="100" y="100" width="64" height="64">
</subtexture>
</textureatlas>
Binary
A simple binary format.
Each sprite is listed as:
| Field | Type |
| Sprite Name | Null Terminated String |
| X Position | Unsigned 16-bit Integer |
| Y Position | Unsigned 16-bit Integer |
| Width | Unsigned 16-bit Integer |
| Height | Unsigned 16-bit Integer |
All integers are stored in little-endian.
ImageMagick
Creates an ImageMagick command for building the sprite sheet.
convert \
-size 200x200\
canvas:none \
-draw "image SrcOver 100, 100, 64, 64 burrito_monster.png" \
spritesheet.png This exporter generates commands that when run use the ImageMagick convert to build the sprite sheet from its pieces. When possible, it uses the names of the original files. It assumed that they are in the current directory as is the output file.
This makes it possible to easily rebuild the sprite sheet from the command line. Commands generated from this exporter may be used in build scripts. This makes it possible to drop in new versions of art without having to repack or make use of the web based sprite sheet tool again. This will work, so long as the dimensions of the art have not changed.
Keyboard Shortcuts
| Key | Action | Key | Action |
| + | Zoom In | - | Zoom Out |
| 0 | Reset Zoom | CTRL + DELETE | Delete the Selected Sprite |
| [ | Previous Sprite | ] | Next Sprite |
| CTRL + [ | Previous Unnamed Sprite | CTRL + ] | Next Unnamed Sprite |
Other
If you encounter any problems using this software, please post a detailed response in the comments of this page explaining how to recreate the issue along with your browser and version. A link to a sample sprite sheet could be helpful as well.
I have tested this primarily in Chrome, but also performed light testing on Firefox and Opera. Since HTML5 features are used, a recent version of these browsers may be required. Due to a lack of availability and interest, IE is untested and likely won't work. Chrome is highly recommended.
This is commercial software and it may not be redistributed. The source code is closed and due to reliance on proprietary game engine code, will likely remain that way. It is currently made available for usage on LeshyLabs.com with no warranty. For more details, please see our
Legal Notices page.
