NPC Systems

Package: com.hypixel.hytale.server.npc.systems

The NPC systems package contains 25 ECS system classes (totaling 69 types including inner classes) that implement the NPC behavior tick pipeline, spatial indexing, damage/death processing, interaction handling, spawn management, and debug visualization.

Tick Pipeline Execution Order

The NPC systems execute in a well-defined order each tick, established through dependency annotations:

Order	System	Purpose
1	NPCSpatialSystem	Update the NPC spatial index
2	PositionCacheSystems.UpdateSystem	Populate nearby entity caches
3	RoleSystems.PreBehaviourSupportTickSystem	Clear steering, validate targets
4	StateEvaluatorSystem	Utility-AI state selection
5	RoleSystems.BehaviourTickSystem	Core instruction tree evaluation
6	AvoidanceSystem	Entity avoidance/separation steering
7	SteeringSystem	Apply steering to motion controller
8	RoleSystems.PostBehaviourSupportTickSystem	Cleanup, state updates
9	ComputeVelocitySystem	Compute velocity from position delta
10	MovementStatesSystem	Update movement state flags
11	StepCleanupSystem	Remove step debug component (runs last)

Lifecycle Systems

System	Purpose
NPCSystems	11 inner systems for add/remove, model change, death, teleport, kill feed
RoleBuilderSystem	Constructs Role objects from JSON builder configs
BalancingInitialisationSystem	Sets up entity stats (health) from role
RoleChangeSystem	Processes queued runtime role changes
FailedSpawnSystem	Removes entities with failed role construction
NewSpawnStartTickingSystem	Enables ticking for newly spawned entities

Damage and Death

System	Purpose
NPCDamageSystems	5 inner systems: damage received/dealt, event view, filtering, item drops
NPCDeathSystems	2 inner systems: death event view, NPC kills tracking

World State and Messaging

System	Purpose
BlackboardSystems	4 inner systems: init, periodic cleanup, block event forwarding
MessageSupportSystem	5 inner systems: tick message slots for beacons and events
PositionCacheSystems	3 inner systems: spatial cache update, role activation, flock join

Spawning

System	Purpose
SpawnReferenceSystems	4 inner systems: spawn marker/beacon lifecycle and validation

Interaction

System	Purpose
NPCInteractionSystems	2 inner systems: add interaction manager, tick held interactions

Physics and Movement

System	Purpose
NPCPreTickSystem	Store tick-start position, manage despawn timers
NPCSpatialSystem	Maintain NPC spatial index
NPCVelocityInstructionSystem	Process velocity Set/Add instructions
ComputeVelocitySystem	Compute velocity from position delta
MovementStatesSystem	Update movement state flags from velocity

Base and Debug

System	Purpose
SteppableTickingSystem	Abstract base respecting Frozen component
StepCleanupSystem	Remove StepComponent at end of frame
TimerSystem	Tick all Tickable timers

All Types (69)

File	Top-Level	Inner Types
AvoidanceSystem	AvoidanceSystem	—
BalancingInitialisationSystem	BalancingInitialisationSystem	—
BlackboardSystems	BlackboardSystems	InitSystem, TickingSystem, BreakBlockEventSystem, DamageBlockEventSystem
ComputeVelocitySystem	ComputeVelocitySystem	—
FailedSpawnSystem	FailedSpawnSystem	—
MessageSupportSystem	MessageSupportSystem	BeaconSystem, NPCBlockEventSystem, NPCEntityEventSystem, PlayerBlockEventSystem, PlayerEntityEventSystem
MovementStatesSystem	MovementStatesSystem	—
NewSpawnStartTickingSystem	NewSpawnStartTickingSystem	QueueResource
NPCDamageSystems	NPCDamageSystems	DamageDealtSystem, DamageReceivedEventViewSystem, DamageReceivedSystem, DropDeathItems, FilterDamageSystem
NPCDeathSystems	NPCDeathSystems	EntityViewSystem, NPCKillsEntitySystem
NPCInteractionSystems	NPCInteractionSystems	AddSimulationManagerSystem, TickHeldInteractionsSystem
NPCPreTickSystem	NPCPreTickSystem	—
NPCSpatialSystem	NPCSpatialSystem	—
NPCSystems	NPCSystems	AddedSystem, AddedFromExternalSystem, AddedFromWorldGenSystem, AddSpawnEntityEffectSystem, OnDeathSystem, OnTeleportSystem, ModelChangeSystem, KillFeedDecedentEventSystem, KillFeedKillerEventSystem, LegacyWorldGenId, PrefabPlaceEntityEventSystem
NPCVelocityInstructionSystem	NPCVelocityInstructionSystem	—
PositionCacheSystems	PositionCacheSystems	UpdateSystem, RoleActivateSystem, OnFlockJoinSystem
RoleBuilderSystem	RoleBuilderSystem	—
RoleChangeSystem	RoleChangeSystem	RoleChangeQueue, RoleChangeRequest
RoleSystems	RoleSystems	BehaviourTickSystem, PreBehaviourSupportTickSystem, PostBehaviourSupportTickSystem, RoleActivateSystem, RoleDebugSystem
SpawnReferenceSystems	SpawnReferenceSystems	BeaconAddRemoveSystem, MarkerAddRemoveSystem, TickingSpawnBeaconSystem, TickingSpawnMarkerSystem
StateEvaluatorSystem	StateEvaluatorSystem	—
SteeringSystem	SteeringSystem	—
StepCleanupSystem	StepCleanupSystem	—
SteppableTickingSystem	SteppableTickingSystem	—
TimerSystem	TimerSystem	—

• NPCDamageSystems.DropDeathItems
• NPCSystems.OnNPCAdded
• RoleSystems.RoleDebugSystem