spright

<a href="https://github.com/houmain/spright/releases/latest">Downloads</a> | <a href="#command-line-arguments">Command line arguments</a> | <a href="#installation">Installation</a> | <a href="#building">Building</a> | <a href="https://github.com/houmain/spright/releases">Changelog</a>

spright is more than a simple sprite sheet packer, it can be used as one though. Its key ideas are:

Keep all the information about the sprites and tiles, required for being efficiently consumable by the game engine, in a plain text file.
Instead of forcing one to split each sprite in a separate file and later address them using the filename, it should be possible to keep them in whatever format they are most conveniently to handle.
It should be possible to give each sprite an ID, group them (e.g. for animations) or further annotate them for game specific purposes.
The tool should be able to deduce obvious information from the input images and assist with completing the required information.

While any text editor can be used for writing the input definition, the Visual Studio Code Extension can greatly simplify the process.

Also have a look at the spright test suite to get an impression of the functionality.

Introduction:

Simple sheet packing
Advanced usage example

Reference:

Terminology
Input definition
- Definition reference
- Variables
Output description
- Additional functions
Output template engine

Simple sheet packing

To pack your sprites into one or more sheets, create an input definition file spright.conf like the following and run spright:

max-width 1024                 # set some constraints for the sheet
max-height 1024
power-of-two true

output "spright{0-}.png"
description "spright.json"
  template "phaser.inja"       # select the template for your game engine

id "{{ source.filenameBase }}"
glob "characters/**/*.png"     # set the location of the images you want to pack
glob "scenery/**/*.png"

The sample creates a sprite sheet spright0.png along the output description spright.json, consumable by the Phaser game engine. Templates for some other game engines are provided and additional templates can be easily written.

See the input definition section for a description of the available options.

Advanced usage example

Say you got some nice sprites you would like to use in your next game:

And your game engine supports efficiently packed sprite sheets like this:

Then you may want to use spright to define the sprites within their original sources and directly pack the sheet from there.

To do so, start by creating a spright.conf containing the essential information:

sheet "sprites"
  padding 1
  output "sheet{0-}.png"

colorkey

input "Decorations (32x32).png"
  grid 32 32

input "Old enemies 2.png"
  grid 16 16

input "Orc Attack/Frame{01-04}.png"

input "misc_scenery.png"
  atlas

When spright is called without command line arguments, the input definition is read from spright.conf and it writes a spright.json file containing the output description.

Passing the argument -c runs the completion, which extends spright.conf with automatically deduced information:

input "Decorations (32x32).png"
  grid 32 32
    sprite
    sprite
    sprite
    sprite
    sprite
  row 1
    sprite
    sprite
    sprite
    sprite
    sprite
...

It detected that Decorations (32x32).png contains five sprites per row and added them below...
For sheets without grids it adds the sprites' rectangles:

...
input "misc_scenery.png"
  atlas
  sprite
    rect 78 12 6 27
  sprite
    rect 88 12 4 24
  sprite
    rect 97 9 6 34
  sprite
    rect 107 8 7 40
  sprite
    rect 6 17 17 52
...

Now you can complete the definition manually by e.g. giving the sprites IDs and customizing their pivot points:

...
input "Decorations (32x32).png"
  grid 32 32
  pivot left top
    sprite "banner_top"
    sprite "platform_1_left"
    sprite "platform_1_middle"
    sprite "platform_1_right"
    sprite "platform_1_sole"
  row 2
    sprite "banner_middle"
    sprite "platform_2_left"
    sprite "platform_2_middle"
    sprite "platform_2_right"
    sprite "platform_2_sole"
  row 3
    sprite "banner_bottom_1"
...

You can also tag sprites to define animations or other game specific properties and leave sprites you do not want to directly address without ID:

...
input "Old enemies 2.png"
  grid 16 16
    tag anim "blue_enemy_idle"
    sprite
    sprite
    tag anim "blue_enemy_dead"
    sprite
    tag anim "blue_enemy_jump"
    sprite
  row 1
    tag anim "blue_enemy_run"
    sprite
    sprite
    sprite
    sprite
    sprite
    sprite
  row 2
...

See the output template engine section on how to generate a file consumable by your game engine.

Terminology

Since there are quite some terms, an explanation of what they represent in spright might be useful:

input: a filename or sequence referring to one or more input images.
source: a single image file of an input containing the pixel data of one or more sprites.
sheet: a collection of sprites which should be arranged on one or more slices, while obeying the defined constraints. Each sprite is part of a single sheet (there is a default sheet "spright").
slice: a single layer of a sheet where the sprites are arranged.
sprite rect: the rectangular space a sprite allocates on the slice.
sprite size: the size of the sprite rect.
sprite bounds: the logical bounds of a sprite - defined by the sprite rect plus a margin.
pivot point: the coordinate of a point on a sprite used for placing it in the game (a.k.a anchor).
output: a filename or sequence referring to one or more output images.
texture: a single image file of an output containing the pixel data of one slice, possibly with some output transformations applied.
(output) description: a file generated by spright containing the information about the sprites, like where to find them on which texture.

Input definition

Indentation is relevant in the hierarchical input definition file. There are two scoping rules:

A definition affects succeeding items on the same or a sub-level.
A definition affects its parent item.

The comments in the following sample should exemplify these:

pivot center middle      # sets default pivot point

input "furniture.png"
  pivot center bottom    # sets pivot point within "furniture.png"
  sprite "chair"
  sprite "lamp"
    pivot center top     # sets pivot point of "lamp"
  sprite "bed"

input "characters.png"
  sprite "player"
  sprite "bird"
    pivot center bottom  # sets pivot point of "bird"
  sprite "wolf"          # "wolf" still gets the default pivot point

Definition reference

The following table contains a list of all definitions, with the item each affects, the expected arguments and a description. Optional arguments are enclosed in square brackets. Unless specified otherwise, optional booleans default to true, numbers default to 1, and an additional value defaults to the first value.

| Definition | Affects | Arguments | Description | | ---------- | ------- | --------- | ----------- | | sheet | sprite | id | Sets the sheet on which the sprites should be packed (default: "spright"). | | pack | sheet | pack-method | Sets the method, which is used for placing the sprites on the sheet: - binpack : Tries to reduce the sheet size, while keeping the sprites' rectangles apart (default). - compact : Tries to reduce the sheet size, while keeping the sprites' convex outlines apart. - rows : Layout sprites in simple rows. - columns : Layout sprites in simple columns. - single : Put each sprite on its own slice. - origin : Place all sprites in the top-left corner (use align to position). - layers : Like origin but also activates layered output of .gif files. - keep : Keep sprite at same position as in source. | | width | sheet | width | Sets a fixed sheet width. | | height | sheet | height | Sets a fixed sheet height. | | max-width | sheet | width | Sets a maximum sheet width. | | max-height | sheet | height | Sets a maximum sheet height. | | power-of-two | sheet | [boolean] | Restricts the sheet's

Spright

Install / Use

README