Modding FAQ

From Stonehearth Wiki
Jump to: navigation, search

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[edit | edit source]

Q. Are there any "primers" on modding Stonehearth?[edit | edit source]

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:

Q: What is a mixinto?[edit | edit source]

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?[edit | edit source]

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?[edit | edit source]

See this post.

Q: What does file(...) do?[edit | edit source]

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?[edit | edit source]

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?[edit | edit source]

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?[edit | edit source]

Compress the mod folder using zip compression and change the extension of the archive from ".zip" to ".smod".

Advanced Questions[edit | edit source]

Q: Can you use mixintos to modify a .json array?[edit | edit source]

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?[edit | edit source]

.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?[edit | edit source]

No.

Q. Can I view debugging information?[edit | edit source]

Yes. Set set enable_debug_keys to true in your user_settings.json file.

Troubleshooting[edit | edit source]

Q. Why did my mod stop working after a Stonehearth version update?[edit | edit source]

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[edit | edit source]

Q. Where are my Stonehearth files located?[edit | edit source]

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

Q. Where are my settings stored?[edit | edit source]

User_settings.json.

Q: Will you replace the term "mixinto" with "extension"?[edit | edit source]

Maybe. If we do, it will just be a syntax change.

Examples[edit | edit source]

Q: Can I get trees to drop wool?[edit | edit source]

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[edit | edit source]

Q. How can I reduce my loading time? / How can I create a smaller world?[edit | edit source]

Try adding this to your user_settings.json:

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