SpritePacker/README.md

# SpritePacker

An advanced sprite packing tool. Currently a work in progress.

## Requirements
 * Either the Microsoft .NET framework on Windows, or the [Mono runtime](http://www.mono-project.com/) on other platforms.
 * If you want to build SpritePacker from source, you'll need [git](https://git-scm.com/) installed and in your PATH.

## Getting Started

### Prebuilt binaries
I provide prebuilt binaries, just in case you can't get SpritePacker to build yourself.

Link: [SpritePacker.exe](https://owncloud.starbeamrainbowlabs.com/index.php/s/xr7oS7DPCaFJ4kO) ([Direct Link](https://owncloud.starbeamrainbowlabs.com/index.php/s/xr7oS7DPCaFJ4kO/download))

### From source

 * Clone or [download](https://git.starbeamrainbowlabs.com/sbrl/SpritePacker/archive/master.zip) this repo, and build the included solution.
	 * Windows GUI: Open the solution in Visual Studio and hit build (CTRL + SHIFT + B).
	 * Windows Command Line: Run `msbuild` from the root of this repo (I assume).
	 * Linux GUI: Open the solution in MonoDevelop and hit build (F8)
	 * Linux Command Line: Run `xbuild` from the root of this repo.

## Usage
SpritePacker is currently a command line tool (Requests for a GUI are welcome), and intended to be easy to automate and integrate into your existing workflow. Despite that, it's still easy to use. Here's an example of how you would pack 3 different images into the same file:

```bash
SpritePacker.exe /path/to/output.png picture1.png textureB.jpeg anotherimage.gif
```

Your next latest and greatest project will probably have a _lot_ mroe than just 3 images, making specifying them all one by one a pain in the neck. Thankfully, SpritePacker supports (recursive!) directories of images:

```bash
SpritePacker.exe /path/to/output.png /path/to/image/directory
```

Packing sprites is all very well, but your program needs to be able to tell where each individual sprite was placed in the final image. SpritePacker tells you by outputting some nice, easy to read text, but this isn't particularly machine-friendly. Alternatively, you can add the `--csv` flag when you call SpritePacker. This will cause SpritePacker to output some nice, (hopefully) well-formatted CSV for your program to consume:

```bash
SpritePacker.exe /path/to/output.png /path/to/image/directory --csv
```

Note that any other text besides the CSV will be ouputted via stderr, so you can pipe the raw stdout to a file and have your program understand it.

```bash
SpritePacker.exe /path/to/output.png /path/to/image/directory --csv >SpriteLocations.csv
```

Additonal help can be found by running `SpritePacker.exe --help`.

## Feedback
This project is a work in progress. If you encounter any issues, please open an issue on the [issue tracker](https://git.starbeamrainbowlabs.com/sbrl/SpritePacker/issues) if you have an account, otherwise please send an email to `bugs at starbeamrainbowlabs.com`.

Once SpritePacker is somewhat stable, it will be moving to GitHub. I still intend to host a mirror at this address though, so you can bookmark this address.

If you would like to contribute (before the move to GitHub sometime in the future), please an email to the aforementioned address and I'll create you an account with which you can contribute.


## License
This tool is licensed under the Mozilla Public License version 2.0. You can view the full license text in the `LICENSE` file in this repo. Alternatively, [tl;dr legal](https://tldrlegal.com/) has a [summary](https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)) of this license.