MonoPack - Free lightweight texture packer

Monkey Archive Forums/Monkey Discussion/MonoPack - Free lightweight texture packer

GuShh(Posted 2014) [#1]
Hi guys (and gals),

This is my first contribution for Monkey-X:

From the page:

MonoPack is a simple, comprehensive and lightweight pipeline oriented sprite / texture packer for web, game and software developers alike.

Right now MonoPack is a console-only application, oriented to streamline game and website development pipelines. It’s nature allows it to be automated via batch and scripting engines very easily.

It’s “page” oriented, meaning it will iterate through a given directory, including all matching images into the final atlas. It does not take into consideration sequential images (animations) nor grouping yet.

Monkey code:
There's already plenty of support for some of the output formats MonoPack generates (currently it outputs all supported formats at once) However if a specific requirement for a concise library or code sample is required, I'll try my best to come up with something.

Also if extra features or formats are required, please let me know and I'll add them to the to-do list!

I was sick and tired of some of the tools out there and I needed something simple and fast to deal with atlases. On the site you'll see the results of a small benchmark (over 2000 images processed) and the resulting atlas (scaled down of course), all in under one second.

A GUI is currently planned, but not officially. The internal framework / libs certainly allow for fast processing of sprites, so almost instant feedback is possible for a GUI, however we all know how much time a GUI takes to design, implement and test... So we'll see how much time I can allocate to this particular task.

I didn't want to implement artificial limitations on alpha channels or amount of sprites, I find this very distasteful. Instead if anyone finds it useful feel free to donate a small sum to help with the development of the software and it's documentation.

Currently you are allowed to use it on both non-commercial and commercial projects. Of course credit could be given, maybe a link to my site wouldn't hurt either!

Hope this ends up being useful to someone, I know it is for me. A polygon / vector outline generator is on the works for physic models and smart masking.


Soap(Posted 2014) [#2]
Unrelated to your tool, but it's safer to limit atlas size to 1024x1024 and then load multiple textures than to use one of a higher power. You only lose an inconsequential amount of time for loading into memory in exchange for greater support on older hardware.

Closed source?

This is the tool we use for texture packing right now, and I'd rather change to something else, but still keep its format. The key feature of it is that it's able to generate multiple textures while minimizing texture area waste. There has been no immediate urgency for us to roll our own solution. I'd only switch to something if its source was available and it already did the few things I need. Also, I'd pay for something better. A wish feature would be to be able to rebuild atlases from multiple folders with various options based on a .recipe file.

GuShh(Posted 2014) [#3]
Hi Soap,

You are absolutely correct about the atlas size, I however was testing the code using bigger sizes for optimization and basic testing purposes. Multiple pages (or textures) will be supported soon enough. For now it's closed source but that may well change.

About the size again, not only do you waste time loading the data, it also takes longer to retrieve the raw information from the image (decoding) and needless to say not all devices support much bigger sizes. But again, I like to test with huge amounts of images and big atlases.

The code to determine the best size (less waste) is there, but it isn't yet implemented because I haven't been able to test it torhougly. I wanted to release this early on to see what your thoughts might be on formats, features, etc.

It's already useful to me as-is, but I do see a lot of room for improvement.

The tool you linked to looks nice, but it lacks a means to invoke it directly without a GUI (as far as I can see).
To humour you I selected all files from the test directory on my laptop (around 2200 small sprites). The screen froze for 5-10 seconds and it then displayed the sprites.
I then added them to be packed, Had a small delay... then I was able to click "pack" ... I'm still waiting, it's been 5 minutes, entirely unresponsive single thread application.

Not to offend whoever developed it but it's clearly showing the same signs I found on every other tool out there, they are not responsive and they can't take the load of big projects.

In reality I'm hardly using as many sprites, but some projects do require vast amounts whether they use separate "pages" or one big atlas, the generation process (to me) should be as seamless and fast as possible, because you may want to invoke it as part of the compilation process or deploying process depending on your needs.

A good content manager will anyway attempt to read the separate file first, if it contains newer data than that of the atlas (or given any other condition), but being able to quickly generate the atlases is to me a very good thing.

I'm going to close the program now, it's been too long and it hasn't responded. I'm sure it works fine with small amounts of images, but it already requires quite a few steps from the user just to get the atlas packed and saved, specially the list setup. That's clearly what I'm trying to avoid on this GUI-less version. Input directory > output atlas (given N amount of conditions and settings).

I've contemplated the idea of adding rotation support, but it will inevitably increase the packing time as it would require a heuristic method to assert whether the given alternative rotation provide a better coverage or not. It would however be useless if the packing occurs on RECT bounds and the image is square instead of rectangular though, as both orientations would take up the same space (same rect bounds).

Anyway thanks a lot for trying it out, I'll be releasing a new version soon with new data formats (including one for your tool).

GuShh(Posted 2014) [#4]
Beta 5 is available here:

Changes: Added support for Slick2D, TreSensa and "Texture Packer" (See Soap's URL) data formats.

Nobuyuki(Posted 2014) [#5]
I look forward to some sorta texture packer that isn't closed-source for once. Never really made sense to me why monkey-community people would do this closed-source business for tools like these, since there's practically no market for that kinda "basic" middleware. Organizing the system by grouped pages would be great too of course, but the lack of this feature is kinda what prompts my personal request for open source in the first place. That, and output formats. Instead we have to choose from a number of solutions that can't be custom-fit because the program can't be modified, if you know what I mean. I suspect the lack of open source in previous projects has something to do with the bin-packing algorithms involved, but I can't prove that...

GuShh(Posted 2014) [#6]
I'm sorry but what business are we talking about? This tool is FREE for both commercial and non commercial projects! I state this clearly. You don't have to pay for an expensive license for weasel-software to unlock limitations (I won't name them).

A plugin SDK will be fitted for anyone to add their own format, but as you've seen I can add them very quickly. The bin-packing algorithm used here is not patented as far as I'm aware, It's merely a binary tree. I'm not sure you'd be able to implement a plugin with Monkey directly unless you use C or C++ for the structures.

From my side, I would worry some weasel would take the code, change a few labels and begin selling it, which isn't unheard of. So there are two sides to this, It's not paranoia, you can also expect people to rip off your games specially in Asia and you wouldn't be any wiser, of course that's another story...

I would share the code with this community, but given an SDK and good support, is there really a need for something most people won't even care to look at? Because I see this a lot with open source projects, they go stagnant very quickly for the most part. That's why I also wanted to release this early because the more people get involved the more motivated I'll be to continue this, instead of talking "I'm doing this, and that, and that as well" but never showing anything in return (vaporware).

So that's how I feel right now about tools and open source, I might change my mind later on thought.

Just to be clear, the commercial tools available are not giving you their source code after you paid for the license and support is sometimes scarce. But my biggest issue is how slow and heavily dependent on third party code the available solutions are.

I hope this doesn't sound too negative or narrow minded, I do think everyone is entitled to do whatever they want with their own code / creations though, In essence I'm not saying "no" I'm just saying maybe :)

If you have a specific data format you require please show me some sample data and I'll make sure to implement it on the next version.


Nobuyuki(Posted 2014) [#7]
of course there's a use. That's why I would even request open source in the first place. Being able to adapt the tool to specific purposes would be nice, improving the bin packing algo for specific uses (making tilemaps, keeping animations together, adding priority factors, etc). I was talking about the business of marketing the middleware itself, honestly.

If you're afraid "some weasel will come steal it", I have good news and bad news -- the good news is that if anyone finds it worth doing that, then at least your code has some value and I was wrong about its commercial middleware applications. You can find legal recourse in a copyleft license, or a dual license, or just make your code better than your "competition". The bad news is that probably no one cares to steal code to such a simple (in concept) application, and it would only be useful to other people who want to use it to build atlases for their games. The only thing that would be of much interest would be the bin-packing algorithm, and like I said, I get the feeling that there aren't enough clever people on here to have come up with a novel one worth trying to hide -- If that's the case, then why not share it, since there's no good Monkey ports of a bin-packing algo in the public sphere yet?

With my OSS projects, I don't expect anyone to contribute specifically, but it's nice when they do, and I am excited by fixes and/or change thrown my way. I haven't come across anyone so crass yet that they'd want to "weasel" my code and re-accquisition it for some commercial middleware. This is a small community, people would notice. Not to say there isn't competition in this community for mindshare, but again, I'm not looking to make a fiefdom where the only people invited are people who want to do things my way or the highway. I just want some respect. Conversely, you'll earn respect from your peers by providing a useful service in the form of your code, and hey who knows, someone may want to improve it and send those improvements back upstream to you instead of keeping it to themselves for an internal project.

Anyway, I don't consider you narrow-minded for not believing in open source for this kinda thing, though. You're not the only person with this attitude, so don't feel personally insulted by my opinion on the matter. Even the person who pays me gets that "fiefdom" attitude from time to time with the code I develop internally and release publicly. Don't lose sight of the goal -- the games, not necessarily the middleware :)

GuShh(Posted 2014) [#8]
I don't feel insulted by anyone's opinion, it's their opinion and I accept it.

However there are plenty bin packing algos out there with source available in most languages, I'm pretty sure most of it is at least an order of magnitude better than mine. However If it's such a simple concept there wouldn't be a need for me to release any code, since anyone could write it (and anyone can if they set their minds to it). There's nothing to hide here, everyone is entitled to do what they want with what they create, Not going opensource is not always a bad thing -- There are also multiple papers on binpacking that are freely available as well as plenty good books to read on the subject so whether I share some code or not, I don't think it would make a difference.

Again, In this case my goal is not to share code, it's to share a tool. I suggest a new topic to discuss bin packing if that's within your interest. Otherwise we're getting a bit offtopic!

For what it's worth this tool was not developed in Monkey or any BRL product for that matter, the codebase was programmed many years ago and recently implemented into this tool which I'm still working on and with your help it can be much better than it currently is. There's no hidden agenda here, We all benefit either way (open source or not).

Perhaps the middleware is what I'm interested in, not games entierly. Everyone is free to pursue their own ambitions and passions.

zoqfotpik(Posted 2014) [#9]
"I would worry some weasel would take the code, change a few labels and begin selling it"

Since you are not making any profit from it, why would you care? Do you know how little money there is in texture utilities? You're better off writing a Flappy Bird clone.

My guess is most of the people here wrote their own asset packers. I did. Much easier to integrate with a pipeline that way...

Paul - Taiphoz(Posted 2014) [#10]
zoqfotpik does the fact that some one is not selling something mean it should be open source?

GuShh(Posted 2014) [#11]
zoqfotpik: If you want to argue please join 4chan, this is not the place. There's also no requirement for you to use my tool, you are free to use your own and open source it if you want to.

Paul - Taiphoz: I agree, plus nobody can force you to opensource.

Anyway these are both offtopic discussions that are not pertaining to the tool itself, only personal opinions on open source vs closed source. Either way it's free, no need to argue over it. Once the SDK is implemented, you won't have a specific reason to say "it doesn't support my pipeline / format".

A new version is coming up with extra formats and features.

Nobuyuki(Posted 2014) [#12]

Okay, fellas, stop antagonizing each other.

GuShh(Posted 2014) [#13]
Please remove that stupidity and go do something productive instead of wasting my time. Thanks. This is exactly the reason why I won't opensource.

Shinkiro1(Posted 2014) [#14]
Hey, that looks nice.
Do you have any plans to release an OSX version?

PS: The benchmarks look impressive (my own packer always takes forever -.-)

GuShh(Posted 2014) [#15]
Hi Shinkiro1, I could actually compile on OSX but not at the moment (also of course Linux) since my code is cross-platform compatible right now (some optimizations will have to be targeted toward each platform, which is a time consuming process though).

Let's add it to the "planned" list however!

I released beta 6 today, you can get it from here:

The new major feature is "AutoSize", the changelog gives you a better idea of what's going on, There's also a documentation file now and new options on the configuration file.

The docs are simple but down to the point, they describe every configuration option and the internal binary format in case anyone cares for it.

If you find any errors please let me know, I can't really test this in depth all by myself!

Have fun,

GuShh(Posted 2014) [#16]
Bug found on certain instances where AutoSize is used (overlapping images for those that didn't fit) will be fixed on next release, it's a tiny bug in the detection code that shows up depending on the size of the sprites, specifically the first packed sprites (which are the biggest). The heuristic simplifies the detection by not having to do a full blown bounds check, this means it's very fast, but small errors can leave "stranded" images. It's all very experimental!

GuShh(Posted 2014) [#17]
Beta7 is out:

It allows for a new option in AutoSize called BoundsCheck to prevent possible overlaps (off by default, since it performs a full blown bounds check instead of the simple heuristic it uses by default, so it is a slow option and should only be used if packing errors are found while using AutoSize).

It's also worth mentioning AutoSize -is- slower than defining a fixed atlas size, this is simply because we are doing N amount of packs to reach the most efficient size, so we are basically (logically) packing more than once using AutoSize. Of course these are numerical packs, not graphical. Only the last step of the process involves the renderer.

Assumptions on a final atlas size can be made given a raw total volume of images, but it's not going to be an educated guess, the trial-and-error method just works.

Either way for atlases with under 200 images I don't think you'll find any noticiable speed difference using AutoSize. Let's be realistic, most games hardly ever use as many images, but the goal here is to be efficient!

That's all for today!

Soap(Posted 2014) [#18]
>most games hardly ever use as many images

Most of mine use many hundred in part because I render 1x and 2x assets. 1x for low resolutions, 2x for normal resolutions. Each x is kept in its own set of atlases though.

GuShh(Posted 2014) [#19]
That's a good point, all the more reason to keep it fast!
I'll be implementing JPEG support soon, including other nice features.

Would you reckon a function to generate low resolution versions of the assets could be useful? Such as mipmaps but with only a few levels. Not entirely sure how I would implement this in a transparent way though, perhaps appending "_low" to the 1x level images could work. Of course initially only a linear scale would be allowed with alpha channels, since it's otherwise a bit more complicated to implement. I'm thinking your separate atlas approach is a lot cleaner and allows for loading on demand.

I've been trying out the App Game Kit format on Monkey (since it's the simplest format I've encountered thus far) I came up with an Atlas class, which is extended as "AppGameKit_Atlas" where the magic happens, the parent class keeps the image handle for the atlas and a string map to address the images per name. The child class merely implements the New and Load methods to deal with the specific format, then there's a basic Sprite class to keep the data of each image and implement a simple render method.

I'm not entirely sure if using LoadString and the Split method is the fastest way around parsing the text file, but it certainly is a simple way to do it. Once I clean up the code I'll include it with the tool as a means of a starting point for "roll it yourself" atlas support. Of course many frameworks already have support for a few existing formats.

Thanks for testing!

GuShh(Posted 2014) [#20]
Beta8 is now out! Please visit for more information, or get it directly from:

Changelog for this version:

06/03/2014 - Multiple loader formats are allowed now, including subdirectories.
JPEG is now supported for both import and export operations with compression config.

There's a new loader option to enable or disable subdirectory scanning, JPEG can be both loaded and saved now, with compression setting (default to 8 from 0 to 10, it's in the docs).
AutoSizing is slightly better now, but still working on it.

Loader can now interpret multiple format patterns, for instance you may choose to only load PNG and BMP images, thus using the pattern: "*.png|*.bmp"
For a "catch-all" use "*.*" (not highly tested)

All sorts of other internal minor fixes and additions for better stability.

A very minimalistic GUI is in the works, but I can't promise anything at this stage. However suggestions are welcomed, as always :)


GuShh(Posted 2014) [#21]
It's been a while, but here's the latest version for those who are interested:

Padding has been implemented, a simple edge-padding feature is also present but it's still experimental (corners missing). The "SeparateAlpha" feature has not been implemented yet, however you may use "OnlyAlphaChannel" to generate only the alpha channel.

Also heavily experimental are the MipMap options. The "ScaleLevels" option is not implemented, only one level can be generated at the moment. The other options should work fine. The rescale algorithm can be chosen. Alpha is always retained.

These new features are still experimental, therefore they are not documented at the moment since they're subject to change.

A counterpart to this tool is being developed, currently in alpha stage it's the Unpacker, which can take any sprite sheet and unpack it into separate images without any metadata. Very useful indeed.

The packer GUI is being developed, but due to the amount of work involved it may not be available for free. However the console application will always remain freeware. We're talking about a small licensing fee anyway, nothing we indies can't afford. A lite version of the GUI may be eventually available free of charge anyway.

Let me know if you find any issues or if you would like to see any specific feature, I'll try my best!

For testing purposes a small sample set of sprites made by Hyptosis are also included for the time being, these are actually royalty free as far as I'm aware, but you may want to contact the author for more information in case you want to use them in your project.

Newer versions and other relevant info may be found here:


Soap(Posted 2014) [#22]
Woo for updates! Glad to hear you'll be putting a price on it. Commercial dev is best dev.

Is there an option for output folder?

What's I'd want to do is "MonoPackB9c.exe sample output" so that files are put into the output folder. An option to override the config JSON too to define a different config file from command line? Config file should be able to select of which formats to make. I would like to not output any formats I do not want.

No multi page support?

It looks like if there is a JPEG in a folder then it's not probably being combined with other assets - it is put behind other PNG assets .. I'll e-mail you a result.

GuShh(Posted 2014) [#23]
Hi Soap,

An option for output folder will be included within the next release.

Config already allows to select the output format, it's just that if you define "all" it outputs all of them (it's set to 'all' by default for debugging purposes).

Under "exporter":

"Format" : "all",
will output every format

"Format" : "appgamekit",
will only output appgamekit.

The docs show a list of the formats and their names. The "Unity3D" format was implemented recently but it's not present in that version.

Overriding the config path is a nice feature, I'll add it to the next version as well.

It would also be nice to have the option to use a separate config file per directory, where it would automatically load the file from that path without user intervention, otherwise the default would be loaded (in case no specific config was found).

I'm going to take a look at your email and the attachment to see what's going on, I opened "src_full.png" and at a first glance it looks very wrong, Could it be a fault of autosize?

If by paging you mean one atlas per directory, then that's also planned. I'm currently refactoring some of the code to speed things up so once that's done, I'll implement this feature as well.

I've been busy with some other tools lately, plus their GUIs. I've got a small implementation of the "AppGameKit" format on Monkey, the code seems fine to me (I'll upload it later) but perhaps someone with more Monkey experience might be able to refactor it into something better.

The way you end up invoking a sprite is: atlas.SpriteMap.Get( "player_red" )
There's also a dummy render method, which for direct access ends up being: atlas.SpriteMap.Get( "player_red" ).Render( x, y )

I'm not sure if string maps are fast enough in Monkey, but at any rate if speed is required perhaps some other method should be used...

GuShh(Posted 2014) [#24]
Quick update:

07/04/2014 - Added support for the Unity3D format.
08/04/2014 - Destination Path is now the second command line parameter the third parameter is Destination Name.

The docs contain a small example for the paths and names.

Currently no command line "switches" are available. However this will change in the near future to aid in readability and user friendliness.

Soap: will be looking into the bug/s later this evening.

Soap(Posted 2014) [#25]
What I mean by paging is that say you have a fixed atlas size of 1024x1024 - you would make new atlas images called altas_1.png ... atlas_5.png as "pages" until all assets selected can be placed into atlases. The other image I put in e-mail showed how we currently output atlases. We use 1024x1024 sized atlases because otherwise certain Android devices would not be able to load the game.

Being able to by force a single atlas per directory would be useful in certain cases. The more options the better!

-silent command line option for making it not require pressing enter to close after it completes without errors? that way I can have a batch file with multiple calls to the tool which execute after each other in more automated way

rebuild_atlases.bat is the exact thing I ran to make the atlases which look a bit buggy. I am not sure what is causing it, but it looked like something to do with mixing asset types at least to me.

GuShh(Posted 2014) [#26]
No silent command, but currently in the config (undocumented but added on the last release) you can switch it off it's called "WaitForInput"
Verbose / Silent modes will be added once proper commands are implemented for all options.

GuShh(Posted 2014) [#27]
MonoPack just got a bit more powerful! ( X64 and x86 binaries )

Full commandline switch support, while still being able to define all settings through the configuration file.
The configuration is first loaded, then the command line switches are parsed, if applicable they will overwrite the previous configuration settings.

Aside from the existing configuration options, a few special switches were implemented:

/padding - Defines packing X and Y padding at the same time, shorthand. example: /padding 10 - sets 10px padding on X and Y
/silent or /s - Disables the default verbose mode (no output). No parameters.
/batch or /b - Disables waiting for input and enables Silent Mode. No parameters.
/deploy - Same as /batch but it disables reports. No parameters.

This release contains no bug fixes.
Reported bugs: Possible issue with hex colors on command line switches

The next release will contain bug fixes and new features.

Soap(Posted 2014) [#28]
Have not been able to test this version yet, but as always thank you the updates. Those features are very useful!