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.


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...
Connecting to opensource.cego.dk||: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

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

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

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

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] 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] 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


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"/>
Each tag/parameter will be described in the following.


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:


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.
                               - 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.