Init

2026-01-20 20:33:59 +01:00
commit b16a40e431
583 changed files with 87339 additions and 0 deletions
--- a/content/world/entities/npc/npc-components.en.md
+++ b/content/world/entities/npc/npc-components.en.md
@@ -0,0 +1,348 @@
+---
+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 >}}