[Tutorial] Adding Custom Professions


This time let’s get our hands really dirty. Adding a profession is a bit more complicated as the other mods so far… but also much more fun :wink:.

Especially with this one please be aware that there will be changes implemented which will cause that the process of adding a new profession will not work exactly like it is explained here (in the future). However, with Patch r27 it is working and the basic will be the same.

If you are interested in knowing what changes might come along… read what Stephanie is saying here and there.

There are seven mandatory steps this time (but some are really small):

  1. Define the profession: “…\Stonehearth\mods\stonehearth\professions”
  2. Display the profession: “…\Stonehearth\mods\stonehearth\ui\game\start_menu”
  3. Placing the workbench: “…\Stonehearth\mods\stonehearth\data\effects\place_workshop”
  4. Add related Lua-code: “…\Stonehearth\mods\stonehearth\professions”
  5. Define log-entries: “…\Stonehearth\mods\stonehearth\data\personality”
  6. Write log-entries: “…\Stonehearth\mods\stonehearth\services\personality”
  7. Update manifest: “…\Stonehearth\mods\stonehearth”

As this are quite some steps, the following descriptions are just on a high level. The video below is explaining them in more detail.

:one: ** Define the profession: “…\Stonehearth\mods\stonehearth\professions”**

Add a folder (e.g. copy & paste the carpenter-folder) for your custom profession and rename it to what you want the profession to be called. You should rename all files and folders inside and change all references inside the files from “carpenter” to < your profession name > (in case you are using the carpenter as a template).

:two: ** Display the profession: “…\Stonehearth\mods\stonehearth\ui\game\start_menu”**

Add an image into the image-folder which will represent your profession in the ingame menu. You need to change also the .html- and .js-files and replicate the entries for the carpenter, just rename the new one to your profession.

:three: ** Placing the workbench: “…\Stonehearth\mods\stonehearth\data\effects\place_workshop”**

Simply copy & paste one of the other files and rename it to your professions name.

:four: ** Add related Lua-code: “…\Stonehearth\mods\stonehearth\professions”**

Copy & paste one of the existing folders and adjust the references in the .lua-file to fit your profession.

:five: ** Define log-entries: “…\Stonehearth\mods\stonehearth\data\personality”**

Here you can define which log-entries will be linked to the promotion of a worker to your profession by copy & paste the carpenter’s file. Change the references inside the file to fit to your profession’s name.

:six: ** Write log-entries: “…\Stonehearth\mods\stonehearth\services\personality”**

Simply add a line to the .lua-file similar as it exists already for the carpenter.

:seven: ** Update manifest: “…\Stonehearth\mods\stonehearth”**

Look for the entries which are existing for the carpenter and replicate them so you have the same entries for your profession. You do not have to create sound-entries, so just skip them.

In the best case this has worked out and you can start adjusting the design, recipes, etc. Enjoy!

Here some visual aid which might make it less confusing (28 Min.):

Voxel Pirate's Tutorials n' Stuff (Overview)
Adding a custom jobs [Alpha 16]

as usual, you brighten up my morning, even if i’ve woken up to a frozen wasteland (Houston has frozen solid over night)…

this is brilliant stuff @voxel_pirate! im sensing a new title may be in order… :smile:


Yey, Voxel Pirate the “Helping Arm”. What do I need to do to get promoted to “Helping Torso”? :wink:


i was going to suggest “Super Genius”, but you might hear from Wiley Coyote’s attorneys…


This is lovely. I suppose step 3 (Placing the workbench effect) could be omitted if we have a default, fallback “place workshop” sound. The only thing special that’s going on there is defining what sound to play when the workshop is placed. Theoretically, you could just reuse the carpenter or weaver one if you’re not actually adding a new sound file.


Somebody get this man a medal


@sdee I am a big fan of having default files in such cases which could be simply overwritten, would make life a bit easier and again save one step. At the moment it is required to create the file, otherwise placing the workbench gets broken :disappointed:.