Last updated: January 30th, 2019. Latest version here.

The manifest

Your first mod

To start making your mod, create a folder inside the Stonehearth/mods directory. You can name the folder however you want, but it can ONLY contain alphanumeric characters, hyphens and underscores. We also tend to use lowercase only for the folder name.

icon If you're going to upload your mod to the Steam Workshop, you should create your mod folder via the Mods menu. Alternatively, you can develop your mod in the Stonehearth/mods folder, and when it's ready, generate the mod folder through the Mods menu, copy-paste the contents of your mod, and edit the content of the auto-generated manifest so that it includes your additions.

From there on, you should either continue developing your mod inside the auto-generated mod folder, or disable that mod and develop the one inside the mods folder, repeating the steps above whenever you need to push your update to the Workshop. Steps in this guide will refer to the mods folder (local mods), but you can develop your mod inside the auto-generated folder for the Workshop if you want.

Create a text file inside your mod folder and name it manifest.json (make sure the extension is .json and not .json.txt or the like. Enable showing file extensions so you can see the actual format of the file). Now, open it with the text editor of your choice and copy/paste this data in it:

     "info": {
        "name": "My First Mod",
        "namespace": "my_first_mod",
        "version": 3

Here you can change the name to any name you want (e.g.: "Candy Land"). You MUSN'T change the version number. As for the namespace, it's usually some abbreviated form of the name, and we tend to keep it lowercase to avoid typos. It can only contain alphanumeric characters, hyphens and underscores. Usually the namespace matches the folder's name.

And that's it. Your first mod is complete. Run Stonehearth, open the Mods menu, and you should see your mod listed there by name and with its namespace in small next to it. This mod doesn't do anything yet, but first we need to learn the structure of the manifest and how to work with the files.

What is the manifest?

The manifest is a list of all the assets and code in the mod.

The minimum required fields in the manifest are inside this section called "info":

  1. The namespace of the mod.
    This will be used to distinguish the identifiers of your mod's content from other mod's content. You will be using it in your files so try to keep it short and unique. It can only contain alphanumeric characters, hyphens and underscores, using spaces or other characters is not allowed.

  2. The version.
    icon The "version" key of the "info" section refers to the modding API version, not to your mod version. It is used to outdate automatically old mods when the API version is changed. To make your mod compatible with the current version of the game, always ensure that it has the same value than the one in the current stonehearth mod.

  3. The name of the mod.
    A name or title for your mod. In the past, the name had to match exactly the folder's name, but now you can use any character for the name, as long as you use the namespace for your aliases.

Optional fields

There can be other optional keys inside the "info" section of the manifest, that affect the way they are displayed in the Mods menu:

  "required" : true

This is only used for the main mods required to run the game (radiant, stonehearth). It displays them as checked and disabled in the Mods tab, so that players won't uncheck them accidentally. The other default mods also have the "is_base_mod" key, to highlight them in the Mods menu. These two keys allow to differentiate the base game content from the external mods, so you shouldn't use them.

  "client_only": true

This is a tag to prevent the mod from being compared when a player joins a multiplayer game. The game won't try to synchronize client-only mods (such as localization mods).

  "is_debug_mod": true

This will tag a mod as a mod used for debugging (for example, the "debugtools" mod that comes bundled with the game). It will be labeled as "Debug Mod" in the Mods menu.

  "default_enabled": false

Use this tag inside the "info" section if you want your mod to be disabled by default.

  "author" : "Your name"

This is an optional field. It won't have any effect in game but you can include your name or nickname there to remember who made that mod.

JSON allows for writing any key/value you want, so as long as the game doesn't treat it as a special keyword you can add other keys here.

Structure of the manifest

In the stonehearth's manifest you can see other sections below the "info" one. They are used to reference all the assets in the game. Now we will cover briefly what do each of them do, and refer to specific sections in the guide for examples on how to use them.

The aliases

An alias is a nickname to reference a game object. We can declare an alias and associate it with the file path to get to the data file that describes that object. Later on, inside our mod's files, we can reference that game object by using its alias (always prefixed by the namespace of our mod plus a colon), which is way shorter than having to write the whole path to the file. Let's see a short example from the stonehearth manifest:

  "aliases": {
     "medium_oak_tree" : "file(entities/trees/oak_tree/medium_oak_tree)"

iconYou may have noticed that the path looks a bit strange. There are several ways in which we can specify the paths. These are all equivalent:

 "medium_oak_tree" : "file(entities/trees/oak_tree/medium_oak_tree)"
 "medium_oak_tree" : "file(entities/trees/oak_tree/medium_oak_tree/medium_oak_tree.json)"
 "medium_oak_tree" : "/stonehearth/entities/trees/oak_tree/medium_oak_tree/medium_oak_tree.json"

The syntax for the first one is shorthand for the second one, but it's only applicable if it's a JSON file inside a folder that has the same name as that file. If the file is a Lua file (or a .png, .qb, etc.), you will have to specify the whole path.

The "file()" used to wrap the paths will start searching in the current folder. This is important to know because we can use this syntax to reference files from within other files, but the path to those files will not be the same depending on which folder we are in. More examples on this later.

Not all the files in our mod need to have an alias, but sometimes it can be handy to have extra aliases for certain files, not just for entities.

The aliases (the keys) should only contain letters, numbers, underscores and colons. You can use uppercase and lowercase, but stonehearth's convention is to only use lowercase and separate sections with colons (for organization) and then use underscores to separate words (you could also use hyphens, but the convention is using underscores). Using a mix of uppercase and lowercase is confusing, and you risk of making typos, so by default we only use lowercase for our JSON keys. Using spaces is also not recommended.

For a full example of a mod, go to the starter mods section.

Mixintos and Overrides

These sections don't appear in the stonehearth manifest, but are the basics for modding. They are covered in the next sections of the guide.


The keys listed inside the "functions" section are aliases for functions. They all list the path of the controller that has the definition of the function, and an endpoint, which refers to the client or the server, depending on where the function is meant to be run.


A controller is a Lua file containing a utility class that stores data and functions (and isn't a component, service, call handler, etc). It has some behaviors that make initializing / loading / destroying easier. In the stonehearth manifest you can find aliases for the controllers of the different jobs, traits, scenarios, inventory trackers, etc.


A component is a reusable blob of code that describes a related set of details about an entity. Components include things like ai/actions, an entity's render rig, it's carried items, its stats, etc. If any game logic of any sort is associated with an entity, there is likely a component attached to that entity covering that game logic. If you create a new component, you need to add it into this section of your manifest.


This section of the manifest declares the files that define the different UI views. It contains keys for lists of all the HTML files, Javascript (.js) files, and Less files (a variant of CSS).



This key is what allows for localization (more about how to localize your mod on the specific section of the guide).


We can also specify that our mod should be loaded after other mod. This is useful when we want to add compatibility with other mods. At the same level than "info", "default_locale", etc. we can add this array listing the namespaces of the mods we depend on:

  "dependencies" : [ "mod_a", "mod_b"]

This way, if our mod overrides the same files than "mod_a" or "mod_b", our overrides will win, because they'll be loaded last.

icon This won't force dependencies nor warn the players if they're missing the dependencies. Modders should talk among themselves to decide which mod should add the dependency, and tell players to install the mods they require.

The base mods will be loaded first. In multiplayer, client_only mods will be ordered separately, since the host might not have them. The "dependencies" field won't affect hotloaded manifests.

If the game detects a circular dependency (like mod_a depends on mod_b which depends on mod_c which depends on mod_a), these mods will be temporarily disabled (it won't affect the user_settings disabled setting and won't change the checkbox in the Mods menu). They will be disabled in case the dependency could cause bugs in the game. A pop up will appear after the mods have been loaded telling which ones have the circular dependency and will therefore be disabled.

In the same way, if we have a mod that has a dependency, but the depended mod is not installed or is disabled, the game will ignore the dependency and just load that mod as if it didn't have it.

Deprecated aliases

Deprecated aliases are for assets that devs wanted to replace while players already had versions of the assets. If they were to just delete the asset, then they would ruin save/load compatibility - or maybe it would load, but things would be broken. So by moving the original URI to this deprecated list, the original asset lives on but is no longer populated in new games. For example: the 'red_fox' originally used the rabbit's rig, but a fox doesn't really move like a rabbit. They decided to switch the fox over to the wolf rig, but when they first did this all pre-existing saves displayed horribly broken looking fox creatures. So instead they deprecated the asset and made a new fox, problem solved. Another example is when they updated many of the carpenter's assets, but that meant a lot of shape and color changes that people may not want instantly replaced in their homes.

Modders should use this feature anytime they have a mod that is already out to the public but they want to make a change to an art asset that is drastic enough that a save file's old data will cause issues, or the visuals are distinctly different enough to warrant not wanting to force someone to have the new visuals instantly.

Other sections

There can be other sections in the manifest, such as "game", "client_init_script"/"server_init_script", "component_renderers", "invariant_renderers", "client_controllers", "client_components", ... but we won't be explaining those here. They will be mentioned in other sections of the guide.

There will be documentation on how to create components, call handlers, UI views, etc. in the advanced sections of the guide.