Creating classes

Hey everyone! I’ve done some searching on this discourse, but I’m having trouble finding documentation on creating new classes for settlers. What I’ve understood so far:

Items (tools) have an associated .json that has the promote_to_profession code in it. Looking at that, however (in \data\commands\promote_to_profession, if you’re curious) doesn’t seem to lead much of anywhere, except out to radiant_promote_to_profession. After this point I get a little lost, since I think form here I need to delve into Lua and decompiling the existing codebase, which seems a little extreme for creating a mod.

I guess my question is, has anyone created/expanded new classes in Stonehearth yet? I’m wondering if this is going to require some fancy Lua shenanigans or if this will be doable via the .json framework already provided. I feel like I might be overthinking and overcomplicating things, so I figured I’d ask here first.


first of all, welcome aboard @EDC! :smile:

as to your question, there are a few significantly themed mods, like @Avairian’s Japanese Mod and @Miturion’s Egyptian Conversion Mod… however, it might be best to call in our resident scripting wizard… paging @RepeatPan!

Correct. The system to promote citizens - at least the “officially endorsed” one, both code- and gameplay-wise - is that an item is used for the “transition”.

That’s about what you need to do. This is what is required/what happens with the vanilla professions:

  • You need to have an item that is used for the ascension. In theory, no item is required and you could promote them in any other way, such as adding a command to them or what not, but if you want to keep with the theme of the game, an item is required.
  • As you’ve correctly seen, the components.stonehearth:commands component adds a promote_to_profession command. This is the action (i.e. the button) that you can click to promote somebody. This will call an event, as you’ve also figured out, named radiant_promote_to_profession.
  • In addition, a stonehearth:promotion_talisman component is required that sets the profession value, the URI to the profession description.
  • This event is not handled in lua, but in Javascript (stonehearth/ui/game/promote/promote.js). It basically adds a view that lets you choose which citizen to promote. You do not need to modify anything here. If you’re interested in the mechanics, however, the event passes the item (usually called “talisman”) and the profession name (as defined in the stonehearth:promote_talisman component).
  • Internally: The GUI will now display all worker citizens, i.e. all non-promoted workers (using stonehearth:get_worker_tracker).
  • The promotion itself happens by JS calling stonehearth:grab_promotion_talisman, passing… if I’m not mistaken, the chosen citizen and the talisman entity.
  • stonehearth:grab_promotion_talisman does little more than calling, talisman). This just adds a stonehearth:profession component to the citizen and calls promote_to(profession) on it.
  • That command will load the profession (as defined in stonehearth:promote_talisman.profession of the talisman), load the profession script, equip the outfit, call promote of the profession script (a callback if you want to) and then fires some events.


So what you need to do, effectively:

  • Create a talisman entity that has a stonehearth:promote_talisman component which sets profession to the JSON of your new profession
  • Also in that talisman entity, add the stonehearth:commands component that has /stonehearth/data/commands/promote_to_profession in it. This is the absolute URL that can be used in other mods, too, until they add an alias for it.
  • Create your “profession description” (the file which stonehearth:promote_talisman points to).
  • Create your profession script, which is a very simple lua script (referenced to in your profession description). For example, the trapper’s is empty and looks like this. It just needs a promote function and from the look of it, a demote one too.
  • Create your outfit, also referenced to in your profession description.

That should do the trick. You do need lua, which is only available by decompiling at the moment as there isn’t a proper documentation for it. If you want to mod seriously at the moment, I’m afraid, you won’t come around a little bit of decompiling here and there - if only to understand how it works. For example, I’ve just written this by going through the code, function to function, to… well, understand it. :smiley:


… another good starting point might be that post (a bit older and probably requires adjustments):


Huzzah, thank you for the detailed description! I managed to finagle getting it to more or less work. I was able to follow your instructions and get a new class to get promoted no problem! There are a few kinks to work out (the tool doesn’t get consumed, they hold the proxy instead of the actual equipped item, etc.) BUT STILL! It works!

Thanks again : ) I can’t wait for the combat engine so I can actually spear things!

1 Like