unwrp is a tool that automates extracting of .smod archives and decompiling lua, with some fancy new formatting to make it easier readable.
Disclaimer:
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
Installation
- 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.
##Troubleshooting
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.
Now I’ll get into the nitty-gritty .lua files. Maybe even change them before I run the game again.