Unwrp r22 - A tool to easily extract smod files and decompile luac (now with pretty formatting!)

unwrp is a tool that automates extracting of .smod archives and decompiling lua, with some fancy new formatting to make it easier readable.


Beware. You can mess up your Stonehearth installation if you modify files in… an inappropriate way. Looking should be okay-ish, modifying is a bit dangerous. Any update could break this tool or your current setup, requiring you to re-download the smod files/validate the game cache/remove your modified folders.

Because I’m sure we’re going to do this quite often (and already have in the past!), I have written a little Java program that takes care of the most tedious tasks: Unzipping the smod files and then decompiling the lua files.

What unwrp does

  • Extracts all .smod files in the current directory (by default, the directory you’ve placed the unwrp.jar in) into the same directory.
  • automatic decompilation of luac files using unluac (bundled in the jar under the MIT license).
  • Re-formats unluac’s output a little bit to create more readable code
  • Renames the smod files by attaching a timestamp to their file extension. If things break, you can simply rename them back to restore normal game functionality.
  • Optionally allows for existing folders to be backed up


  • Download and install Java in case you have not installed it yet. Version 6 is required, but version 7 is recommended. Personal recommendation: If you install Java just for unwrp, make sure that the browser plugin is not installed or at least disabled.
  • Download unwrp.jar. Save it in your Stonehearth/mods directory.
  • Double-click the unwrp.jar. It should start the program and extract the files. If everything went smooth, there should not be a box complaining. In case there’s this little black window complaining about something, please see “Troubleshooting” below.
  • If double clicking it tries to unzip (or opens it in some sort of file browser): You need to start it with Java. Either right click -> open with -> Java™ Platform SE binary (or similarly called) or use this batch file (placed in the same directory as unwrp.jar).

Advanced usage for advanced users

unwrp has a bunch of functions that can make your life more convenient. These are command line arguments, i.e. to be executed in a batch file after the jar. I’ve included example commands to run it (which can be placed in a normal batch file). These are optional and not required. I recommend them only for people that have worked with command line tools before.

  • --zip
    If a folder already exists (say there is a radiant.smod but a folder named “radiant” already exists) unwrp will zip the current folder and save it in the same directory as unwrp.jar, labelled with the name and time. This is useful to create backups of your modifications in case an update happens, which would overwrite your changes.
    Example: java -jar unwrp.jar --zip
  • --dir [some path to a directory]
    Instead of using the current directory, unwrp will search for smod files within the specified. This can be used to have unwrp in some other location, for example your modding folder. Keep in mind to use “quotes” if your path has any white spaces in it.
    Example: java -jar unwrp.jar --dir "C:\Program Files (x86)\Steam\steamapps\common\Stonehearth\mods"
  • --keep-luac
    Usually, unwrp will decompile luac files and not extract them directly. With --keep-luac, you will get both - the decompiled lua and the original luac file.
  • --verbose
    Starting with r15, unwrp is silent. Only if there’s an error encountered it will actually display something - otherwise, it will work completely in the background. Verbose disables this behaviour and reverts to the old, spammy “Print everything” attitude.
  • --no-renaming
    Somewhat pointless if you intend to mod because smod files are prioritised over folders - but in case you just wish to peek without modifying, this is the option for you. It won’t rename the .smod to the timestamped version once it’s done.


Instead of opening the program, it tries to unpack/unzip the downloaded jar!

You need to open it with Java, not a zipping program. Right click -> “Open with” -> “Java™ Platform SE Binary” or similar, alternatively use the batch file as provided under “Installation” above.

Something doesn’t work while extracting!

If unwrp fails, it will tell you why. Copy-paste its output here and I’ll see what I can do.

###I receive “Permission denied” or “Cannot create …” errors!
By default, Windows Vista/7 do not allow programs to write into Program Files. You need to run unwrp as administrator - which likely requires you to download/create a batch file to do that and run that one as administrator (shift-rightclick on it, then “Run as administrator”).

I’ve extracted and changed something and now it crashes/I have some weird issues/bugs

This tool is dedicated to those who wish to know how Stonehearth works and how to modify it. If you really did manage to break your installation, it’s not a big deal. There are several ways how you can restore your old installation. You can either have Steam re-download the smod files (and therefore ignore your modified folders) or smply rename the last “.smod [somedate]” file back to “.smod”. Delete your mods/stonehearth and mods/radiant folder just to be sure. In the worst case, you can try a re-installation.

Post post (because horizontal lines are so hardly visible here)

This tool is licensed under the MIT license. I might make the source public at some later point.

Discourse release because I’ve accidentally re-compiled it today to find out that the new unluac does not mess up the files anymore - i.e. there’s no need to replace some lua files with the original luacs (for now).

But just in case, I’ve added --keep-luac and because I was so annoyed at unluac’s formatting and I happened to have Eclipse open anyway, I’ve added some minor formatting. It’s just a bunch of newlines here and there, really, but I think it makes a huge difference. It’s very likely that the formatting is going haywire here and there, if you could post the code snippet where this happens I can take a look at it and see how to adjust the rules for it.

If you want to see an (in the meantime already outdated) example, have a look at unwrp’s version of log.lua and unluac’s version. There’s still some things that need to be tweaked but it’s a step in the right direction. Also, the rules for these few changes are already quite… confusing.


So, I’m just now noticing this amazing tool. However, it doesn’t work for me at all.

When I run it (with --verbose), I get the following:
unwrp v22.
Check C:\Program Files (x86)\Steam\steamapps\common\Stonehearth\mods…
Zipping disabled. Continue extracting…

Extracting radiant.smod…
Unzipping radiant/client.luac into C:\Program Files (x86)\Steam\steamapps\common\Stonehearth\mods.\radiant\client.luac…
radiant/client.luac is a file.
Exception in thread “main” java.lang.IllegalStateException: The input file does not have the signature of a valid Lua file.
at unluac.parse.BHeader.(BHeader.java:37)
at unwrp.Main.extractPackage(Main.java:311)
at unwrp.Main.parseDirectory(Main.java:82)
at unwrp.Main.main(Main.java:72)

I suspect this is a TR problem, but, @RepeatPan, could you possibly be so nice as to help me make sure that’s the case?

The way Lua-files are handled in Stonehearth has changed…

To read them now you can take a look into this thread…

Thanks, @voxel_pirate, I’ll look into that.

@voxel_pirate is right. There is a successor to unwrp written in C# that’s much nicer. However, it’s also a lot less designed to be used by others (as in, if there’s something wrong, it will just crash - without necessarily telling you why or what).

I dislike the other minifier because I need to work with files, not some browser thingy. With bare files, I can use whatever tools and editor I want to - and some of these are way mightier than the unminifier.


One of these days, I’ll get to actually learning a scripting language. Lua seems like a good candidate…

Thanks for the info, @RepeatPan. I agree that bare files would be more useful.

If you want to go ahead and use the new RP.Unwrp anyway (it works fine for me, although your mileage may vary), just click on the present and unzip it to your mods/ directory:


Make sure that you have no file opened inside the stonehearth/radiant folders and make sure to never have the folder and the .smod active at the same time, that results usually in black screens or similar.


Works like a charm. :slight_smile: Now I’ll get into the nitty-gritty .lua files. Maybe even change them before I run the game again.

I know, I’m WAY behind the times in learning how SH works, but hey, it’s fun!

Many thanks to you Mr RepeatP
Many thanks