Stonehearth Modding FAQ

hey folks! as more and more of you are joining the modding ranks, it seemed fitting to provide a starting point to answer some of the more basic questions floating around…

below is an initial list comprised primarily of questions from @RepeatPan and @sdee… this is a first pass however, and the format may be adjusted a bit over time… we will of course supplement the FAQ as more material presents itself… :wink:

we’ll leave the thread open, so feel free to pose any suggestions you may have (in q&a format, of course :smile: )… please refrain from posing general modding questions here though…

Stonehearth Modding FAQ:

Q. Are there any “primers” on modding Stonehearth?
A. Yes. You can read this post which introduces the mixinto and override concepts, or this post which discusses the entity/component framework.

You can also try downloading the startermod_basic mod from the stonehearth github repository. Read the Readme and get started! GitHub - stonehearth/startermod_basic: A most basic starter mod to get you going!

Q. Where are my Stonehearth files located?
A. Steam: C:\Program Files (x86)\Steam\SteamApps\common\Stonehearth
A. Humble Bundle: C:\Program Files (x86)\Stonehearth

Q. How do I extract the .smod files?
A. They’re zip files. You can use any zipping program, such as 7z, WinRAR, etc.

Q. Can I work with my extracted mod folder?
A. Yes. Note that Stonehearth will prefer smod files over folders though - if you have a folder named my_mod and an smod named my_mod.smod, it will always load my_mod.smod and ignore your folder!

Q. How can I create .smod files?
A. Simply zip them using any zip program and change their extension to “.smod”.

Q. What are luac files? How can I open them?
A. luac are compiled lua files. To convert them into readable lua again, you need something like unluac. This is fairly complex however, and there are tools to help this process [TODO: link to @Xavion’s tool, perhaps?]

Q. Where are my settings stored?
A. user_settings.json.

Q. Can I view debugging information?
A. Yes. Set set enable_debug_keys to true in your user_settings.json file.

Q. How can I reduce my loading time? / How can I create a smaller world?
A: Try adding this to your user_settings.json:

"mods" : {
   "stonehearth" : {
       "world_generation" : {
               "method" : "tiny"

Q: What exactly, is a mixinto?
A: A mixinto lets you inject additional content into an existing .json file. (.json data files hold almost all of Stonehearth’s mutable gameplay parameters) The easiest use for this is to replace values defined in existing json.

The more complicated (less documented, stable, and supported) use case is to add wholly new content to existing .json files. (This is dangerous because the format of those json files is not yet finalized, so the section you’ve modified may change or go missing.)

Q: What, exactly, is an override?
A: An override lets you replace any file in the game with another file. Use to replace assets with other assets. If you use this to replace code files with other code files, Team Radiant is not responsible for the results, or the mantainability of the edits going forward.

Q: Can you use mixintos to modify a .json array?
A: Yes. The modifications are added to the top of the array, though this may change in the future.

Q: How do I know what files are possible json targets for mixintos, and how do I reference them? Should I use their alias, or filename, or what?
A: See this post

Q: Will you replace the term “mixinto” with “extension”?
A: Maybe. If we do, it will just by a syntax change

Q: What does file(…) do?
A: file(…) is a shortcut that makes it “easier” to declare filepaths in json.

  • First, it appends the mod directory to the path in the parenthesis. As @RepeatPan mentions, file(/foo) is equal to /my_mod/foo
  • file() can also be used to append the path to the current directory: file(mystuff.json) is equivalent to /my_mod/path/path1/path2/mystuff.json
  • Finally, if the path inside a file() statement ends with a folder, and not a file with an extension, it will automatically append a file of the similar name.json to the path. For example, file(/stuff) becomes /my_mod/stuff/stuff.json

Q: Can I get trees to drop wool?
A: Yes! The resource_node determines what is dropped by a tree or plan when it is permanently harvested. Change the inside a tree.json (like, oak_tree.json) change the resource from stonehearth:oak_log to stonehearth:wool_bundle:

"stonehearth:resource_node": {
     "resource": "stonehearth:wool_bundle", 
     "durability": 20

Q: Can you use mixintos for html code?
A: No

Q: Can I mod in-progress features?
A: You are completely free to use our (Radiant’s) stuff, with one caveat. That is, you can use any item that is in the game, or any playable feature – but we ask that you not modify or otherwise use unreleased features or content. We know that in some cases code for an unreleased feature may be present in a given release, though in a dormant state. Please wait until something is official and playable before, um, playing with it. You don’t need to ask us for permission to use our stuff… but we’d appreciate a credit when you let your creation loose upon the world.


This is more of a question towards the modders instead of modding itself:

How hard is it to keep track of the original game’s updates and improvements? Do you need to alter alot of you want to keep the mod up to date as well?

(If this question isn’t fitting for this thread, you may delete it @SteveAdamo)

It really depends on what your mod does; the first few that I’ve written in R6? using the first draft of RP actually still worked with R27 without issues… and probably still would with R34 if I didn’t decide to rename a few things.

Tracking the changes per se is possible if you use something to diff the files, personally I have two git repos (one for stonehearth/, one for radiant/). That way I can check for modifications, restore files if I need to modify them and more.

1 Like

Unless I’m missing something the luac files aren’t actually compiled lua, but minified (using something like GitHub - stravant/LuaMinify: Lua source code minifier., in which all unnecessary comments, spaces, line breaks stripped out and variable names shortened) so they can be opened and modified with any text editor.

I’m guessing at some point they actually were compiled (version I’m looking at is alpha 5), so do we know if Radiant plans to go back to compilation or is the minified format here to stay?

1 Like

You are right. Until 3-4 updates ago all the luac files were compiled / obfuscated. This made modding a pain because you would have to decompile in order to modify. However, they were not minified, and were a lot easier to read once decompiled.

As to whether or not minified is here to stay I couldn’t say for sure, but I would guess it is because everything has been switched over


I would say it is a lot harder to modify lua now. The decompiling was easy enough with the programs some guys made.
I know it is faster, but I hope Radiant will also give us some way to see the un-minified version of the lua files.

I have a question: Is it possible to create the voxel models using another voxel program with .qb export capabilities?

I hope they do. Modding, right now, is way more difficult than it was before. The decompiling wasn’t exactly neat either, as some files refused to compile - but I would much rather have had that (or some hybrid) than minification. It simply makes it much harder to read the code, even if you are able to format it properly (which unluac had to do anyway).

I’m afraid however that this is meant to stay - the vibe I’ve always got when it came to modifying core game files was that they don’t want us to. Sure, modding and all, but only with official API, the official way. The step to minify the source might just be a coincidence, maybe they did mean well - but I can’t help but feel like it’s another step towards a rather closed source base.

can’t really fault RE for protecting their source code though… and surely it won’t be an issue once there’s a robust modding API in place …

It’s not really that though (ATM at least). It’s just harder to read, not properly obfuscated.

Now, not modding the core files is all fine and dandy, but it does mean that learning from those same files just got a lot harder for new modders. Personally, I’m not sure that’s worth the extra kB in storage saved or w/e.

1 Like

Sadly, you can either have a greatly modified game (such as we had), or closed source. It’s really difficult to balance that. Especially if you can’t just tell a team of programmers to do nothing but API programming. One of the strong points of Stonehearth was its ability to be modded, which was part of the reason I’ve backed it. However, it seems that nowadays, this is a simple buzzword without any meaning. “I can change the font” is already a “modable” game.

As @Teleros said, there’s learning involved too. I wouldn’t know half as much as how the game works if I wasn’t able to read the code and understand it. In addition, an API might only do so much - however, if you can modify the source directly (which can be done as standalone, like most of my creations) you gain much more leverage over the game.


Well before we all get out our pitchforks, maybe we can just ask @sdee or @Tom what, if any, intentions they currently have regarding modding and the Lua code. :slight_smile:

It’s probably more of a question for @Ponder.

Certainly, over here, in my far corner of the code base, my ever expanding collection of comments and docs wait with baited breath for a larger audience than just us six. :wink:


I wasn’t around for the early days, but I find the history here pretty interesting. Much more of an education than I expected :smile:

As someone who has to support frameworks in my day job I can definitely appreciate trying to hold folks off until things get more settled. While most folks are understanding that things will change there always seems to be a group of folks that get very angry about change and are very vocal about it. Trying to mitigate that can really slow things down and poison the community. StoneHearth still has a long way to go to get some fundamental features, like mining, implemented which could change how things work. Or maybe the AI approach doesn’t scale and they have to start over. Who knows.

So, I don’t get the vibe that something evil is going on. To @sdee point there are even some of the placeholders for doc in the smod file. Overall, I’m pretty pleased with the amount of things that are being shared. The biggest concern for me is probably the qb files and the animation. I have more concerns around the lock in there than the code. Our options are a decent tool, as far as I can tell, with overzealous (imo) paranoia/protection or free tools that are pretty limited in what they can do. I think that is just more of a market limitation right now though as there doesn’t seem to be a widely accepted voxel file format so there is limited competition.

That being said, the minification definitely makes things more difficult, intentionally or not. I can get by pretty easily with the white space removal, but shortening the variable names and the constant recycling of them for different assignments really makes it hard to understand the intent. A downside of a weakly typed language I suppose.

Anyway, to my original question. I thought it might be better to put this topic in the wiki, so I ported over what is up top and made a few modifications. Hopefully this is ok.


We had to move away from compilation when we turned on LuaJIT by default. The LuaJIT byecode format is incompatible with the standard Lua bytecode. If you’d still like to look at unobfuscated source, there are a lot of Lua un-minifiers (magnifiers?) which can transform the code back into a readable form. I just tried Lundary on the latest source and it works like a champ!

Let it be known (BONG!!!): many of the core game system are still being developed. Mods which rely on overriding source files, monkey patching functions, and other nefarious (though sometimes necessary!) tricks may stop working at any time. Frankly, even the data-formats are still undergoing change, albeit at a much slower pace. Modding is extremely important to us. It’s one of our three core tenant, and why a majority of the core game play is written in Lua so modders can get at it. It’s still very early days, though. Things will get better over time, but not until core systems become more stable.


I would love to know how Lunadry knows that m was originally carpenter_class without any sort of mapping. The issue isn’t the formatting per se; that was something unluac did to make the decompiled bytecode pretty. As I’ve said, compiling and decompiling with unluac would yield the same results again. The real issue is that everything has been renamed to, well, being minified, which makes the code hard to read for humans.

I would go on a limb and claim that many of the core game systems will continue to be developed for some time. There isn’t an official API or documentation for anything yet, therefore there shouldn’t be any kind of game-changing mod. Do you really want to suspend the modding community in an artificial beauty sleep until you give the green light for modding? Where do you think Minecraft would be today with that strategy?

I know I’m repeating myself, but when somebody wishes to play with fire, then let him. It’s his responsibility if he gets burned, not yours. You’ve stated over and over and over again that everything is work in progress, everything can break and if somebody ignores that it’s his fault. Hell, I’m pretty sure Minecraft (again) doesn’t have any sort of stable API judging by the amount of complaining everybody does when a new major update comes out. They do pretty fine, community issues aside.

If you can turn off the variable naming minimization that would be all that I can actually complain about, really. As for now, it just looks like we’ve got from bad to worse (as mentioned by @Programmierer I think who said that he had to rename all local variables before he could get going with scripting - it’s hard enough to work with uncommented code as it is).


Ok, variables names will be back in the next unstable build. Hopefully soon.


Great :thumbsup:
That is a big impovement for readability of the Lua.

1 Like

I guess this means I’ll have to update the wiki page again now. But it is well worth it :smiley: Thanks!


I’ve tried using the lunadry to un-minify the lua code but haven’t been able to get it to work, can anyone provide any advice on what to do, as there doesn’t seem to be much instruction on how to use it.