Hytale NPC and AI System: Roles, Sensors, and Actions

Hytale uses a role-based AI architecture for NPC behavior. Instead of attaching individual goals to entities (like Minecraft does), Hytale defines Roles that bundle together perception (Sensors), behavior (Actions), and memory (Blackboards) into a complete NPC archetype. This reference covers the architecture as found in Hytale server version 2026.03.26.

#Architecture Overview

Every NPC in Hytale follows this layered design:

A Role is the top-level container. It defines what an NPC can see, what it can do, and how it moves. Sensors continuously evaluate world conditions and post results to a Blackboard. Actions check the Blackboard and decide whether to execute.

Note: Minecraft's mob AI uses a flat list of prioritized Goals (e.g., MeleeAttackGoal, WanderAroundGoal) that compete for execution each tick. Hytale's system is more like a state machine — Sensors trigger transitions, Actions define states, and the Blackboard carries context between them. If you've worked with behavior trees or GOAP systems, Hytale's architecture will feel familiar.

#Roles

A Role is built using BuilderRole and defines everything about an NPC's behavior profile:

// Conceptual example — Roles are typically defined via asset data
BuilderRole guardRole = new BuilderRole()
    .setInitialMaxHealth(40)
    .setRootInstruction(patrolInstruction)
    .setInteractionInstruction(dialogueInstruction)
    .setDeathInstruction(deathAnimInstruction)
    .setDropListId("guard_drops")
    .setNameTranslationKey("npc.guard.name");

Key properties you configure on a Role:

• Health — initialMaxHealth sets starting HP
• Instructions — root (main behavior loop), interaction (when a player interacts), death (death sequence)
• Steering — separate Steering configs for body and head movement
• Combat — CombatSupport for damage dealing, targeting, and aggro
• Flocking — alignment, separation, and cohesion weights for group behavior
• Drops — item drop list on death
• Environment constraints — breathing requirements (air, water), allowed environments
• Movement physics — collision probes, inertia, knockback response

Roles also support variants through BuilderRoleVariant, letting you create variations of an NPC (e.g., an armored guard vs. a scout) without duplicating the entire definition.

#Sensors

Sensors are the perception layer. They observe the world and determine whether conditions are met. Every Sensor implements the Sensor interface:

public interface Sensor {
    boolean matches(InfoProvider info);
    SensorInfo getSensorInfo();
}

The matches() method returns true when the sensor's condition is satisfied. The server calls this each evaluation cycle.

#Built-in Sensor Types

#SensorEvent Search Modes

SensorEvent is particularly flexible. It supports different search modes that control how it finds relevant events:

• PlayerFirst — prioritize events from players, fall back to NPC events
• PlayerOnly — only respond to player-originated events
• NpcFirst — prioritize events from other NPCs, fall back to player events
• NpcOnly — only respond to NPC-originated events

This is how NPCs can react differently to players versus other NPCs. A guard might use PlayerFirst to prioritize responding to player threats, while a villager NPC might use NpcFirst to prioritize communication from other villagers.

#Example: Health Threshold Sensor

// Sensor that triggers when NPC health drops below 25%
public class LowHealthSensor implements Sensor {

    @Override
    public boolean matches(InfoProvider info) {
        float currentHealth = info.getCurrentHealth();
        float maxHealth = info.getMaxHealth();
        return currentHealth < (maxHealth * 0.25f);
    }

    @Override
    public SensorInfo getSensorInfo() {
        return new SensorInfo("low_health", "Health below 25%");
    }
}

#Actions

Actions are the behavior layer. They execute when their conditions are met. Every Action implements:

public interface Action {
    boolean canExecute(InfoProvider info);
    void execute(InfoProvider info);
    void activate(InfoProvider info);
    void deactivate(InfoProvider info);
}

The lifecycle is:

1. canExecute() — checked each cycle. Returns true if the action should run.
2. activate() — called once when the action starts.
3. execute() — called each tick while the action is active.
4. deactivate() — called once when the action ends.

#Built-in Actions

#Composing Actions

Actions can be combined using ActionList for sequential execution or InstructionRandomized for random selection:

// Execute a sequence: play sound, then spawn particles, then apply effect
ActionList alertSequence = new ActionList(
    new PlaySound("alert_horn"),
    new SpawnParticles("exclamation_mark"),
    new ApplyEntityEffect("speed_boost", Duration.ofSeconds(10))
);

#Example: Flee Action

public class FleeAction implements Action {

    private static final float FLEE_DISTANCE = 20.0f;

    @Override
    public boolean canExecute(InfoProvider info) {
        // Only flee when health is low (checked via Blackboard)
        return info.getBlackboard().has("low_health_triggered");
    }

    @Override
    public void activate(InfoProvider info) {
        info.getMotion().setSpeedMultiplier(1.5f);
    }

    @Override
    public void execute(InfoProvider info) {
        // Move away from the nearest threat
        Entity threat = info.getBlackboard().get("current_threat");
        if (threat != null) {
            Vector3d fleeDirection = info.getPosition()
                .subtract(threat.getPosition())
                .normalize()
                .multiply(FLEE_DISTANCE);
            info.getMotion().moveTo(info.getPosition().add(fleeDirection));
        }
    }

    @Override
    public void deactivate(InfoProvider info) {
        info.getMotion().setSpeedMultiplier(1.0f);
        info.getBlackboard().remove("low_health_triggered");
    }
}

#Blackboard System

The Blackboard is a typed key-value store that acts as shared memory between Sensors and Actions. Sensors write observations, and Actions read them to make decisions.

// Sensor writes a detection result
blackboard.set("nearest_player", detectedPlayer);
blackboard.set("threat_distance", distance);

// Action reads the result
Entity target = blackboard.get("nearest_player");
float distance = blackboard.get("threat_distance");

The system uses EventTypeRegistration for dynamic event keys and EventView for type-safe reads:

// Register a typed blackboard key
EventTypeRegistration<Entity> threatKey =
    EventTypeRegistration.create("current_threat", Entity.class);

// Write with type safety
blackboard.set(threatKey, targetEntity);

// Read with type safety — no casting needed
Entity threat = blackboard.get(threatKey);

Tip: Always define Blackboard keys as EventTypeRegistration constants rather than raw strings. This gives you compile-time type checking and avoids runtime ClassCastException errors when Sensors and Actions disagree on value types.

#Event Messaging Between NPCs

The Blackboard also supports cross-NPC communication through the event messaging system:

• PlayerBlockEventSupport / NPCBlockEventSupport — share block interaction events
• PlayerEntityEventSupport / NPCEntityEventSupport — share entity interaction events
• AllNPCsLoadedEvent — fires when all NPCs in a region finish loading

This lets NPCs coordinate. A scout NPC that spots a player can post a threat event that nearby guard NPCs pick up through their SensorEvent listeners.

#Flocking

Roles can enable flocking behavior for group movement. Three parameters control the simulation:

• Alignment — how strongly NPCs match the heading of nearby group members
• Separation — how strongly NPCs avoid crowding each other
• Cohesion — how strongly NPCs move toward the center of the group

BuilderRole herdAnimal = new BuilderRole()
    .setFlockingAlignment(0.8f)
    .setFlockingSeparation(1.2f)
    .setFlockingCohesion(0.6f);

Note: High separation with low cohesion creates loose, spread-out groups (like grazing animals). High cohesion with low separation creates tight swarms (like insects or fish). Start with balanced values around 1.0 and adjust from there.

#Motion and Steering

Each Role configures separate Steering objects for body and head movement. The body steering controls locomotion while the head steering controls where the NPC looks:

• Collision probes — collisionProbeDistance determines how far ahead the NPC checks for obstacles
• Inertia — controls how quickly the NPC accelerates and decelerates
• Knockback — defines the NPC's response to being hit
• Entity avoidance — isAvoidingEntities controls whether the NPC pathfinds around other entities

#Example: Patrol Guard NPC

Here's how the pieces fit together for a guard NPC that patrols waypoints, detects players, and calls for backup:

Sensors:

• SensorPlayer with a 15-block detection range to spot approaching players
• SensorDamage to react when attacked
• SensorEvent in NpcOnly mode to receive alerts from other guards

Actions:

• PatrolAction — walks a waypoint loop (root instruction)
• InvestigateAction — moves toward detected player
• CombatAction — engages hostile targets with CombatSupport
• AlertAction — posts a threat to the Blackboard so nearby guards react via SensorEvent
• PlaySound("guard_alert") + DisplayName("!") — visual and audio feedback

Blackboard keys:

• detected_player (Entity) — written by SensorPlayer, read by InvestigateAction
• under_attack (Boolean) — written by SensorDamage, read by CombatAction
• alert_broadcast (Entity) — written by AlertAction, read by other guards via SensorEvent

Role configuration:

• 40 max health, moderate speed, entity avoidance enabled
• Flocking: low alignment (0.3), high separation (1.5), medium cohesion (0.8) — guards spread out but stay in the same area
• Death instruction plays a collapse animation and drops guard_drops loot table

#Custom NPC checklist

• Define a BuilderRole with health, steering, and combat settings
• Implement Sensors for each condition the NPC should detect
• Implement Actions for each behavior the NPC should perform
• Define typed Blackboard keys for Sensor-to-Action communication
• Compose instructions using ActionList or InstructionRandomized
• Configure flocking weights if the NPC should move in groups
• Set up death instructions and drop lists
• Test pathfinding, combat engagement, and edge cases like chunk boundaries