SpriteMapper

Welcome to the world of sprite mapping!

Sprite mapping is a technique of grouping many small images used in games or websites into one larger image in order to minimize the number of web requests needed to fetch all graphics and in the same time maybe minimize the file size. The result is a sprite map (also called sprite sheet, texture map or texture atlas).

A couple of programs exists for this purpose, for instance Zwoptex and TexturePacker. Both of these unfortunately are closed source and not easy to have in your build process. Also Zwoptex only works on Mac.

This is where SpriteMapper comes into the picture.

Features

SpriteMapper contains many of the same features as Zwoptex and TexturePacker but it also has a couple of unique ones:

I have no need for a GUI application, so this is not available but it would not be hard to build one.

How to build and install

Download the latest source file from here and unpack it somewhere.

$ wget http://opensource.cego.dk/spritemapper/SpriteMapper.tar.bz2
--2011-03-07 16:57:05--  http://opensource.cego.dk/spritemapper/SpriteMapper.tar.bz2
Resolving opensource.cego.dk... 194.255.21.242
Connecting to opensource.cego.dk|194.255.21.242|:80... connected.
HTTP request sent, awaiting response... 401 Authorization Required
Reusing existing connection to opensource.cego.dk:80.
HTTP request sent, awaiting response... 200 OK
Length: 1871452 (1,8M) [application/x-bzip2]
Saving to: `SpriteMapper.tar.bz2'

100%[======================================>] 1.871.452   11,2M/s   in 0,2s    

2011-03-07 16:57:05 (11,2 MB/s) - `SpriteMapper.tar.bz2' saved [1871452/1871452]

$ tar xjf SpriteMapper.tar.bz2
$ cd SpriteMapper
                

Run the default 'ant' target

$ ant
Buildfile: /home/robert/SpriteMapper/build.xml

init:
    [mkdir] Created dir: /home/robert/SpriteMapper/dist
    [mkdir] Created dir: /home/robert/SpriteMapper/build

compile:
    [javac] Compiling 31 source files to /home/robert/SpriteMapper/build

jar:
      [jar] Building jar: /home/robert/SpriteMapper/dist/SpriteMapper.jar

BUILD SUCCESSFUL
Total time: 1 second
                

Copy the resulting jar file to your system Ant lib directory.

$ sudo cp dist/SpriteMapper.jar /usr/share/ant/lib
                
...or to your local Ant lib directory.
$ mkdir -p $HOME/.ant/lib
$ cp dist/SpriteMapper.jar $HOME/.ant/lib
                

Finally verify the installation by running the demo ant build file.

$ ant -f spritemap.xml
Buildfile: /home/robert/SpriteMapper/spritemap.xml

spritemap_trim:
[spritemap] Layouter used: Guillotine(BestShortSideChooser,ShortestAxisSplitStrategy)
[spritemap] Resulting file is 1200 by 1462 pixels. Area is 1754400 square pixels.
[spritemap] Waste: 1%
[spritemap] Combined filesize: 1940786 Map filesize: 2277040

spritemap_notrim:
[spritemap] Layouter used: Guillotine(BestFitChooser,ShortestAxisSplitStrategy)
[spritemap] Resulting file is 1200 by 1732 pixels. Area is 2078400 square pixels.
[spritemap] Waste: 1%
[spritemap] Combined filesize: 1940786 Map filesize: 2307327

spritemaps:

BUILD SUCCESSFUL
Total time: 2 seconds
                

How to use with Ant

This is the most well maintained way to run the mapper as this is what I do myself. Get Ant from here.

Somewhere in your build file you must load the spritemapper Ant tasks:

<taskdef resource="spritemapper-tasks"/>

The following target shows all supported attributes:

<target name="spritemap">
    <taskdef resource="spritemapper-tasks"/>
    <spritemap trim="true" drawframes="false" maxwidth="800" destfile="spritemap.png">
        <layoutmeta destfile="spritemap.plist" format="zwoptex2"/>
        <fileset dir="graphics">
            <include name="**/*.png"/>
        </fileset>
    </spritemap>
</target>
Each tag/parameter will be described in the following.

<spritemap>

The spritemap tag is the task for building the spritemap. The images that should be used as input are specified as a nested fileset tag. spritemap supports the following attributes:

<layoutmeta>

This tag defines a file that should contain the coordinate information for the sprite map. It is contained within the spritemap tag. Multiple tags are allowed. It supports the following attributes:

How to use from the command line

The SpriteMapper can also be run from the command line. The jar archive contains a default main class in its manifest file so running it is easy:

$ java -jar SpriteMapper.jar
Usage: java -jar SpriteMapper.jar [options...] <image dir>
  Options and default values:
    --zwoptex2=spritemap.plist - Output metadata to 'spritemap.plist' in Zwoptex2 format.
    --out=spritemap.png        - Output sprite map to 'spritemap.png'.
    --max-width=1000           - Set maximum width of sprite map to 1000 pixels.
    --draw-frames=false        - Draw frames around images in sprite map.
    --trim=true                - Trim transparent edges.
    --file-pattern=\.((png)|(jpe?g)|(gif))$
                               - Only include files matching this pattern.
                

Only the top level directory containing images needs to be specified, but the --zwoptex2 parameter should also be specified. At some point multiple formats will be supported and then several meta output parameters can be specified.