Jump to content
  • The forum downloads section will be removed on Jan 1st 2023. Players may still download mods that are currently hosted, but new submissions are no longer being accepted. Mod makers are advised to relocate their mods to alternative hosting solutions.

Stexatlaser - Simple TEX Atlas Packer

About This File

Stexatlaser (Stex)

Stex the Stegasaurus

Stexatlaser (stex-atlaser, a play on 'spectacular'), or simply Stex, is a simple tool for generating a (Klei) TEX format atlas and its key from a simple folder structure with no external dependencies required.

It uses an implementation of the MaxRects algorithm to efficiently pack each input element image into a larger atlas image, with as little wasted space as possible. Some empty space is inevitable given that atlases must have power-of-two dimensions.

It can also reverse the process and extract element images from an atlas using its key.

Stex uses the following syntax scheme:

stex <global options> [command] <command options>

The order of switches within each options section does not matter.

Basic Usage

Creating an Atlas
To create an atlas/key, start by setting up an input folder with the following structure:

|-- element1_name.png
|-- element2_name.png
|-- element3_name.png
|-- ...

The available input formats can vary between systems, but most common formats are supported. See All Commands/Options (on GitHub) for more information.

As implied by the above, the folder name will be used as the atlas/key name, and the file names (with the extension ".tex", see Additional Information on GitHub) of each image will be used as their respective element names. All sub-folders and other files will be ignored.

Then run Stex with the pack command:

stex pack -i "X:\Path\To\Input\Directory" -o "X:\Path\To\Output\Directory"

When finished, the resultant atlas.tex and key.xml files will be placed in the specified output directory. You can then refer to each element by its name in LUA without concerning yourself where they actually were placed within the atlas.

If you want to see the element arrangement, try viewing the output with a TEX viewer.

Extracting an Atlas
To extract an atlas, run Stex with the unpack command:

stex unpack -i "X:\Path\To\Input\key.xml" -o "X:\Path\To\Output\Directory"

The key's corresponding atlas, which must be located alongside it, will be read automatically using the name specified within the key.

When finished, a subfolder with the name of the atlas will be created within the specified output directory that contains each individual element as a separate image. This results in the same structure used as input when packing an atlas.


When packed, a folder of images that looks like this:


Will produce the files "test.tex" and "test.xml", which will look like:

test.tex (in a TEX capable viewer)



<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <Texture filename="test.tex"/>
        <Element name="ear-0" u1="0.4375" u2="0.478027" v1="0.329102" v2="0.391113"/>
        <Element name="ear-0 - Copy" u1="0.472656" u2="0.513184" v1="0.266113" v2="0.328125"/>
        <Element name="ear-1" u1="0.372559" u2="0.40918" v1="0.941406" v2="0.999512"/>
        <Element name="ear-1 - Copy" u1="0.372559" u2="0.40918" v1="0.882324" v2="0.94043"/>
        <Element name="eye-0" u1="0.949707" u2="0.996094" v1="0.622559" v2="0.670898"/>
        <Element name="eye-0 - Copy" u1="0.413574" u2="0.459961" v1="0.580566" v2="0.628906"/>
        <Element name="eye-1" u1="0.198242" u2="0.244629" v1="0.173828" v2="0.216309"/>
        <Element name="eye-1 - Copy" u1="0.245605" u2="0.291992" v1="0.173828" v2="0.216309"/>
        <Element name="eye-2" u1="0.505859" u2="0.554199" v1="0.831055" v2="0.865723"/>
... (etc)


Special Feature

Stex has a mechanism for recording if atlases it creates are using pre-multiplied alpha so that it can be handled automatically when unpacking. See GitHub.


View on GitHub for more info: https://github.com/oblivioncth/Stexatlaser

If you believe you've found a bug, please file an issue there instead of just mentioning it here. Discussion otherwise is fine.

What's New in Version   See changelog


This release has existed for some time, but I forgot to upload it here in addition to GitHub. Woops.

Original Notes:

A couple bug fixes and a feature tweak:

  • Fixed an off-by-one error when unpacking a TEX file that caused the output PNG files to be one pixel wider and taller than they were supposed to
  • Changed the feature of adding a safety margin of transparent pixels to input images when packing a TEX to be optional, since it is generally not required and sometimes could cause TEX dimensions to be much larger than necessary (see -m switch in README.md)
  • Debian binaries now correctly use static Qt libs so that the tool can be used without installing them on the end user's system
  • Like 4
  • Sanity 1

User Feedback

Recommended Comments

I'm aware that this exists: 


but obviously it's dated and (seems?) to have some issues so I just said screw it and made something similar from scratch for fun/long-term convenience since I can now easily modify this tool instead of being stuck with the binaries of that one as they are.


Edited by oblivioncth
  • Like 1
Link to comment
Share on other sites

Great tool. It definitely seems like an improvement over the other tool.

Would it be possible for you to release Linux (Ubuntu specifically) binaries? All good if you can't though.

Link to comment
Share on other sites

On 10/6/2021 at 10:49 PM, BlueBeka said:

Great tool. It definitely seems like an improvement over the other tool.

Would it be possible for you to release Linux (Ubuntu specifically) binaries? All good if you can't though.

I don't think this would take much effort to port. At the moment I'm a little stuck dealing with some unexpected crap, but when I can I'll try to make Debian compatible binaries.

Link to comment
Share on other sites

On 10/6/2021 at 10:49 PM, BlueBeka said:

Would it be possible for you to release Linux (Ubuntu specifically) binaries? All good if you can't though.


  • Thanks 1
Link to comment
Share on other sites

un or pack.bat

just transfer this bat file to the same folder with the program. And then just drag the folder or xml file onto the bat file

bat text:
pushd %~dp1
cd %~dp0
stex.exe unpack -i %1 -o .
stex.exe pack -i %1 -o .

Link to comment
Share on other sites

I like your tool. But when I packed. It changed picture size. My original picture size is 64*64. After packed and unpacked. It became 65*64. This made a bug in game.

Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
  • Create New...