Creating classes

Modding
3

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 stonehearth.town:get_town(session.player_id):promote_citizen(person, 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.

Done.

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: