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
- In addition, a
stonehearth:promotion_talisman component is required that sets the
profession value, the URI to the profession description.
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
- Internally: The GUI will now display all worker citizens, i.e. all non-promoted workers (using
- 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.
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.