NPC Model Definitions

NPC model definitions configure the visual appearance, hitbox, animations, and camera behavior for NPCs. These server-side JSON files link to client-side .blockymodel and .blockyanim files.

Asset Organization

Model definitions are stored in Assets/Server/Models/:

• DirectoryAssets/Server/Models/

  • DirectoryBeast/

    • Fox.json
    • Bear_Grizzly.json
    • Wolf.json
  • DirectoryCritter/

    • Rabbit.json
    • Squirrel.json
  • DirectoryIntelligent/

    • Human.json
    • Kweebec.json
  • DirectoryLivestock/

    • Sheep.json
    • Cow.json
  • DirectoryUndead/

    • Skeleton.json
    • Zombie.json
  • …

Client-side models and animations are in Assets/Common/NPC/:

• DirectoryAssets/Common/NPC/

  • DirectoryBeast/Fox/

    • DirectoryModels/

      • Model.blockymodel
      • Texture.png
    • DirectoryAnimations/

      • DirectoryDefault/

        • Idle.blockyanim
        • Walk.blockyanim
        • Run.blockyanim
      • DirectoryDamage/

        • Hurt.blockyanim
        • Death.blockyanim
      • DirectorySwim/

        • …
      • DirectoryFly/

        • …
      • DirectoryFlavor/

        • …

Model Definition Schema

Required Fields

Field	Type	Description
Model	string	Path to .blockymodel file
Texture	string	Path to texture .png file
HitBox	object	Collision box dimensions
AnimationSets	object	Animation mappings by state

Core Properties

Field	Type	Default	Description
EyeHeight	float	-	Height of eyes from ground (blocks)
CrouchOffset	float	0	Vertical offset when crouching
MinScale	float	0.95	Minimum random scale multiplier
MaxScale	float	1.05	Maximum random scale multiplier
DefaultAttachments	ModelAttachment[]	null	Attachments always applied to this model
RandomAttachmentSets	map<string, map<string, ModelAttachment>>	null	Weighted random attachment pools per slot

HitBox Object

"HitBox": {
  "Min": { "X": -0.45, "Y": 0, "Z": -0.45 },
  "Max": { "X": 0.45, "Y": 1.1, "Z": 0.45 }
}

Field	Type	Description
Min	Vector3	Minimum corner (bottom-back-left)
Max	Vector3	Maximum corner (top-front-right)

Camera Object

Controls head tracking for the NPC:

"Camera": {
  "Pitch": {
    "AngleRange": { "Max": 45, "Min": -45 },
    "TargetNodes": ["Head"]
  },
  "Yaw": {
    "AngleRange": { "Max": 45, "Min": -45 },
    "TargetNodes": ["Head"]
  }
}

Field	Type	Description
AngleRange.Max	float	Maximum rotation angle (degrees)
AngleRange.Min	float	Minimum rotation angle (degrees)
TargetNodes	string[]	Bones to rotate for head tracking

IconProperties Object

For UI icon generation:

"IconProperties": {
  "Scale": 0.6,
  "Rotation": [0.0, -45.0, 0.0],
  "Translation": [19.0, -41.0]
}

Attachments

Attachments are extra model+texture pairs layered on top of the base NPC model — think armor pieces, accessories, hairstyles, or held items. The system supports both fixed attachments that always appear and randomized attachments that vary per NPC spawn.

ModelAttachment Object

Each attachment entry has these fields:

Field	Type	Default	Description
Model	string	null	Path to the attachment .blockymodel file
Texture	string	null	Path to the attachment texture .png file
GradientSet	string	null	Gradient set for color variation
GradientId	string	null	Specific gradient within the set
Weight	double	1.0	Selection weight (only used in RandomAttachmentSets)

DefaultAttachments

An array of ModelAttachment objects that are always applied to the NPC. These get combined with any randomly selected attachments at spawn time.

"DefaultAttachments": [
  {
    "Model": "NPC/Intelligent/Human/Attachments/Hair_01.blockymodel",
    "Texture": "NPC/Intelligent/Human/Attachments/Hair_01.png"
  }
]

RandomAttachmentSets

A two-level map structure: the outer key is a slot name (like "Hair" or "Armor"), and the inner map contains named attachment options with weights. At spawn, the engine picks one option per slot using weighted random selection.

"RandomAttachmentSets": {
  "Hair": {
    "Style_A": {
      "Model": "NPC/Intelligent/Human/Attachments/Hair_A.blockymodel",
      "Texture": "NPC/Intelligent/Human/Attachments/Hair_A.png",
      "Weight": 2.0
    },
    "Style_B": {
      "Model": "NPC/Intelligent/Human/Attachments/Hair_B.blockymodel",
      "Texture": "NPC/Intelligent/Human/Attachments/Hair_B.png",
      "Weight": 1.0
    }
  }
}

In this example, Style_A is twice as likely to be selected as Style_B. The final attachment list sent to the client is the DefaultAttachments array plus one pick from each RandomAttachmentSets slot.

Tip

NPC behaviors can swap attachments at runtime using the ActionModelAttachment action, which takes a slot name and an attachment ID. This rebuilds the model with the new attachment configuration.

AnimationSets

The AnimationSets object maps animation states to animation files:

Animation Entry Structure

"Idle": {
  "Animations": [
    {
      "Animation": "NPC/Beast/Fox/Animations/Default/Idle.blockyanim",
      "Speed": 0.6,
      "BlendingDuration": 0.1,
      "Looping": true,
      "SoundEventId": "SFX_Fox_Idle"
    }
  ]
}

Field	Type	Default	Description
Animation	string	-	Path to .blockyanim file
Speed	float	1.0	Animation playback speed multiplier
BlendingDuration	float	0.2	Transition blend time (seconds)
Looping	bool	true	Whether animation loops
SoundEventId	string	-	Sound to play with animation

Standard Animation States

Movement Animations

State	Description	Typically Loops
Idle	Standing still	Yes
Walk	Walking forward	Yes
WalkBackward	Walking backward	Yes
Run	Running forward	Yes
Crouch	Crouching idle	Yes
CrouchWalk	Crouching forward	Yes
CrouchWalkBackward	Crouching backward	Yes

Jumping & Falling

State	Description	Typically Loops
Jump	Start of jump	No
JumpWalk	Jump while walking	No
JumpRun	Jump while running	No
Fall	Falling animation	Yes

Swimming

State	Description
SwimIdle	Floating still
Swim	Swimming forward
SwimBackward	Swimming backward
SwimFast	Fast swimming
SwimJump	Jumping from water
SwimFloat	Surface floating
SwimSink	Sinking underwater
SwimDive	Diving downward
SwimDiveBackward	Diving backward
SwimDiveFast	Fast diving

Flying

State	Description
FlyIdle	Hovering
Fly	Flying forward
FlyBackward	Flying backward
FlyFast	Fast flying

Fluid (Wading in Shallow Water)

State	Description
FluidIdle	Standing in fluid
FluidWalk	Walking in fluid
FluidWalkBackward	Walking backward in fluid
FluidRun	Running in fluid

Damage & Death

State	Description	Typically Loops
Hurt	Taking damage	No
Death	Dying on land	No
HurtFly	Hurt while flying	No
DeathFly	Dying while flying	No
DeathFlyImpact	Ground impact after flying death	No
HurtSwim	Hurt while swimming	No
DeathSwim	Dying while swimming	No
HurtDrown	Hurt from drowning	No
DeathDrown	Dying from drowning	No

Behavior States

State	Description
Alerted	Noticed threat
Spawn	Initial spawn animation
Laydown	Transition to sleeping
Sleep	Sleeping loop
Wake	Waking up

Flavor Animations

State	Description
Roar	Aggressive roar/howl
Threaten	Threat display
Search	Looking around
Eat	Eating
Dig	Digging
TiltHead	Head tilt (curiosity)
Howl	Howling

Complete Example

Fox.json

{
  "Model": "NPC/Beast/Fox/Models/Model.blockymodel",
  "Texture": "NPC/Beast/Fox/Models/Texture.png",
  "EyeHeight": 0.9,
  "CrouchOffset": -0.4,
  "HitBox": {
    "Max": { "X": 0.45, "Y": 1.1, "Z": 0.45 },
    "Min": { "X": -0.45, "Y": 0, "Z": -0.45 }
  },
  "Camera": {
    "Pitch": {
      "AngleRange": { "Max": 45, "Min": -45 },
      "TargetNodes": ["Head"]
    },
    "Yaw": {
      "AngleRange": { "Max": 45, "Min": -45 },
      "TargetNodes": ["Head"]
    }
  },
  "AnimationSets": {
    "Idle": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Default/Idle.blockyanim",
        "Speed": 0.6
      }]
    },
    "Walk": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Default/Walk.blockyanim",
        "Speed": 1.4
      }]
    },
    "Run": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Default/Run.blockyanim",
        "SoundEventId": "SFX_Fox_Run",
        "Speed": 1.1
      }]
    },
    "Jump": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Default/Jump.blockyanim",
        "BlendingDuration": 0.1,
        "Looping": false,
        "Speed": 0.8
      }]
    },
    "Hurt": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Damage/Hurt.blockyanim",
        "BlendingDuration": 0.1,
        "Looping": false,
        "SoundEventId": "SFX_Fox_Hurt"
      }]
    },
    "Death": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Damage/Death.blockyanim",
        "Looping": false,
        "SoundEventId": "SFX_Fox_Death"
      }]
    },
    "Sleep": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Default/Sleep.blockyanim",
        "SoundEventId": "SFX_Fox_Sleep"
      }]
    },
    "Alerted": {
      "Animations": [{
        "Animation": "NPC/Beast/Fox/Animations/Default/Alerted.blockyanim",
        "Looping": false,
        "SoundEventId": "SFX_Fox_Alerted"
      }]
    }
  },
  "IconProperties": {
    "Scale": 0.6,
    "Rotation": [0.0, -45.0, 0.0],
    "Translation": [19.0, -41.0]
  }
}

Large NPC Example

Larger NPCs like bears have different hitbox dimensions and scale ranges:

Bear_Grizzly.json

{
  "Model": "NPC/Beast/Bear_Grizzly/Models/Model.blockymodel",
  "Texture": "NPC/Beast/Bear_Grizzly/Models/Texture.png",
  "EyeHeight": 1.5,
  "CrouchOffset": -0.3,
  "HitBox": {
    "Max": { "X": 0.8, "Y": 1.8, "Z": 0.8 },
    "Min": { "X": -0.8, "Y": 0, "Z": -0.8 }
  },
  "MinScale": 0.9,
  "MaxScale": 1.25,
  "DefaultAttachments": [],
  "AnimationSets": {
    "Roar": {
      "Animations": [{
        "Animation": "NPC/Beast/Bear_Grizzly/Animations/Flavor/Roar.blockyanim",
        "Looping": false,
        "SoundEventId": "SFX_Bear_Grizzly_Alerted"
      }]
    },
    "Eat": {
      "Animations": [{
        "Animation": "NPC/Livestock/Sheep/Animations/Flavor/Eat.blockyanim"
      }]
    }
  }
}

Tip

NPCs can reference animations from other NPC types. In the bear example, the Eat animation uses the sheep’s eating animation.

NPC Categories

Category	Location	Examples
Beast	Models/Beast/	Fox, Wolf, Bear, Scarak
Critter	Models/Critter/	Rabbit, Squirrel, Mouse
Intelligent	Models/Intelligent/	Human, Kweebec, Feran
Livestock	Models/Livestock/	Sheep, Cow, Chicken
Wildlife	Models/Wildlife/	Deer, Boar
Undead	Models/Undead/	Skeleton, Zombie, Wraith
Flying_Beast	Models/Flying_Beast/	Pterodactyl variants
Flying_Critter	Models/Flying_Critter/	Birds, Insects
Swimming_Beast	Models/Swimming_Beast/	Shark, Whale
Swimming_Wildlife	Models/Swimming_Wildlife/	Fish, Jellyfish
Elemental	Models/Elemental/	Fire, Water, Earth elementals
Boss	Models/Boss/	Boss creatures
Pets	Models/Pets/	Pet variants
Projectiles	Models/Projectiles/	Arrow, Spell projectiles
Vehicles	Models/Vehicles/	Mounts, Vehicles

Animation Folder Structure

Standard animation organization:

• DirectoryNPC/[Category]/[NPC]/Animations/

  • DirectoryDefault/

    • Idle.blockyanim
    • Walk.blockyanim
    • Walk_Backward.blockyanim
    • Run.blockyanim
    • Jump.blockyanim
    • Fall.blockyanim
    • Crouch.blockyanim
    • Crouch_Walk.blockyanim
    • Alerted.blockyanim
    • Spawn.blockyanim
    • Sleep.blockyanim
    • Laydown.blockyanim
    • Wake.blockyanim
  • DirectoryDamage/

    • Hurt.blockyanim
    • Death.blockyanim
    • Hurt_Fly.blockyanim
    • Death_Fly.blockyanim
    • …
  • DirectorySwim/

    • Swim_Idle.blockyanim
    • Swim.blockyanim
    • …
  • DirectoryFly/

    • Fly_Idle.blockyanim
    • Fly.blockyanim
    • …
  • DirectoryFlavor/

    • Roar.blockyanim
    • Eat.blockyanim
    • …

Creating Custom NPCs

1. Create the model in Blockbench with proper bone hierarchy
2. Create animations for each required state
3. Export .blockymodel and .blockyanim files
4. Create model definition JSON referencing your files
5. Create NPC role to define behavior

MyPlugin_CustomCreature.json

{
  "Model": "MyPlugin/NPC/CustomCreature/Model.blockymodel",
  "Texture": "MyPlugin/NPC/CustomCreature/Texture.png",
  "EyeHeight": 1.0,
  "HitBox": {
    "Max": { "X": 0.5, "Y": 1.5, "Z": 0.5 },
    "Min": { "X": -0.5, "Y": 0, "Z": -0.5 }
  },
  "AnimationSets": {
    "Idle": {
      "Animations": [{
        "Animation": "MyPlugin/NPC/CustomCreature/Animations/Idle.blockyanim"
      }]
    },
    "Walk": {
      "Animations": [{
        "Animation": "MyPlugin/NPC/CustomCreature/Animations/Walk.blockyanim"
      }]
    },
    "Hurt": {
      "Animations": [{
        "Animation": "MyPlugin/NPC/CustomCreature/Animations/Hurt.blockyanim",
        "Looping": false
      }]
    },
    "Death": {
      "Animations": [{
        "Animation": "MyPlugin/NPC/CustomCreature/Animations/Death.blockyanim",
        "Looping": false
      }]
    }
  }
}

Related

• NPC Asset Overview - NPC system overview
• NPC Groups - NPC grouping and attitudes
• Audio Overview - Sound event system
• Blockbench Setup - Model creation tool