Last updated: December 10th, 2018. Latest version here.

Steam Workshop mods

Instructions for installing mods through the Steam Workshop:

  1. Run the game while Steam is running, and open the Mods menu from the main menu. mods_menu
  2. You should see a "Browse Steam Workshop" button on top of the second list. browse_workshop
  3. The Steam overlay will open and show the Workshop. Browse items in the workshop, and when you see a mod that you like, click on the "Subscribe" button. workshop_overlay suscribe
  4. The mod should start downloading. Return to the game, and you should see the mod listed in the Workshop mods list. You might see a download progress bar in the list item if it takes a while to download. downloading
  5. Make sure it is checked / enabled after it finishes downloading. downloaded
  6. Accept to reload when returning to the main menu, so that the downloaded mods are loaded. apply_changes

Instructions for uninstalling mods from the Steam Workshop:

If you subscribed to a mod from the Steam Workshop, you can uninstall it from within the game:

  1. Go to the Mods menu from the main menu, and find the mod you wish to uninstall.
  2. Hover over it, and click on "Unsubscribe from mod" (the red X button). Alternatively, you can click on "View mod in workshop" (the button with the Steam icon) and unsubscribe from the Workshop itself. downloaded unsuscribing
  3. The mod will be effectively deleted from your computer once you completely exit the game. There might be empty folders left, that's the way Steam handles unsubscribing.

For reference, the Workshop mods you subscribe to are downloaded inside this location: C:\Program Files (x86)\Steam\steamapps\workshop\content\253250. Since they're not in the usual Stonehearth mods folder, you can hover over them in the Mods menu and click on "Open mod folder" (the button with the folder icon), if you need to browse them. workshop_downloads

iconBear in mind that savefiles that were made with that mod active will throw errors if you try to load them after uninstalling it (same if you disable the mod instead of removing it).

Instructions for uploading mods to the Steam Workshop:

Workshop mods require a Steam file ID so they must be created from our UI in order to generate it. They will be automatically converted to .smod files when uploading them to the Workshop, but you'll still be able to edit your local version without needing to uncompress it.

  1. Go to the Mods menu from the main menu, and click on the "Create New Mod" button above the third column. create_mod_button

  2. Fill the required fields: create_ws_mod_form A title/name for your mod and a namespace. The namespace can only contain alphanumeric characters, hyphens and underscores. Spaces and other characters are not allowed. Try to keep it short and unique.

  3. If your mod is going to be exclusively a translation mod, check the "Is this a translation mod?" checkbox. This will add a special tag that will allow different players to keep their own translation mods active when they join a multiplayer game, so that each player can play in their own language.

  4. If your mod is going to add building templates, check the "Is this a building templates mod?" checkbox. This will add a special tag that will allow you to add building templates to your mod very easily. More instructions here.

  5. Click on "Create". This will create the mod folder and a pre-filled manifest for you. The mod will appear in the Workshop Uploads list, and the mod folder will be automatically opened so you can start adding content to it. ws_mod_just_created steam_uploads_mod

  6. The Workshop mods that you upload will live inside its own folder ("steam_uploads") instead of inside the "mods" folder. Don't copy them there because you will get a conflict inside the game (having two mods with the same namespace), and you would have to disable or remove one of them.

  7. You can browse your new mod in the workshop right now, but its visibility will be hidden so that you can add content to it before making it public. It might take a while for Steam to update the workshop, however, so you might see a blank page for a while. first_upload_to_ws

  8. Add content to your mod.

  9. Once you're satisfied with your mod, go to the Mods menu once again and hover over your mod in the Workshop Uploads list. Click on the "Upload mod to workshop" button (the green icon with the arrow). ws_mod_just_created

  10. A new form will appear. update_ws_mod_form Fill in the title (it'll be the name displayed at the Workshop, can be different than your mod's title/inner name), a description for your mod, change the visibility if you want to (by default it'll be Public, unlike when we created the mod), and optionally add some custom tags (separated by commas), upload a preview image, or add some initial changelog notes. Make sure you agreed to the terms of service too before proceeding.

  11. Click on Upload. The mod will start uploading to Steam (a progress bar will be shown in the list, it might fill several times since the mod will be compressed before uploading it), and once it's finished, the Steam overlay will automatically open, showing your mod in the Workshop. updating_ws_mod

  12. Next time you change your mod's content, you can click on the upload button from the Mods menu and change any field from that form, and the contents of the mod will get updated to the workshop.
    icon Make sure your manifest is valid before trying to upload or update your mod to the workshop. No error messages should appear in the Mods menu for your mod. Sometimes the "Invalid Steam File Id" error will appear when you open the Mods menu, but will go away quickly once the game syncs with Steam.

You can develop your mod inside the mods folder instead of the steam_uploads folder if you want, then create a new mod from the Mods menu so that a Steam file ID is generated, copy paste your mod contents to that folder, and edit the auto-generated manifest to include the missing keys. But you'll have to disable or remove the one in the mods folder after uploading it to Steam, since the game will consider it a conflict (you'll have 2 mods with the same namespace).

iconIf your mod was uploaded to the workshop as a plain folder, and players have already downloaded it, they'll need to unsubscribe, restart and subscribe again in order to get the latest smod version. Otherwise their local copies won't be updated correctly.
Players can check if they have plain files or a .smod by clicking on the folder icon of the corresponding subscribed mod in the Mods menu. For building templates, they won't be compressed, so that players can still see their images in the Mods menu.

Instructions for uploading building templates as a mod:

The mods menu includes an easy way to redistribute a pack of building templates as a mod. These templates mods won't be compressed when uploading them, so that players can see their images in the Mods menu.

First create a mod as explained above, and make sure to check the "Is this a building templates mod?" checkbox. Once it appears in the Workshop Uploads list, click on the "Edit this mod's list of templates" button, which has an icon for editing templates. template_mod_created A new window will appear and let you choose from your existing building templates: choosing_templates icon The templates will be copied to your mod, but they won't be deleted from the main game. If you later decide to add other templates, or remove some of them your mod, you can do so through this menu too (only the templates from your mod will be affected by the deletion).

Once you click 'OK', a confirmation dialog will appear: confirm_templates In the mods list, there will be an arrow button at the right for the mods that have building templates. Clicking on it will expand / collapse the list of templates that the mod has (which is convenient if you need to see which templates are in which mod): viewing_templates viewing_sh_templates

Lastly, remember to upload your mod to the Workshop like explained in the above section (step 9 onwards). The "Building Templates" tag will appear automatically for your mod in the upload form.

The game will collect the templates from all the mods and will show them in the building editor's template list.