Skip to content
Hytale Modding Manual

NPC Roles

Overview

An NPC Role file defines everything about a specific NPC: its visual appearance, health and movement stats, sensing ranges, drop tables, flock membership, tameable status, and the AI instruction tree that drives its behavior. Roles are typically Variant files that inherit from a template via the Reference + Modify pattern, overriding only the fields that differ from the base template.

NPC Role Lifecycle

flowchart TD;
    A["Template File<br>e.g. Template_Beasts_Passive"] --> B["Role File<br>e.g. Chicken.json"];
    B -->|"Reference + Modify"| C[Resolved NPC Definition];


    C --> D[Spawn into World];
    D --> E[Idle State];


    E --> F{Detect Player?};
    F -->|"Passive NPC"| G["Continue Idle<br>or Wander"];
    F -->|"Hostile NPC"| H[Enter Combat];
    F -->|"Neutral NPC"| I{Was Attacked?};


    I -->|"No"| G;
    I -->|"Yes"| H;


    H --> J["Evaluate Actions<br>via Decision Making"];
    J --> K[Attack / Chase];
    J --> L[Flee / Retreat];
    J --> M[Use Ability];


    K --> N{Target Dead?};
    N -->|"Yes"| E;
    N -->|"No"| J;


    L --> O{Safe Distance?};
    O -->|"Yes"| E;
    O -->|"No"| L;


    G --> P{Take Damage?};
    P -->|"Yes, NPC is hostile"| H;
    P -->|"Yes, NPC flees"| L;
    P -->|"No"| E;


    style A fill:rebeccapurple,color:white;
    style B fill:steelblue,color:white;
    style H fill:darkred,color:white;
    style E fill:darkgreen,color:white;

File Location

Assets/Server/NPC/Roles/**/*.json

Roles are organized into subdirectories by category:

  • _Core/ — Base templates and shared components
  • Aquatic/ — Fish, marine creatures
  • Avian/ — Birds
  • Boss/ — Boss NPCs
  • Creature/Critter/, Creature/Livestock/, Creature/Mammal/, Creature/Mythic/, Creature/Reptile/, Creature/Vermin/ — Overworld animals
  • Elemental/ — Elemental NPCs
  • Intelligent/Aggressive/, Intelligent/Neutral/, Intelligent/Passive/ — Faction NPCs and merchants
  • Undead/ — Undead NPCs
  • Void/ — Void creatures

Schema

Top-level fields

FieldTypeRequiredDefaultDescription
Type"Abstract" | "Variant" | "Generic"Yes—Abstract = base template (not spawnable). Variant = inherits from a Reference. Generic = standalone, no inheritance.
ReferencestringFor Variant—The name of the template this role inherits from (e.g. "Template_Predator").
ModifyobjectFor Variant—Fields to override from the referenced template. Any top-level role field can appear here.
StartStatestringNoTemplate defaultThe initial AI state name (e.g. "Idle").
AppearancestringNoTemplate defaultThe model/rig ID to use for this NPC. Can also be set via { "Compute": "Appearance" } to pull from Parameters.
MaxHealthnumber | ComputeNoTemplate defaultMaximum hit points. Often set via { "Compute": "MaxHealth" }.
MaxSpeednumberNoTemplate defaultMaximum movement speed in blocks per second.
ViewRangenumberNoTemplate defaultDetection range using line-of-sight, in blocks. Set to 0 to disable sight.
ViewSectornumberNoTemplate defaultThe field-of-view arc in degrees (e.g. 180 = half sphere in front).
HearingRangenumberNoTemplate defaultDetection range using sound, in blocks. Set to 0 to disable hearing.
AlertedRangenumberNoTemplate defaultExtended detection range when the NPC is already aware of a threat, in blocks.
DropListstring | ComputeNoTemplate defaultID of the loot table used when this NPC is killed.
FlockArraystring[] | ComputeNo[]NPC role IDs that belong to this flock type. Used for coordinated group behavior.
AttractiveItemSetstring[] | ComputeNo[]Item IDs that this NPC is attracted to when held by a player nearby.
IsTameablebooleanNofalseWhether this NPC can be tamed by a player.
TameRoleChangestringNo—The role ID to switch to when this NPC is successfully tamed.
ProduceItemstringNo—Item ID produced by this NPC on a timer (e.g. eggs from chickens).
ProduceTimeout[string, string]No—ISO 8601 duration range [min, max] between produce cycles (e.g. ["PT18H", "PT48H"]).
MemoriesCategorystring | ComputeNo"Other"Category used by the memories system (e.g. "Predator", "Undead", "Goblin").
NameTranslationKeystring | ComputeNo—Translation key for the NPC’s display name (e.g. "server.npcRoles.Fox.name").
ParametersobjectNo—Named parameter definitions with Value and Description. Used with { "Compute": "<key>" } references.
InstructionsarrayNo—The AI instruction tree. Each entry is a selector or step object evaluated each tick.
SensorsarrayNo—Sensor configuration for detecting entities and world state.
ActionsarrayNo—List of action definitions available to the AI.
DisableDamageGroupsstring[]No—Damage source group IDs that cannot damage this NPC (e.g. ["Self", "Player"]).
Invulnerableboolean | ComputeNofalseIf true, the NPC takes no damage.
KnockbackScalenumberNo1.0Multiplier for knockback received. 0 = no knockback.
MotionControllerListarrayNo—Physics and locomotion controllers (e.g. Walk, Fly).
IsMemoryboolean | ComputeNofalseWhether this NPC is tracked in the memories system.
MemoriesNameOverridestring | ComputeNo""Overrides the displayed memory name when set.
DefaultNPCAttitudestringNo—Default attitude toward other NPCs (e.g. "Ignore", "Neutral").
DefaultPlayerAttitudestringNo—Default attitude toward players (e.g. "Neutral", "Hostile").

Compute shorthand

Any field that reads { "Compute": "ParameterKey" } resolves its value from the Parameters block. This allows templates to declare defaults that concrete roles can override in their Modify.Parameters section.

Examples

Variant role (Fox)

Inherits from Template_Predator and overrides only the fields specific to a fox.

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "Appearance": "Fox",
    "DropList": "Drop_Fox",
    "MaxHealth": 38,
    "MaxSpeed": 8,
    "ViewRange": 12,
    "HearingRange": 8,
    "AlertedRange": 18,
    "AlertedTime": [2, 3],
    "FleeRange": 15,
    "IsMemory": true,
    "MemoriesCategory": "Predator",
    "NameTranslationKey": { "Compute": "NameTranslationKey" }
  },
  "Parameters": {
    "NameTranslationKey": {
      "Value": "server.npcRoles.Fox.name",
      "Description": "Translation key for NPC name display"
    }
  }
}

Livestock role with taming and production (Chicken)

{
  "Type": "Variant",
  "Reference": "Template_Animal_Neutral",
  "Modify": {
    "Appearance": "Chicken",
    "FlockArray": ["Chicken", "Chicken_Chick"],
    "AttractiveItemSet": ["Plant_Crop_Corn_Item"],
    "AttractiveItemSetParticles": "Want_Food_Corn",
    "DropList": "Drop_Chicken",
    "MaxHealth": 29,
    "MaxSpeed": 5,
    "ViewRange": 8,
    "ViewSector": 300,
    "HearingRange": 4,
    "AlertedRange": 12,
    "AbsoluteDetectionRange": 1.5,
    "ProduceItem": "Food_Egg",
    "ProduceTimeout": ["PT18H", "PT48H"],
    "IsTameable": true,
    "TameRoleChange": "Tamed_Chicken",
    "IsMemory": true,
    "MemoriesNameOverride": "Chicken",
    "NameTranslationKey": { "Compute": "NameTranslationKey" }
  },
  "Parameters": {
    "NameTranslationKey": {
      "Value": "server.npcRoles.Chicken.name",
      "Description": "Translation key for NPC name display"
    }
  }
}

Generic role (Klops Merchant) — no template inheritance

{
  "Type": "Generic",
  "StartState": "Idle",
  "Appearance": "Klops_Merchant",
  "DropList": "Drop_Klops_Merchant",
  "MaxHealth": 74,
  "DefaultNPCAttitude": "Ignore",
  "DefaultPlayerAttitude": "Neutral",
  "NameTranslationKey": "server.npcRoles.Klops_Merchant.name"
}