---
title: NPC System
type: docs
weight: 10
---

The NPC (Non-Player Character) system provides a complete framework for creating intelligent game characters with autonomous behavior, decision-making, and navigation capabilities.

**Package:** `com.hypixel.hytale.server.npc`

{{< cards >}}
  {{< card link="npc-basics" title="NPC Basics" subtitle="Creating and configuring NPCs" >}}
  {{< card link="npc-components" title="NPC Components" subtitle="Core components and data" >}}
  {{< card link="npc-ai" title="NPC AI" subtitle="Blackboard, decisions, and sensors" >}}
  {{< card link="npc-movement" title="NPC Movement" subtitle="Navigation and pathfinding" >}}
  {{< card link="npc-commands" title="NPC Commands" subtitle="Admin and debug commands" >}}
{{< /cards >}}

## Architecture Overview

The NPC system is built on several interconnected subsystems:

```
NPCEntity
├── Blackboard (shared state/memory)
├── Role (behavioral template)
│   ├── Instructions (high-level goals)
│   ├── Sensors (perception)
│   └── Actions (behaviors)
├── DecisionMaker (AI logic)
│   ├── Evaluators (condition checking)
│   └── Options (action selection)
└── Movement
    ├── MotionController (movement execution)
    ├── PathFollower (path tracking)
    └── NavigationGraph (A* pathfinding)
```

## Quick Example

```java
// Register NPC-related event
getEventRegistry().register(NPCSpawnEvent.class, event -> {
    NPCEntity npc = event.getNPC();

    // Access blackboard for state
    Blackboard blackboard = npc.getBlackboard();

    // Get current role
    Role role = npc.getRole();

    // Check if NPC has target
    if (blackboard.hasTarget()) {
        Entity target = blackboard.getTarget();
    }
});
```

## Key Classes

| Class | Description |
|-------|-------------|
| `NPCEntity` | Base class for all NPCs |
| `NPCPlugin` | Plugin entry point for NPC system |
| `Blackboard` | Shared state container for NPC data |
| `Role` | Defines NPC behavior template |
| `DecisionMaker` | AI decision logic |
| `MotionController` | Movement execution |
| `PathFollower` | Path tracking and following |

## Subpackages

| Package | Files | Description |
|---------|-------|-------------|
| `corecomponents/` | 327 | Core ECS components for NPCs |
| `asset/` | 152 | NPC asset configuration |
| `util/` | 50 | Utility classes |
| `blackboard/` | 30 | State management |
| `movement/` | 27 | Movement behaviors |
| `systems/` | 25 | ECS systems |
| `commands/` | 23 | Admin commands |
| `decisionmaker/` | 22 | AI decision logic |
| `sensorinfo/` | 20 | Perception system |
| `role/` | 17 | Role definitions |
| `instructions/` | 14 | High-level behaviors |
| `navigation/` | 12 | Pathfinding |