Adding NPCs

Basics

NPCs are defined by Roles that combine:

Appearance (model)
Stats (health, speed)
AI behaviors (aggression, detection)
Attacks (interaction references)
Drops (loot tables)

Pack location: Server/NPC/Roles/
Base game reference: Assets.zip/Server/NPC/Roles/

Role Structure

NPCs use a template + variant pattern:

Template_Predator          (base hostile AI)
    ├── Wolf               (fast, pack hunter)
    ├── Spider             (ambush, poison)
    └── Molerat            (burrowing, timid)

Minimal NPC

Create Server/NPC/Roles/My_Creature.json in your pack:

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "Appearance": "Wolf",
    "MaxHealth": 50,
    "MaxSpeed": 8,
    "Attack": "Root_NPC_Attack_Melee",
    "DropList": "Drop_Wolf"
  }
}

Templates

Base game templates (in Assets.zip/Server/NPC/Roles/Templates/):

`Template_Predator`

Hostile creature that hunts players.

`Template_Passive`

Non-hostile creature that flees when attacked.

`Template_Neutral`

Only attacks if provoked.

Common Properties

Stats

{
  "Modify": {
    "MaxHealth": 100,
    "MaxSpeed": 6,
    "WanderRadius": 15
  }
}

Detection

{
  "Modify": {
    "ViewRange": 20,
    "HearingRange": 10,
    "AbsoluteDetectionRange": 3,
    "AlertedRange": 25,
    "AlertedTime": [3, 5]
  }
}

ViewRange: Can see player within this distance
HearingRange: Reacts to sounds
AbsoluteDetectionRange: Always detects (ignores line of sight)
AlertedRange: Pursuit range after detecting
AlertedTime: Min/max seconds to stay alert

Combat Behavior

{
  "Modify": {
    "AttackDistance": 2.5,
    "CombatBehaviorDistance": 6,
    "CombatDirectWeight": 10,
    "CombatStrafeWeight": 5,
    "CombatBackOffAfterAttack": true,
    "ChaseRelativeSpeed": 0.8
  }
}

AttackDistance: Range to start attack
CombatDirectWeight: Tendency to charge directly
CombatStrafeWeight: Tendency to circle
ChaseRelativeSpeed: Speed multiplier during chase

Leashing (return home)

{
  "Modify": {
    "LeashDistance": 40,
    "HardLeashDistance": 60,
    "LeashMinPlayerDistance": 10,
    "LeashTimer": [5, 8]
  }
}

Threatening (pre-attack warning)

{
  "Modify": {
    "ThreatenDelayRange": [1, 2],
    "ThreatenAnimation": "Threaten",
    "FleeIfNotThreatened": false
  }
}

Attacks

NPCs reference interactions just like items:

{
  "Modify": {
    "Attack": "Root_NPC_Attack_Melee"
  }
}

Or with custom overrides:

{
  "Modify": {
    "Attack": "Root_NPC_Attack_Melee",
    "_InteractionVars": {
      "Melee_Damage": {
        "Interactions": [{
          "Parent": "NPC_Melee_Damage",
          "DamageCalculator": {
            "BaseDamage": { "Physical": 15 }
          }
        }]
      }
    }
  }
}

Drops

Set DropList on the NPC role to reference a drop table:

{
  "Modify": {
    "DropList": "Drop_Wolf"
  }
}

Create the drop table in your pack at Server/Drops/Drop_My_Creature.json:

{
  "Container": {
    "Type": "Multiple",
    "Containers": [
      {
        "Type": "Single",
        "Item": { "ItemId": "Raw_Meat", "QuantityMax": 2 }
      },
      {
        "Type": "Single",
        "Weight": 30,
        "Item": { "ItemId": "Leather" }
      },
      {
        "Type": "Single",
        "Weight": 5,
        "Item": { "ItemId": "Rare_Fang" }
      }
    ]
  }
}

See Adding Drop Tables for the full container type reference (Choice, Multiple, Droplist, Empty).

Complete Example: Custom Predator

Server/NPC/Roles/Fire_Wolf.json:

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "Appearance": "Wolf",
    "DropList": "Drop_Fire_Wolf",

    "MaxHealth": 80,
    "MaxSpeed": 10,

    "ViewRange": 25,
    "HearingRange": 15,
    "AbsoluteDetectionRange": 4,
    "AlertedRange": 35,
    "AlertedTime": [4, 6],

    "AttackDistance": 3,
    "CombatBehaviorDistance": 8,
    "CombatDirectWeight": 15,
    "CombatStrafeWeight": 5,
    "CombatBackOffAfterAttack": false,
    "ChaseRelativeSpeed": 1.0,

    "LeashDistance": 50,
    "HardLeashDistance": 80,

    "Attack": "Root_NPC_Attack_Melee",
    "_InteractionVars": {
      "Melee_Damage": {
        "Interactions": [{
          "Parent": "NPC_Melee_Damage",
          "DamageCalculator": {
            "BaseDamage": { "Physical": 12, "Fire": 8 }
          },
          "DamageEffects": {
            "WorldParticles": [{ "SystemId": "Impact_Fire" }]
          }
        }]
      }
    }
  }
}

Complete Example: Ranged NPC

Server/NPC/Roles/Skeleton_Archer.json:

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Modify": {
    "Appearance": "Skeleton",
    "DropList": "Drop_Skeleton",

    "MaxHealth": 40,
    "MaxSpeed": 5,

    "ViewRange": 30,
    "AlertedRange": 40,

    "AttackDistance": 15,
    "CombatBehaviorDistance": 20,
    "CombatDirectWeight": 2,
    "CombatStrafeWeight": 10,
    "CombatBackOffAfterAttack": true,

    "Attack": "Root_NPC_Attack_Ranged",
    "_InteractionVars": {
      "Ranged_Projectile": {
        "Interactions": [{
          "Type": "LaunchProjectile",
          "ProjectileId": "Arrow_Basic"
        }]
      }
    }
  }
}

Complete Example: Passive Creature

Server/NPC/Roles/Forest_Deer.json:

{
  "Type": "Variant",
  "Reference": "Template_Passive",
  "Modify": {
    "Appearance": "Deer",
    "DropList": "Drop_Deer",

    "MaxHealth": 30,
    "MaxSpeed": 12,
    "WanderRadius": 20,

    "ViewRange": 15,
    "HearingRange": 20,
    "AlertedTime": [2, 4],

    "FleeRange": 25,
    "FleeSpeed": 1.2
  }
}

Parameters System

For configurable NPCs, use Parameters:

{
  "Type": "Variant",
  "Reference": "Template_Predator",
  "Parameters": {
    "Appearance": {
      "Value": "Spider",
      "Description": "Model to use"
    },
    "BaseDamage": {
      "Value": 10,
      "Description": "Base attack damage"
    }
  },
  "Modify": {
    "Appearance": { "Compute": "Appearance" },
    "_InteractionVars": {
      "Melee_Damage": {
        "Interactions": [{
          "DamageCalculator": {
            "BaseDamage": { "Physical": { "Compute": "BaseDamage" } }
          }
        }]
      }
    }
  }
}

Spawning

NPCs spawn via:

Prefabs (placed in world structures)
Spawn rules (world generation)
Spawner blocks
Commands

Spawn configurations: Server/NPC/Spawn/

Existing Appearances

From base game Assets.zip/Common/NPC/:

Creatures:

Wolf, Spider, Snake, Molerat
Deer, Sheep, Chicken, Pig
Bat, Crow, Sparrow

Intelligent:

Trork, Goblin, Skeleton
Kweebec, Feran, Outlander

File Locations

What	Your Pack	Base Game Reference
NPC Roles	`Server/NPC/Roles/`	`Assets.zip/Server/NPC/Roles/`
Role Templates	(inherit from base)	`Assets.zip/Server/NPC/Roles/Templates/`
Drops	`Server/Drops/`	`Assets.zip/Server/Drops/`
NPC Models	`Common/NPC/`	`Assets.zip/Common/NPC/`
NPC Animations	`Common/NPC/[creature]/Animations/`	`Assets.zip/Common/NPC/[creature]/Animations/`
NPC Attacks	`Server/Item/Interactions/`	`Assets.zip/Server/Item/Interactions/NPCs/`
Spawn Rules	`Server/NPC/Spawn/`	`Assets.zip/Server/NPC/Spawn/`