com.hypixel.hytale.server.npc.asset.builder

Package: com.hypixel.hytale.server.npc.asset.builder

Implements the JSON-driven builder/factory system for NPC configuration. NPC roles are defined in JSON files under Server/NPC/Roles/. The BuilderManager loads these files, selects the appropriate BuilderFactory by category, and instantiates typed builders that read JSON, validate it, and produce runtime objects (Roles, Actions, Sensors, BodyMotions, HeadMotions, Instructions, etc.).

The package also provides the infrastructure for expression-evaluated parameters, state machine mapping, feature provider evaluation, slot allocation, and schema generation.

Core Builder Types

Type	Kind	Description
Builder	interface	The root interface for all NPC asset builders.
BuilderBase	abstract class	Abstract base implementation with attribute reading infrastructure.
BuilderBaseWithType	abstract class	Adds a secondary Type field; implements ISpawnable.
SpawnableWithModelBuilder	abstract class	Extends BuilderBase for spawnable entities with models and dynamic dependencies.
BuilderComponent	class	Generic component wrapper; automatically registered by every factory.

Factory and Management

Type	Kind	Description
BuilderFactory	class	Creates builders by type discriminator from a named registry.
BuilderManager	class	Central manager for loading, caching, validating, and hot-reloading builders.
BuilderInfo	class	Metadata about a loaded builder (index, name, path, validation state).

Object Helpers (JSON Reading)

Type	Kind	Description
BuilderObjectHelper	abstract class	Base for helpers that read JSON and produce typed objects.
BuilderObjectReferenceHelper	class	Resolves inline, file, or internal builder references.
BuilderObjectArrayHelper	abstract class	Reads JSON arrays of builder objects.
BuilderObjectListHelper	class	Produces a List<T> from a JSON array.
BuilderObjectMapHelper	class	Produces a Map<K, V> from a JSON array with key extraction.
BuilderObjectStaticHelper	class	Enforces inline-only (no references).
BuilderObjectStaticListHelper	class	List of inline-only builders.
BuilderCodecObjectHelper	class	Reads JSON via a Codec<T>.
BuilderCombatConfig	class	Combat configuration with runtime override.
BuilderTemplateInteractionVars	class	Interaction variable maps with runtime override.

Parameters, Modifiers, and Context

Type	Kind	Description
BuilderParameters	class	Parameter definitions, expression scope, and dependency tracking.
BuilderModifier	class	"Modify" block: parameter overrides, state exports, combat config, interaction vars.
EmptyBuilderModifier	class	Singleton null-object modifier.
BuilderContext	interface	Hierarchical breadcrumb context for error reporting.
BuilderSupport	class	Runtime context during build(): entity, slots, instructions, events, state.
BuilderValidationHelper	class	Bundles validation context objects.

Schema and Descriptors

Type	Kind	Description
BuilderDescriptor	class	Builder schema for documentation/validation generation.
BuilderAttributeDescriptor	class	Single attribute schema with fluent configuration.
BuilderDescriptorState	enum	Lifecycle state: Unknown, WorkInProgress, Experimental, Stable, Deprecated.

Slot Mappers

Type	Kind	Description
SlotMapper	class	Maps names to sequential integer slots.
ReferenceSlotMapper	class	Extends SlotMapper with lazily-created reference objects.
EventSlotMapper	class	Allocates event observation slots by type and set.

State Machine Support

Type	Kind	Description
StateMappingHelper	class	Two-level state name/index mapping with validation.
StatePair	class	Immutable (fullStateName, mainIndex, subIndex) tuple.

Enums

Type	Kind	Description
FeatureOverride	enum	Three-state override for NPC builder features (On, Off, Default).

Feature Evaluation

Type	Kind	Description
Feature	enum	Target types: Player, NPC, Drop, Position, Path.
FeatureEvaluatorHelper	class	Manages feature provider evaluation and requirements.

Instruction Context

Type	Kind	Description
InstructionType	enum	Instruction contexts: Default, Interaction, Death, Component, StateTransitions.
ComponentContext	enum	Sensor contexts: SensorSelf, SensorTarget, SensorEntity.
InstructionContextHelper	class	Validates instruction/component context compatibility.

Reference Resolution

Type	Kind	Description
InternalReferenceResolver	class	Resolves local builder references within a file; detects cycles.

Sub-packages

This package has several sub-packages (documented separately):

• expression — Expression types for dynamic JSON values (static and dynamic boolean, number, string, and array expressions).
• holder — Typed value holder classes for validated field storage.
• providerevaluators — Feature and parameter provider evaluators.
• validators — Attribute and asset validators.
• util — Utility classes.