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

title, type, weight

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

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

Brain Components

NPCBrainComponent

The main AI processing component:

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:

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:

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:

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:

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:

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

Movement Components

NPCMovementComponent

Movement configuration:

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:

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:

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:

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

NPCAggroComponent

Aggression management:

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:

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:

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:

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:

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

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

Registering Custom Components

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

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