Documentation/content/world/entities/npc/npc-components.en.md

---
title: NPC Components
type: docs
weight: 2
---

NPC components are ECS components that store data and state for NPCs. The system includes over 300 core components for various NPC functionalities.

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

## Core Components Overview

NPC components follow the ECS pattern where components are pure data containers attached to entity stores.

```java
// Access NPC components
EntityStore store = npc.getEntityStore();
NPCBrainComponent brain = store.getComponent(NPCBrainComponent.class);
```

## Brain Components

### NPCBrainComponent

The main AI processing component:

```java
public class NPCBrainComponent {
    private DecisionMaker decisionMaker;
    private float thinkInterval;
    private float lastThinkTime;

    public void setDecisionMaker(DecisionMaker maker);
    public DecisionMaker getDecisionMaker();
    public boolean shouldThink(float currentTime);
}
```

### NPCMemoryComponent

Stores NPC memories and knowledge:

```java
public class NPCMemoryComponent {
    private Map<String, Memory> memories;
    private float memoryDuration;

    public void remember(String key, Object value, float duration);
    public <T> T recall(String key, Class<T> type);
    public boolean hasMemory(String key);
    public void forget(String key);
}
```

## State Components

### NPCStateComponent

Current behavioral state:

```java
public class NPCStateComponent {
    private NPCState currentState;
    private NPCState previousState;
    private float stateEnterTime;

    public enum NPCState {
        IDLE,
        WALKING,
        RUNNING,
        ATTACKING,
        FLEEING,
        INTERACTING,
        SLEEPING,
        DEAD
    }
}
```

### NPCAlertComponent

Alertness and awareness level:

```java
public class NPCAlertComponent {
    private AlertLevel alertLevel;
    private float alertDecayRate;
    private Entity alertSource;

    public enum AlertLevel {
        RELAXED,     // Normal state
        CURIOUS,     // Something caught attention
        ALERT,       // Actively investigating
        ALARMED,     // Threat detected
        COMBAT       // In combat
    }
}
```

## Target Components

### NPCTargetComponent

Current target tracking:

```java
public class NPCTargetComponent {
    private Ref<EntityStore> currentTarget;
    private TargetType targetType;
    private float targetAcquiredTime;
    private Vector3d lastKnownPosition;

    public enum TargetType {
        HOSTILE,
        FRIENDLY,
        NEUTRAL,
        OBJECT
    }
}
```

### NPCFocusComponent

Visual focus point:

```java
public class NPCFocusComponent {
    private Vector3d focusPoint;
    private Ref<EntityStore> focusEntity;
    private float focusStrength;
    private boolean shouldLookAt;
}
```

## Movement Components

### NPCMovementComponent

Movement configuration:

```java
public class NPCMovementComponent {
    private float walkSpeed;
    private float runSpeed;
    private float turnSpeed;
    private boolean canJump;
    private boolean canSwim;
    private boolean canClimb;
}
```

### NPCPathComponent

Path following data:

```java
public class NPCPathComponent {
    private List<Vector3d> currentPath;
    private int currentWaypointIndex;
    private float pathRecalculateInterval;
    private float lastPathTime;

    public Vector3d getCurrentWaypoint();
    public Vector3d getNextWaypoint();
    public boolean hasReachedWaypoint(Vector3d position, float threshold);
}
```

### NPCNavigationComponent

Navigation settings:

```java
public class NPCNavigationComponent {
    private float avoidanceRadius;
    private float pathfindingRange;
    private int maxPathLength;
    private NavigationFlags flags;

    public static class NavigationFlags {
        public boolean avoidWater;
        public boolean avoidFire;
        public boolean canUseDoors;
        public boolean canBreakBlocks;
    }
}
```

## Combat Components

### NPCCombatComponent

Combat capabilities:

```java
public class NPCCombatComponent {
    private float attackRange;
    private float attackCooldown;
    private float lastAttackTime;
    private DamageType preferredDamageType;
    private List<String> availableAttacks;
}
```

### NPCAggroComponent

Aggression management:

```java
public class NPCAggroComponent {
    private Map<Ref<EntityStore>, Float> aggroTable;
    private float aggroDecayRate;
    private float aggroRange;

    public void addAggro(Ref<EntityStore> entity, float amount);
    public void removeAggro(Ref<EntityStore> entity);
    public Ref<EntityStore> getHighestAggroTarget();
}
```

## Social Components

### NPCFactionComponent

Faction affiliation:

```java
public class NPCFactionComponent {
    private String factionId;
    private Map<String, FactionRelation> relations;

    public enum FactionRelation {
        ALLIED,
        FRIENDLY,
        NEUTRAL,
        UNFRIENDLY,
        HOSTILE
    }

    public FactionRelation getRelation(String otherFaction);
}
```

### NPCDialogueComponent

Dialogue capabilities:

```java
public class NPCDialogueComponent {
    private String dialogueTreeId;
    private Map<String, Boolean> dialogueFlags;
    private Ref<EntityStore> currentSpeaker;

    public boolean hasDialogue();
    public void startDialogue(Player player);
}
```

## Utility Components

### NPCScheduleComponent

Daily schedule:

```java
public class NPCScheduleComponent {
    private Map<Integer, ScheduleEntry> schedule;

    public static class ScheduleEntry {
        public int startHour;
        public int endHour;
        public String activity;
        public Vector3d location;
    }

    public ScheduleEntry getCurrentActivity(int worldHour);
}
```

### NPCInventoryComponent

NPC inventory:

```java
public class NPCInventoryComponent {
    private ItemContainer inventory;
    private ItemStack equippedWeapon;
    private ItemStack equippedArmor;

    public ItemStack getEquippedWeapon();
    public void equipItem(ItemStack item);
}
```

## Registering Custom Components

```java
public class MyPlugin extends JavaPlugin {
    @Override
    public void start() {
        // Register custom NPC component
        getEntityStoreRegistry().registerComponent(
            "custom_npc_data",
            CustomNPCComponent.class,
            CustomNPCComponent::new
        );
    }
}

public class CustomNPCComponent {
    private String customData;
    private int customValue;

    // Component data fields
}
```

## Component Access Patterns

```java
// Safe component access
public void processNPC(NPCEntity npc) {
    EntityStore store = npc.getEntityStore();

    // Check if component exists
    if (store.hasComponent(NPCCombatComponent.class)) {
        NPCCombatComponent combat = store.getComponent(NPCCombatComponent.class);
        // Process combat logic
    }

    // Get or create component
    NPCStateComponent state = store.getOrCreateComponent(
        NPCStateComponent.class,
        NPCStateComponent::new
    );
}
```

## Best Practices

{{< callout type="info" >}}
**Component Guidelines:**
- Components should be pure data - no complex logic
- Use components for state that needs to persist
- Access components through EntityStore, not directly
- Check component existence before access
- Use appropriate component for each type of data
{{< /callout >}}