Modding FAQ

This page was originally a port from the Modding FAQ post on the official Stonehearth Discourse. It was compiled by the community as a set of question and answers about the creation of mods for the game.

=Introductory Questions=

Q. Are there any "primers" on modding Stonehearth?
The best places to get more information on Stonehearth modding are the Developer Blog and Official Forum.

For an introduction into mixintos, overrides and the entity/component framework these posts are especially helpful:
 * Desktop Tuesday, a peek inside the modding API
 * Behind the scenes with Bush #4

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

The more complicated (less documented/stable/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 is an override?
An override lets you replace any file in the game with another file. Use overrides 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 maintainability of the edits going forward.

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

Q: What does file(...) do?
file(...) is a shortcut that makes it "easier" to declare filepaths in .json files.


 * 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. What are .smod files? How do I open them?
The .smod files contain the majority of the games assets, and are simply .zip files with modified extensions.

You can extract the contents of an .smod file using any compression program that supports the .zip format (7zip, WinRAR, etc).

Q. Can I work with my extracted mod folder?
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?
Compress the mod folder using zip compression and change the extension of the archive from ".zip" to ".smod".

=Advanced Questions=

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

Q. What are .luac files? How can I open them?
.Luac files are minified lua files. The minification process removes unnecessary (to the computer) spaces, line breaks and comments, and shortens variable names down to individual letters (ex. n, t, e). This makes it harder for a person to understand, but can improve the performance of the lua processor.

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

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

=Troubleshooting=

Q. Why did my mod stop working after a Stonehearth version update?
It may be that the version field in the mod's manifest.json file needs to be increased. Alpha 14 introduced the requirement that mods be version 2:

{   "info" : { "name" : "my_mod", "version" : 2 }, ...

Keep in mind this requirement isn't arbitrary. It was introduced specifically to prevent loading of older mods, so more significant changes to your mod may also be necessary.

=General Questions=

Q. Where are my Stonehearth files located?

 * Steam: C:\Program Files (x86)\Steam\SteamApps\common\Stonehearth
 * Humble Bundle: C:\Program Files (x86)\Stonehearth

Q. Where are my settings stored?
User_settings.json.

Q: Will you replace the term "mixinto" with "extension"?
Maybe. If we do, it will just be a syntax change.

=Examples=

Q: Can I get trees to drop wool?
Yes. The resource_node determines what is dropped by a tree or plant when it is harvested. Locate the .json file for a tree (for example small_oak_tree.json) and change the resource from stonehearth:resources:wood:oak_log to stonehearth:resources:fiber:wool_bundle:

"stonehearth:resource_node": { "resource": "stonehearth:resources:fiber:wool_bundle", "durability": 20 }

=Other=

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

"mods" : { "stonehearth" : { "world_generation" : "tiny" } },