Adding equipment

For how to create your own combat job, refer to this section of the guide.

About equipment pieces

We can create many types of wearables, such as armor, helmets, outfits, swords, shields, bows, etc. To control them, we have the equipment component in the entities that wear them. And each of these wearable items has the equipment_piece component. There are certain equipment pieces that are actually invisible, such as the collars we use to designate that an animal is a pet, some of the job abilities, or the weapons that wolves use.

With the equipment_piece component we not only can make an item be equipped by a hearthling (or any other living creature), but also inject buffs and AI actions that will activate once the item is equipped.

In order for entities to be able to wear items, they need to have

  "stonehearth:equipment": {}

in their components (for hearthlings it is added in the base_human.json mixin). They also need to have the upgrade_equipment AI pack to be able to find the wearables and equip them (see the entity_data of base_human.json).

General steps for adding outfits and gear

  1. Think which jobs are going to be able to equip the item, and optionally the level they must be in order to equip it.

  2. Copy an existing equipment piece from the stonehearth mod, do the usual renaming of files and create the QB model for your item.

  3. Edit the JSON files of your item. These are the most common properties inside the "stonehearth:equipment_piece" component:

    • "slot" -- this is where do we want to attach / merge our equipment. They work like the equipment slots from any other games. Its value is a string.

      These are the slots used by the equipment pieces from the stonehearth mod:

      "helmet" / "torso" / "mainhand" / "offhand" / "leftArm" / "accessory"

      Using them will guarantee that they can be replaced by newer/better items that are also for those slots (careful with the uppercase in "leftArm", it must be written exactly like that).

      Some equipment pieces don't have this property, for example if they're just used to inject buffs, commands or AI actions; in that case they get automatically named as "no_slot_N" internally.

      Equipped items will be shown in the Equipment tab of the character sheet in the UI, as long as they have a render_type.

    • "render_type" -- there are two possible values:

      • If the "render_type" is "merge_with_model", the item will be merged with the parts of the hearthling regardless of the slot we used, as long as the matrices/layers of its QB model are named the same as the hearthling's bones that they try to replace. This is normally used for armor, together with transparency options in the model variants.

      • If the "render_type" is "attach_to_bone", it will get attached to the bone declared in the "slot" property, regardless of the matrices/layers names (so usually weapons only have one layer in their QB model).

        This bone MUST be mapped to the slot in stonehearth/data/constants.json. Right now, we only use "mainHand", "offHand" and "leftArm" with this render type, but if you want to attach an entity to any other bone, you must make a mixinto for constants.json. For example:

        {
   "constants": {
      "equipment": {
         "SLOT_TO_BONE_MAP": {
            "ring" : "rightFinger12"
         }
      }
   }
}

        The default bones are defined in the skeleton files (in the stonehearth/data/rigs subfolders). For the male hearthling, this file is stonehearth/data/rigs/entities/humans/skeletons/male.json.

        • The bones named "ATTOVERCOG", "bodyPosition" and "root" have their own purpose, so avoid using them for equipment pieces.

        • The bones named "carry", "mainHand" and "offHand" are helper bones that don't match any matrix name from the hearthling model, and are used to attach items to them in certain animations.

        We can also create new slots for already mapped bones in the "SLOT_TO_BONE_MAP", so that we can equip more than one item in that part of the hearthling model. Any slots added there will also appear in the Equipment tab of the character sheet.

        These new slots are meant to be used with the "attach_to_bone" render type, since "merge_with_model" will only care about the model layers names.

      • You may also use "none" as a value for this property if the equipment piece doesn't have a model / isn't meant to be rendered, or just don't include it in the JSON.

    • "ilevel" -- this is an arbitrary number that works in conjunction with the slots. The hearthlings will automatically equip items that have higher ilevel than the ones they have already equipped for the corresponding slot.

      This property is also optional, for example the job outfits are automatically equipped so they don't need an ilevel, or any item that is meant to be equipped from a Lua script, rather than automatically by the AI.

    • "roles" -- a string of roles separated by spaces OR an array of strings (which is better for mod compatibility).

      Only hearthlings whose job's description JSON file has one or more of these roles will be able to equip this item (their job icon will appear in the unit frame when we select the item, as well as in the crafting recipe if we make one). So we have to make sure that this property is correctly setup, otherwise nobody will equip the item.

      Similarly to the "ilevel" property, the roles are optional if we intend to equip this item manually.

    • "required_job_level" -- if we set up the "roles" property, we can optionally require a level in the jobs that fulfill those roles in order to be able to equip this item. Workers can't level up in the vanilla game, so we wouldn't use this property in outfits for them, for example.

      Don't confuse this required level with the "ilevel" property nor with the level required to craft this item, they are different things.

    • "equip_effect" -- URI of the effect that we want to play when the item is being equipped. Make sure the effect is not looped, otherwise it will never finish. This field is also optional.

  4. Create any other optional files that you need (for example, for injecting custom buffs, custom commands, custom AI).

  5. Make the item obtainable in the game (e.g.: through a recipe, loot, etc).

  6. Test that the item can be obtained, restocked, equipped, that it applies whatever abilities / buffs you added to it, as well as that they get removed when the item is unequipped.

icon Note that for equipment, if you add a color map to it in order to make it glow or the like, it won't be correctly applied if it's setup as "merge_with_model". In order to fix this, apply the color map to the base_human.json mixin through a mixinto.

Injecting buffs

Injecting buffs, commands and AI is done through arrays inside the "stonehearth:equipment_piece" component:

  "stonehearth:equipment_piece": {
     "render_type": "merge_with_model",
     "slot": "torso",
     "ilevel": 6,
     "roles": [ "cleric_job" ],
     "required_job_level": 3,
     "equip_effect": "stonehearth:effects:weapon_level_up",
     "injected_buffs": [
        "stonehearth:buffs:devoted"
     ]
  }

Here we add an "injected_buffs" array that contains aliases of buffs.

The "stonehearth:buffs:devoted" is a permanent buff used in stonehearth/jobs/worker/mixins/worker_outfit_2.json and in other outfits of the game.

You can find most of the existing buffs inside stonehearth/data/buffs.

Injecting commands

Let's check stonehearth/entities/critters/collars/pet_collar.json. This is an equipment piece that we equip to a critter when we convert it to a pet.

Inside of the "stonehearth:equipment_piece" component, we have the "injected_commands" array:

  "injected_commands": [
     "stonehearth:commands:release_pet"
  ]

When this item is equipped, it will inject the release_pet command to the critter. Existing commands can be found in stonehearth/data/commands.

Injecting AI

Again, we can see an example in the "stonehearth:equipment_piece" component of pet_collar.json:

  "injected_ai": {
     "actions": [
        "stonehearth:actions:sit_on_ground",
        "stonehearth:actions:goto_sleep",
        "stonehearth:actions:sleep_when_exhausted",
        "stonehearth:actions:pet:pet_sleep_on_ground",
        "stonehearth:actions:pet:pet_sleep_near_owners_bed",
        "stonehearth:actions:pet:pet_sleep_on_ground_adjacent",
        "stonehearth:actions:run_sleep_effect",
        "stonehearth:actions:wait_for_expendable_resource_above",
        "stonehearth:actions:eat_item",
        "stonehearth:actions:pet:pet_eat",
        "stonehearth:actions:pet:pet_eat_from_ground",
        "stonehearth:actions:pet:eat_from_container",
        "stonehearth:actions:pet:eat_from_container_adjacent",
        "stonehearth:actions:pet:check_out_random_friend",
        "stonehearth:actions:pet:get_off_ladder",
        "stonehearth:actions:pet:run_in_circles",
        "stonehearth:actions:pet:follow_owner",
        "stonehearth:actions:pet:pet_run_to_safety",
        "stonehearth:actions:pet:pet_wait_at_safety_point"
     ],
     "ai_packs": [
        "stonehearth:ai_pack:conversation"
     ],
     "observers": [
        "stonehearth:observers:sleepiness"
     ],
     "components": [
        "stonehearth:consumption",
        "stonehearth:conversation",
        "stonehearth:animal_starvation",
        "stonehearth:animal_social"
     ]
  }

These AI packs, AI actions, observers and components will be injected when the critter equips the collar, and will be removed when we release the pet.

With this, we can make the same enemies have different abilities. It is also used for adding the different job abilities when we promote someone to a specific class.

If the job should add to the military score, you can add this inside the equipment component of an equipment piece that has no slot (so that it will only get removed on demotion). Example from cleric_abilities.json:

  "military_score": 10

Equipping items in Lua

We can also equip / unequip items in Lua (example from pet_component.lua):

  local pet_collar = radiant.entities.create_entity('stonehearth:pet_collar')
  local equipment = self._entity:add_component('stonehearth:equipment')
  equipment:equip_item(pet_collar)

  local equipment = self._entity:get_component('stonehearth:equipment')
  if equipment then
     local outfit = equipment:unequip_item('stonehearth:pet_collar')
  end

When creating JSON files for raid encounters and the like, it is possible to declare the equipment that we want the enemies to have using tuning files (which are also in JSON), so we don't need to create a custom script for that.

Using SHED

For creating wearables in SHED the steps are the same than for creating other types of items.

In the Entity Stats Browser, there are tabs for Weapons and Defensive Items, you can compare their stats and iLevel there more easily.