[Collective Knowledge] Class Abilities (Jobs)

Since there doesn’t really seem to be a lot of documentation on what all we can do, and I assume we’re all just reading through code and figuring it out on our own. I thought it would be a good idea to have a collection of collective knowledge posts that are 1/2 tutorial, 1/2 list of available ‘options’ that are available for us to use.

The first one I decided to tackle was the abilities file associated with each job/class. I tried to make this as easy to read as possible, and obviously everything here is how I interpreted each one works by looking though code, and what I have observed in the game. I implore anyone to expand on and correct the information listed here. I combined the list by reading through the abilities file of each job.

##Abilities File
A JSON file typically named [JobName]_abilities.json, and stored in [ModName]\jobs\[JobName]\[JobName]_abilities, and called in [JobName]_description.json.

worker_abilities.json example:

   "type": "entity",
   "components" : {
      "stonehearth:equipment_piece" : {
         "injected_ai" : {
            "actions" : [
            "ai_packs" : [
   "entity_data" : {
      "stonehearth:panic_threshold" : 0.75

We’ll break these down into 3 main sections:

  • actions
  • ai_packs
  • entity_data


Seems it might be redundant to AI Packs->Construction because it is present in Carpenter, but not Mason or Worker. Appears to allow the multiple types of wood to be used for construction, just not sure why only the carpenter has it. See here for more discussion.

Same notes as fabricate_wooden_structure.

Character can bring a piece of wood to a fire pit and set it on fire.

#AI Packs

Allows use of the character’s backpack.

Can hold a position, and wait.

Can build and tear down structures.

Required for any job that crafts items.

Allows all farming actions.

Can heal a sleeping character.

Can heal a character in combat.

Can build and tear down ladders.

Can mine and dig foundation during construction.

Should be declared on non-combat classes, character will fight to the death if not declared.

Always declared, allows character to flee when the threshold is met.

Should be declared on non-combat classes, allows character to cower when unable to flee.

Allows character to patrol, patrol in a party, and walk in formation with party.

Can move entities.

Allows character to attack from a distance, ie: Archer.

Allows character to repair entities that have ai_pack:repairable_item. (Also See: Entity Data->combat:siege_repair_data)

Allows all shepherding actions.

Should be declared on non combat classes, causes character to run to a safety point and stay there when a town alert is activated, if not assigned to militia.

Allows trapping actions.

Avoids threatening entities.

##Entity Data

combat:melee_defenses - Set melee defense paramaters.
Example from Footman:

"stonehearth:combat:melee_defenses": [
    "name": "combat_1h_dodge",
    "effect": "combat_1h_dodge",
    "active_frame": 8,
    "cooldown": 12000,
    "priority": 1,
    "chance_of_success": 0.25,
    "defense_attribute": "dodge_chance"

combat:melee_attacks - sets melee attack type paramaters. (Only found it in trapper, paramaters were empty)

combat:siege_repair_data - I can’t find where this is actually put to use, I assume it points to a coming feature.
@Oldra - allows the person to replace traps and turrets that have expended their use(s).
Example from Engineer

"stonehearth:combat:siege_repair_data": {
  "can_repair": true


  • A number <1, the higher it is, the quicker the character will run from combat.
  • Defaults to 0.5 if not set.
  • Determines when the character should panic in combat.
  • Whenever that character gets hit, the observer checks to see if their hitpoints are below their panic threshold.
  • If their health/max_health is <= threshold, the stonehearth.combat service will record that the entity is panicking from the person who lowered their HP to below the threshold, and cause them to flee/cower.

Nice post, you should put it up on the wiki.
Also i think the combat:siege_repair_data allows the person to replace traps and turrets that have expended their use(s).

Makes sense. When I did a search on all the code for seige_repair_data and can_repair, nothing came up that checked to see if that was set to true, but that doesn’t mean it’s not present in compiled code.

Other build-capable hearthlings don’t care what the building is made of. Carpenter can only construct things made of wood – i.e. just scaffolding if the building is made from stone, or scaffolding + building, if the building is also made of wood.

@Moai That’s what I thought it did at first, and it makes sense that it should work that way, but:

The Carpenter calls

"actions" : [

Along with “stonehearth:ai_pack:construction” in the AI Packs

The construction AI Pack calls:

"actions" : [

While the 2 filters each call their respective _adjacent actions.

The filters don’t override the ai_pack:construction calls(what led me to the redundant comment), and the Carpenter will still (and does in the game) construct buildings out of stone. Now I only tested stone and not clay.

It’s quite possible that is the intended way the Carpenter, and probably if ai_pack:construction was removed, that’s how it would work, and was just an oversight.

1 Like

I’m doing kind of similar things as you over here:


Hmm. I wonder if maybe we should make a centralized spot for all this stuff. For now, there’s probably not enough to constitute a wiki, but it could be a good idea to keep in mind for the future, especially when we get more coding people on board.

Definitely. I’ve been focusing more on understanding the capabilities of the API for now before getting deep into the .lua files. I’m usually really good at understanding new programming languages, and it seems very similar to python, but I’m having a hard time figuring out where variables are coming from. It also took me some googling to figure out that lua ‘tables’ are just arrays, and not a reference to a db. I also wish you could run functions directly from the console like you can with javascript.

Anyways, I completely agree about about the centralized spot, and not quite enough for a wiki, that’s why I was planning on tagging all the posts with [Collective Knowledge] for now, I just wasn’t sure if it would be better off here or in the modding category.

If that works for you, go for it, but I’d advise looking through the Lua files anyway. All those JSON files are being consumed in the Lua scripts, so rather than guessing what each JSON property does, you can see exactly what they do in Lua.

You can’t run functions quite like from the browser console with Javascript, but there is an in-game console which you can enrich with your own functions (ctrl+shift+c to open). It already comes with a very generic command that can call pretty much any Lua function in the game. I also wrote a post about how to add your own functions to it.

What variables confuse you? Some quick personal notes first:

  • The ones that say stuff like self._sv.some_variable are variables that get hard-saved to the entity (that is, they will be accessible if the game is exited and re-loaded).
  • Some variables are imported, but I assume you figured those out.
  • Some variables are global, and are initialized at game start in client and server init lua scripts. Others are global with a nebulous source (such as the radiant mod).

For the most part, it seems like it’s easiest to find an existing asset that does something similar to what you need, and then copy/modify it to fit your ways. If Radiant is accessing the stonehearth variable in a random file that you haven’t seen declared before, you can probably access it in your own files, too.


Also, no, I’d say the Mods category is for completed/wip mods. Here we aren’t really talking about specific mods, but about the process of mod making.

I use commands from the debug tool quite often. (You can also save a finger and just hit ctrl+c to open the console) I was also just looking at that post, good stuff!

Is there somewhere I can look that you know of to see everything stored in _sv?

Will be my next on my reading list.

I noticed there are a lot more posts for help there than here.

@8BitCrab Do you think you could turn this into a wiki post in case anyone else feels like digging into any of this further?

1 Like