Last updated: December 10th, 2018. Latest version here.

Critters and monsters

Monsters are created like any other living entity (critters, hearthlings...) but there are some extra files we'll want to create if we want to use them for encounters (raids, etc). We can find the existing populations under stonehearth/services/server/population/data.

How to create a mob

All the living entities in stonehearth have the stonehearth/mixins/mob.json mixin, either directly or via other mixins. This mixin adds some basic properties like mob/render flags, the AI component, a basic attribute/expendable resource (health), and some essential entity_data that they're going to need.

Their JSON file is of "type" : "entity". Monsters have the monster.json mixin, which has way less components and data than the base_human.json mixin used by hearthlings. Animals use the critter.json mixin instead. You can reuse these mixins for your custom entities. The monster mixin has some basic components like postures, a sight sensor, the job component, and some extra attributes and AI packs so that they can fight.

You can add whatever else you need your entities to have, just like when creating placeable objects and the like, such as the model_variants component, etc. Mind that copying an existing enemy might involve many files and take a while to fix the things that don't work, so take it easy.

Finally, make sure to add an alias for your entities in your manifest. For instance:

  "aliases" : {
     "monsters:vampires:vampire": "file(entities/monsters/vampires/vampire)",
     "monsters:vampires:vampire_female": "file(entities/monsters/vampires/vampire_female)"
  }

AI and animations

You can see how to set up the rig of your entities in the art guide. Depending on the AI actions that your critter / monster can do, you'll need different animations. If the game tries to run an AI action but can't find its related effect or animation files, an error will pop up, so that you know where is the problem.

For starters, your entities will need to have at least an idle_breath.json effect, and a run.json effect, so that they can look alive when standing and running. In the entity data you might see this section for some mobs, listing effects:

  "stonehearth:idle_effects": {
     "effects": [
        {
           "name": "idle_breathe",
           "weight": 5
        },
        {
           "name": "idle_look_around",
           "weight": 2
        },
        {
           "name": "idle_sway",
           "weight": 2
        },
        {
           "name": "emote_count",
           "weight": 0.25
        }
     ]
  }

These are effects that will be played based on a weight when the entity is idle.

If you reuse an existing rig, you will have all of its existing animations available right away. For custom rigs, it may take a while to figure out which animations do you need based on the AI actions that they can do. You can check the Lua files of the AI actions (under stonehearth/ai) from the AI packs that your entity uses and search for execute('stonehearth:run_effect'. Alternatively, copy the effects and animations of an existing monster/critter, and update them little by little.

Setting up the population file

We have to create a population file like we did to implement a new kingdom. However, we won't need as many fields since we won't be showing information about the population in the UI.

These are the fields that we'll usually have for monster populations:

  • "type" : "kingdom" -- this file represents a kingdom.

  • "kingdom_name" -- a descriptive name for our kingdom, for example "Animals", "The undead", etc.

  • "kingdom_id" -- an identifier for the kingdom. Try to keep it unique, and only use lowercase and underscores by convention.

  • "amenity_to_strangers" -- the amenity towards other kingdoms. Normally will be either "hostile" or "neutral". We'll only be able to attack mobs if their amenity to us is hostile. The amenity can be changed by code, for example in the goblin campaign the goblins become neutral to us under certain conditions.

    When we hover over hostile mobs they will appear with a red outline (or red color in all the model, depending on your graphic settings). Neutral mobs (e.g. the wild animals) will appear in orange/brown, and friendly mobs in white.

    The same can be applied for entities (neutral color for wild trees and plants, white color for entities that belong to us, and red color for entities that belong to hostile factions and that we can loot).

    When playing multiplayer each player will get a color assigned so the color for friendly entities will vary.

  • "amenity_to" : {} -- if we need to define a different amenity towards certain other factions, we can include this field. Example from goblin_population.json:

    "amenity_to": {
       "orcs": "neutral",
       "human_npcs": "neutral",
       "orc_npcs": "neutral",
       "rabbit_biped_npcs": "neutral"
    }
    

    Here we're determining that goblins should be neutral to orcs, and that they shouldn't attack human/orc/rabbit NPCs (for example, NPCs that visit your town during town tier celebrations, travellers, etc., since the campaigns may require them to exist).

    The northern_alliance population has this field too, in order to make wild animals hostile so that they can hunt them:

    "amenity_to": {
       "animals": "hostile"
    }
    
  • "roles" : {} -- here's where we define how do the citizens of this population look like. Usually we'll have several roles.

    For example, in animal_population.json we have an entry for each animal type:

    "rabbit" : {
       "male" : {
          "uri": [
             "stonehearth:rabbit"
          ]
       }
    }, 
    "deer" : {
       "male" : {
          "uri": [
             "stonehearth:deer"
          ]
       }
    },
    ...
    

    We only include a "male" gender (which is considered the default in the constants) since all animals of each role will look the same, and add the URI of the animal in question inside the "uri" array.

    If they're going to have a female variant we can add a "female" entry, and if they're going to have custom names we can also add a "given_names" array inside the entry too, etc., like with the population files for playable kingdoms.

  • "task_groups" -- for monsters that are humanoid-like, (goblins, orcs...) here we can use "stonehearth:data:humanoid_task_groups". The animal population doesn't have this field, since they only have a few basic AI actions in their entity files in order to make them look alive without eating many resources from your computer.

    You can create your own reusable JSON file with the task groups that you want all of the members of this population to have (remember to add an alias for it in your manifest so that you can use it in your population file):

    {
       "task_groups": [
          "stonehearth:task_groups:placement",
          "stonehearth:task_groups:restock"
       ]
    }
    

icon Don't forget to add an alias for your population in your manifest! For instance:

  "aliases" : {
     "kingdoms:vampires": "file(services/server/population/data/vampire_population.json)"
  }

About monster tuning files

We can tune the attributes and other properties of a monster depending on the game difficulty and the net worth of the player's town.

This is done via monster_tuning files. You can find them under stonehearth/data/monster_tuning. These files are then used in campaigns to scale raid encounters depending on different factors.