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-ai.en.md
+++ b/content/world/entities/npc/npc-ai.en.md
@@ -0,0 +1,373 @@
+---
+title: NPC AI
+type: docs
+weight: 3
+---
+
+The NPC AI system provides intelligent decision-making through blackboards, decision makers, sensors, and instructions.
+
+**Packages:**
+- `com.hypixel.hytale.server.npc.blackboard`
+- `com.hypixel.hytale.server.npc.decisionmaker`
+- `com.hypixel.hytale.server.npc.sensorinfo`
+- `com.hypixel.hytale.server.npc.instructions`
+
+## Blackboard System
+
+The Blackboard is a shared memory space where NPC components communicate through key-value pairs.
+
+### Blackboard Class
+
+```java
+public class Blackboard {
+    private Map<BlackboardKey<?>, Object> data;
+
+    // Store value
+    public <T> void set(BlackboardKey<T> key, T value);
+
+    // Retrieve value
+    public <T> T get(BlackboardKey<T> key);
+    public <T> T getOrDefault(BlackboardKey<T> key, T defaultValue);
+
+    // Check existence
+    public boolean has(BlackboardKey<?> key);
+
+    // Remove value
+    public void remove(BlackboardKey<?> key);
+
+    // Clear all
+    public void clear();
+}
+```
+
+### BlackboardKey
+
+Type-safe keys for blackboard access:
+
+```java
+// Predefined keys
+public class BlackboardKeys {
+    public static final BlackboardKey<Entity> TARGET =
+        new BlackboardKey<>("target", Entity.class);
+    public static final BlackboardKey<Vector3d> HOME_POSITION =
+        new BlackboardKey<>("home_position", Vector3d.class);
+    public static final BlackboardKey<Float> ALERT_LEVEL =
+        new BlackboardKey<>("alert_level", Float.class);
+    public static final BlackboardKey<Boolean> IN_COMBAT =
+        new BlackboardKey<>("in_combat", Boolean.class);
+}
+
+// Custom keys
+BlackboardKey<String> CUSTOM_KEY = new BlackboardKey<>("custom_data", String.class);
+```
+
+### Using the Blackboard
+
+```java
+NPCEntity npc = // get NPC
+Blackboard bb = npc.getBlackboard();
+
+// Set target
+bb.set(BlackboardKeys.TARGET, targetEntity);
+
+// Get home position
+Vector3d home = bb.getOrDefault(BlackboardKeys.HOME_POSITION, npc.getPosition());
+
+// Check combat status
+if (bb.getOrDefault(BlackboardKeys.IN_COMBAT, false)) {
+    // Handle combat
+}
+```
+
+## Decision Maker System
+
+The Decision Maker evaluates options and selects the best action for the NPC to take.
+
+### DecisionMaker Interface
+
+```java
+public interface DecisionMaker {
+    // Evaluate and select best option
+    Option evaluate(NPCEntity npc, Blackboard blackboard);
+
+    // Get all available options
+    List<Option> getOptions();
+
+    // Add option
+    void addOption(Option option);
+}
+```
+
+### Option Class
+
+Options represent possible actions:
+
+```java
+public class Option {
+    private String id;
+    private Evaluator evaluator;
+    private Action action;
+    private float basePriority;
+
+    // Calculate score based on context
+    public float evaluate(NPCEntity npc, Blackboard blackboard);
+
+    // Execute the action
+    public void execute(NPCEntity npc, Blackboard blackboard);
+}
+```
+
+### Evaluator Interface
+
+Evaluators calculate option scores:
+
+```java
+public interface Evaluator {
+    // Return score from 0.0 to 1.0
+    float evaluate(NPCEntity npc, Blackboard blackboard);
+}
+
+// Built-in evaluators
+public class Evaluators {
+    // Returns 1.0 if target exists
+    public static final Evaluator HAS_TARGET = (npc, bb) ->
+        bb.has(BlackboardKeys.TARGET) ? 1.0f : 0.0f;
+
+    // Returns health percentage
+    public static final Evaluator HEALTH_PERCENT = (npc, bb) ->
+        npc.getHealth() / npc.getMaxHealth();
+
+    // Returns 1.0 if at home
+    public static final Evaluator AT_HOME = (npc, bb) -> {
+        Vector3d home = bb.get(BlackboardKeys.HOME_POSITION);
+        return npc.getPosition().distance(home) < 5.0 ? 1.0f : 0.0f;
+    };
+}
+```
+
+### Creating a Decision Maker
+
+```java
+DecisionMaker dm = new StandardDecisionMaker();
+
+// Add attack option
+dm.addOption(new Option(
+    "attack",
+    Evaluators.HAS_TARGET,
+    new AttackAction(),
+    10.0f  // High priority
+));
+
+// Add flee option
+dm.addOption(new Option(
+    "flee",
+    (npc, bb) -> npc.getHealth() < 20 ? 1.0f : 0.0f,
+    new FleeAction(),
+    15.0f  // Higher priority when triggered
+));
+
+// Add wander option
+dm.addOption(new Option(
+    "wander",
+    (npc, bb) -> 0.3f,  // Low constant score
+    new WanderAction(),
+    1.0f   // Low priority fallback
+));
+
+npc.setDecisionMaker(dm);
+```
+
+## Sensor System
+
+Sensors gather information about the world and update the blackboard.
+
+### Sensor Interface
+
+```java
+public interface Sensor {
+    // Process sensor input
+    void sense(NPCEntity npc, Blackboard blackboard, float deltaTime);
+
+    // Get sensor type
+    String getSensorType();
+}
+```
+
+### SensorInfo Classes
+
+Sensor information containers:
+
+```java
+// Visual detection info
+public class VisualSensorInfo {
+    private List<Entity> visibleEntities;
+    private float detectionRange;
+    private float fieldOfView;
+
+    public List<Entity> getVisibleEntities();
+    public boolean canSee(Entity entity);
+}
+
+// Audio detection info
+public class AudioSensorInfo {
+    private List<SoundEvent> heardSounds;
+    private float hearingRange;
+
+    public List<SoundEvent> getHeardSounds();
+    public Vector3d getLoudestSoundPosition();
+}
+
+// Threat detection info
+public class ThreatSensorInfo {
+    private List<Entity> threats;
+    private Entity primaryThreat;
+    private float threatLevel;
+}
+```
+
+### Built-in Sensors
+
+```java
+// Visual sensor - detects visible entities
+public class VisualSensor implements Sensor {
+    private float range = 20.0f;
+    private float fov = 120.0f;  // degrees
+
+    @Override
+    public void sense(NPCEntity npc, Blackboard bb, float dt) {
+        List<Entity> visible = findVisibleEntities(npc);
+        bb.set(BlackboardKeys.VISIBLE_ENTITIES, visible);
+    }
+}
+
+// Proximity sensor - detects nearby entities
+public class ProximitySensor implements Sensor {
+    private float range = 5.0f;
+
+    @Override
+    public void sense(NPCEntity npc, Blackboard bb, float dt) {
+        List<Entity> nearby = findNearbyEntities(npc, range);
+        bb.set(BlackboardKeys.NEARBY_ENTITIES, nearby);
+    }
+}
+
+// Damage sensor - reacts to damage taken
+public class DamageSensor implements Sensor {
+    @Override
+    public void sense(NPCEntity npc, Blackboard bb, float dt) {
+        if (npc.wasRecentlyDamaged()) {
+            bb.set(BlackboardKeys.LAST_ATTACKER, npc.getLastAttacker());
+            bb.set(BlackboardKeys.ALERT_LEVEL, 1.0f);
+        }
+    }
+}
+```
+
+## Instruction System
+
+Instructions define high-level behavioral goals.
+
+### Instruction Interface
+
+```java
+public interface Instruction {
+    // Check if instruction should activate
+    boolean shouldActivate(NPCEntity npc, Blackboard blackboard);
+
+    // Execute instruction logic
+    void execute(NPCEntity npc, Blackboard blackboard, float deltaTime);
+
+    // Check if instruction is complete
+    boolean isComplete(NPCEntity npc, Blackboard blackboard);
+
+    // Get priority
+    float getPriority();
+}
+```
+
+### Built-in Instructions
+
+```java
+// Wander instruction
+public class WanderInstruction implements Instruction {
+    private float wanderRadius;
+    private float minWaitTime;
+    private float maxWaitTime;
+
+    @Override
+    public boolean shouldActivate(NPCEntity npc, Blackboard bb) {
+        return !bb.has(BlackboardKeys.TARGET);
+    }
+}
+
+// Guard instruction
+public class GuardInstruction implements Instruction {
+    private Vector3d guardPosition;
+    private float guardRadius;
+
+    @Override
+    public void execute(NPCEntity npc, Blackboard bb, float dt) {
+        if (npc.getPosition().distance(guardPosition) > guardRadius) {
+            bb.set(BlackboardKeys.MOVE_TARGET, guardPosition);
+        }
+    }
+}
+
+// Follow instruction
+public class FollowInstruction implements Instruction {
+    private Entity followTarget;
+    private float followDistance;
+}
+
+// Patrol instruction
+public class PatrolInstruction implements Instruction {
+    private List<Vector3d> patrolPoints;
+    private int currentPoint;
+}
+```
+
+## Combining AI Systems
+
+```java
+public void setupNPCAI(NPCEntity npc) {
+    // Configure blackboard
+    Blackboard bb = npc.getBlackboard();
+    bb.set(BlackboardKeys.HOME_POSITION, npc.getPosition());
+    bb.set(BlackboardKeys.AGGRO_RANGE, 15.0f);
+
+    // Add sensors
+    npc.addSensor(new VisualSensor(20.0f, 120.0f));
+    npc.addSensor(new ProximitySensor(5.0f));
+    npc.addSensor(new DamageSensor());
+
+    // Configure decision maker
+    DecisionMaker dm = new StandardDecisionMaker();
+    dm.addOption(new Option("attack", hasHostileTarget, attackAction, 10.0f));
+    dm.addOption(new Option("flee", lowHealth, fleeAction, 15.0f));
+    dm.addOption(new Option("patrol", isGuard, patrolAction, 5.0f));
+    dm.addOption(new Option("idle", always, idleAction, 1.0f));
+    npc.setDecisionMaker(dm);
+
+    // Add instructions
+    npc.addInstruction(new GuardInstruction(guardPost, 10.0f));
+    npc.addInstruction(new ReactToThreatInstruction());
+}
+```
+
+## Best Practices
+
+{{< callout type="info" >}}
+**AI Guidelines:**
+- Use the Blackboard for all inter-component communication
+- Keep Evaluators simple and fast - they run frequently
+- Use appropriate sensor ranges to balance awareness vs performance
+- Design Instructions to be interruptible
+- Test AI behavior with various scenarios
+{{< /callout >}}
+
+{{< callout type="warning" >}}
+**Performance:** Large numbers of NPCs with complex AI can impact performance. Consider:
+- Reducing sensor update frequency for distant NPCs
+- Using LOD (Level of Detail) for AI complexity
+- Limiting pathfinding requests
+{{< /callout >}}