Documentation/content/world/entities/npc/_index.en.md

title, type, weight

title	type	weight
NPC System	docs	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

// 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