CitizenData NPC Model Reference — HyCitizens Plugin

CitizenData is the data model that describes a single NPC. Every field — from display name to combat ranges — lives here. You construct a CitizenData instance and hand it to CitizensManager methods such as addCitizen or updateCitizen to create or update Citizens in the world.

Constructor

new CitizenData(
    String id,                       // unique identifier
    String name,                     // display name (supports \n for multi-line)
    String modelId,                  // e.g. "Human", "Player"
    UUID worldUUID,                  // world to spawn in
    Vector3d position,               // spawn position
    Vector3f rotation,               // pitch/yaw/roll in radians
    float scale,                     // default 1.0
    UUID npcUUID,                    // null for new Citizens
    List<UUID> hologramLineUuids,    // null for new Citizens
    String requiredPermission,
    String noPermissionMessage,
    List<CommandAction> commandActions,
    boolean isPlayerModel,
    boolean useLiveSkin,
    String skinUsername,
    PlayerSkin cachedSkin,
    long lastSkinUpdate,
    boolean rotateTowardsPlayer
);

Pass null for npcUUID and hologramLineUuids when creating a brand-new Citizen. The manager assigns these values automatically after spawning.

Quick Start Example

Creating a Citizen programmatically

import com.electro.hycitizens.HyCitizensPlugin;
import com.electro.hycitizens.models.CitizenData;
import org.joml.Vector3d;
import org.joml.Vector3f;
import java.util.ArrayList;
import java.util.UUID;

// Grab any world UUID from the universe
UUID worldId = Universe.get().getWorlds().values().iterator().next().getWorldConfig().getUuid();

CitizenData citizen = new CitizenData(
    UUID.randomUUID().toString(),  // unique ID
    "Village Elder",               // name
    "Human",                       // model ID
    worldId,                       // world UUID
    new Vector3d(100, 64, 200),    // position
    new Vector3f(0, 0, 0),         // rotation
    1.0f,                          // scale
    null, null,                    // npcUUID, hologramUuids (null = new)
    "", "",                        // permission, permMessage
    new ArrayList<>(),             // command actions
    false, false, "", null, 0L,    // player-model fields
    true                           // rotateTowardsPlayer
);

HyCitizensPlugin.get().getCitizensManager().addCitizen(citizen, true);

Identity

id — String

Immutable unique identifier set at construction time. Use UUID.randomUUID().toString() when creating Citizens programmatically. The ID is used as the storage key and cannot be changed after creation.

name — String

Display name shown as the NPC’s nametag. Supports \n for multi-line nametags — each non-empty line becomes a separate hologram entity. Access via getName() / setName(String).

modelId — String

The Hytale model asset ID used to spawn the NPC entity, e.g. "Human", "Player". Access via getModelId() / setModelId(String).

worldUUID — UUID

UUID of the Hytale world where the Citizen will be spawned. Access via getWorldUUID() / setWorldUUID(UUID).

group — String

Slash-delimited group path for organisational hierarchy, e.g. "Town/Guards". Empty string means ungrouped. The path is normalised (back-slashes converted, leading/trailing slashes stripped). Access via getGroup() / setGroup(String).

Position & Scale

position — Vector3d

The configured spawn position. When a Citizen is teleported or wanders, the live position is tracked separately in currentPosition. Access via getPosition() / setPosition(Vector3d).

rotation — Vector3f

Spawn rotation in radians (pitch X, yaw Y, roll Z). Access via getRotation() / setRotation(Vector3f).

scale — float

Model scale factor, clamped to the range 0.01–100.0. Default is 1.0. Access via getScale() / setScale(float).

Appearance

Player Model & Skin

Field	Type	Description
`isPlayerModel`	`boolean`	When `true` the entity uses the Player model type.
`useLiveSkin`	`boolean`	When `true` the skin is fetched from Mojang and refreshed every 30 minutes.
`skinUsername`	`String`	Mojang username for skin lookup.
`cachedSkin`	`PlayerSkin`	The last fetched skin object. `null` if not yet fetched.
`lastSkinUpdate`	`long`	Epoch milliseconds of the last skin fetch.

Access via isPlayerModel(), isUseLiveSkin(), getSkinUsername(), getCachedSkin(), etc.

Nametag Visibility

Field	Type	Default	Description
`hideNametag`	`boolean`	`false`	Hides the nametag completely.
`hideNpc`	`boolean`	`false`	Hides the NPC entity itself (only nametag remains visible if enabled).
`nametagOffset`	`float`	`0`	Vertical offset applied to the hologram position above the NPC head.

Access via isHideNametag(), isHideNpc(), getNametagOffset() / setNametagOffset(float).

Model Nametag

Instead of a text hologram, a 3D model can be displayed above the NPC.

Field	Type	Default	Description
`modelNametagEnabled`	`boolean`	`false`	Enables the model nametag.
`nametagModelId`	`String`	`""`	Asset ID of the model to display.
`nametagModelScale`	`float`	`1.0`	Scale of the nametag model.
`rotateNametagTowardsPlayer`	`boolean`	`true`	When `true`, the model nametag rotates to face nearby players.

Access via isModelNametagEnabled(), getNametagModelId(), etc.

Look-At Behaviour

Field	Type	Default	Description
`rotateTowardsPlayer`	`boolean`	`false`	When `true` (and movement type is `IDLE`), the NPC turns to face nearby players.
`lookAtDistance`	`float`	`25.0`	Maximum distance in blocks at which the NPC reacts to a player’s presence.

Access via getRotateTowardsPlayer() / setRotateTowardsPlayer(boolean) and getLookAtDistance() / setLookAtDistance(float).

Equipment

Field	Slot	Description
`npcHelmet`	Armor slot 0	Item asset ID or `null`.
`npcChest`	Armor slot 1	Item asset ID or `null`.
`npcGloves`	Armor slot 2	Item asset ID or `null`.
`npcLeggings`	Armor slot 3	Item asset ID or `null`.
`npcHand`	Hotbar slot 0	Item asset ID or `null`.
`npcOffHand`	Utility slot	Item asset ID or `null` (reserved).

Access via getNpcHelmet() / setNpcHelmet(String), and the equivalent getters/setters for each slot.

Map Marker

Field	Type	Default	Description
`mapMarkerEnabled`	`boolean`	`false`	Enables a map marker for this Citizen.
`mapMarkerType`	`String`	`"PIN"`	Icon type. Valid values: `PIN`, `DOT`, `STAR`, `DIAMOND`, `SQUARE`, `QUESTION`, `EXCLAMATION`, `MONEY_SYMBOL`, `SHOP`, `TRADER`, `CHEST`, `SWORD`, `SHIELD`, `HEART`, `HOME`, `NPC_TYPE`, `CUSTOM`.
`mapMarkerName`	`String`	`""`	Label shown on the map.
`mapMarkerCustomIcon`	`String`	`""`	Filename of a custom `.png` icon (filename only, no path).
`mapMarkerMaxDistance`	`float`	`0.0`	Max distance in blocks at which the marker is visible. `0` means always visible.

Access via isMapMarkerEnabled(), getMapMarkerType() / setMapMarkerType(String), etc.

Behavior

MovementBehavior

Controls how the NPC moves in the world. Construct with:

new MovementBehavior(
    String type,          // IDLE, WANDER, WANDER_CIRCLE, WANDER_RECT, PATROL, FOLLOW_CITIZEN
    float walkSpeed,      // default 10.0
    float runSpeed,       // default 6.0
    float wanderRadius,   // used by WANDER
    float wanderWidth,    // used by WANDER_RECT
    float wanderDepth     // used by WANDER_RECT
)

Movement Type	Description
`IDLE`	Stands in place. Rotate-towards-player is only active in this mode.
`WANDER`	Wanders within a sphere of radius `wanderRadius`.
`WANDER_CIRCLE`	Circular wander pattern.
`WANDER_RECT`	Rectangular wander area defined by `wanderWidth` and `wanderDepth`.
`PATROL`	Follows a named patrol path. Requires `pathConfig.pluginPatrolPath` to be set.
`FOLLOW_CITIZEN`	Follows another Citizen. Requires `followCitizenId` to be set.

Access via getMovementBehavior() / setMovementBehavior(MovementBehavior).

animationBehaviors — List<AnimationBehavior>

A list of AnimationBehavior objects that define timed, default, or proximity-triggered animations. Each entry specifies the animation name, slot, trigger type, interval, and optional stop behaviour. Access via getAnimationBehaviors() / setAnimationBehaviors(List).

attitude — String

The NPC’s base attitude toward players. Valid values: PASSIVE, NEUTRAL, AGGRESSIVE. Default is PASSIVE. Access via getAttitude() / setAttitude(String).

Follow Citizen

Field	Type	Default	Description
`followCitizenEnabled`	`boolean`	`false`	Legacy field. Movement type `FOLLOW_CITIZEN` is the preferred approach.
`followCitizenId`	`String`	`""`	ID of the Citizen to follow.
`followDistance`	`float`	`2.0`	Desired separation distance in blocks when following.

Access via isFollowCitizenEnabled(), getFollowCitizenId() / setFollowCitizenId(String), getFollowDistance() / setFollowDistance(float).

scheduleConfig — ScheduleConfig

Defines a time-based schedule that moves the Citizen between named locations and changes its activity (idle, wander, patrol, follow) throughout the in-game day. Access via getScheduleConfig() / setScheduleConfig(ScheduleConfig).

Interactions

commandActions — List<CommandAction>

Commands run when a player interacts with the Citizen. Each CommandAction has a command string, runAsServer flag, delay in seconds, interaction trigger (LEFT_CLICK, F_KEY, BOTH), and a chance percent. Access via getCommandActions() / setCommandActions(List).

commandSelectionMode — String

Controls which commands from commandActions run per interaction. Valid values: ALL, RANDOM, SEQUENTIAL. Default is ALL. Access via getCommandSelectionMode() / setCommandSelectionMode(String).

messagesConfig — MessagesConfig

Configuration for messages broadcast when a player interacts. Contains a list of CitizenMessage objects, a selection mode (ALL, RANDOM, SEQUENTIAL), and an enabled flag. Access via getMessagesConfig() / setMessagesConfig(MessagesConfig).

Permissions

Field	Type	Description
`requiredPermission`	`String`	Permission node required to interact. Empty string disables permission check.
`noPermissionMessage`	`String`	Message shown to players who lack the required permission.

Access via getRequiredPermission() / setRequiredPermission(String) and getNoPermissionMessage() / setNoPermissionMessage(String).

First Interaction

A one-time interaction that fires the first time each player interacts with this Citizen.

Field	Type	Default	Description
`firstInteractionEnabled`	`boolean`	`false`	Enables the first-interaction system.
`firstInteractionCommandActions`	`List<CommandAction>`	`[]`	Commands to run on the first interaction.
`firstInteractionMessagesConfig`	`MessagesConfig`	default	Messages to send on the first interaction.
`firstInteractionCommandSelectionMode`	`String`	`"ALL"`	`ALL` or `RANDOM`.
`postFirstInteractionBehavior`	`String`	`"NORMAL"`	What happens on subsequent interactions: `NORMAL`, `NONE`.
`runNormalOnFirstInteraction`	`boolean`	`false`	When `true`, normal interaction commands/messages also fire on first interaction.

Access via isFirstInteractionEnabled(), getFirstInteractionCommandActions(), etc.

Combat & Health

Damage & Health

Field	Type	Default	Description
`takesDamage`	`boolean`	`false`	When `false` the NPC is fully invulnerable.
`overrideHealth`	`boolean`	`false`	When `true`, uses `healthAmount` as the max HP.
`healthAmount`	`float`	`100`	Max HP when `overrideHealth` is `true`.
`overrideDamage`	`boolean`	`false`	When `true`, uses `damageAmount` as the Citizen’s attack damage.
`damageAmount`	`float`	`10`	Attack damage when `overrideDamage` is `true`.

Access via isTakesDamage(), isOverrideHealth(), getHealthAmount(), etc.

Respawn

Field	Type	Default	Description
`respawnOnDeath`	`boolean`	`true`	When `true`, the Citizen respawns after dying.
`respawnDelaySeconds`	`float`	`5.0`	Seconds to wait before respawning.

Access via isRespawnOnDeath() / setRespawnOnDeath(boolean) and getRespawnDelaySeconds() / setRespawnDelaySeconds(float).

Health Regeneration

Field	Type	Default	Description
`healthRegenEnabled`	`boolean`	`false`	Enables passive health regeneration.
`healthRegenAmount`	`float`	`1.0`	HP restored per regen tick.
`healthRegenIntervalSeconds`	`float`	`5.0`	Seconds between regen ticks.
`healthRegenDelayAfterDamageSeconds`	`float`	`5.0`	Seconds after taking damage before regen resumes.

Access via isHealthRegenEnabled(), getHealthRegenAmount(), etc.

combatConfig — CombatConfig

Fine-grained control over combat AI parameters. Key fields:

Field	Type	Default	Description
`attackType`	`String`	`"Root_NPC_Attack_Melee"`	Interaction ID used for the attack animation.
`attackDistance`	`float`	`2.0`	Range in blocks at which the Citizen initiates an attack.
`chaseSpeed`	`float`	`0.67`	Relative speed multiplier when chasing a target.
`backOffAfterAttack`	`boolean`	`true`	When `true`, the Citizen backs away after attacking.
`backOffDistance`	`float`	`4.0`	Distance to back off in blocks.
`blockAbility`	`String`	`"Shield_Block"`	Ability ID used for blocking.
`blockProbability`	`int`	`50`	0–100 percent chance to block incoming attacks.

Construct with new CombatConfig() (defaults apply) and customise via setters. Apply via setCitizenCombatConfig(citizenId, combatConfig).

detectionConfig — DetectionConfig

Controls how and how far the NPC detects players. Key fields:

Field	Type	Default	Description
`viewRange`	`float`	`15`	Visual detection range in blocks.
`viewSector`	`float`	`180`	Horizontal field-of-view in degrees.
`hearingRange`	`float`	`8`	Hearing detection range in blocks.
`absoluteDetectionRange`	`float`	`2`	Range within which detection is guaranteed regardless of LOS.
`alertedRange`	`float`	`45`	Range within which an alerted NPC will pursue.
`investigateRange`	`float`	`40`	Range for investigation state navigation.

Construct with new DetectionConfig() (defaults) or new DetectionConfig(boolean hostile). Apply via setCitizenDetectionConfig(citizenId, detectionConfig).

pathConfig — PathConfig

Configures waypoint-based patrol path behaviour. Key fields:

Field	Type	Default	Description
`followPath`	`boolean`	`false`	When `true`, the Citizen follows a path defined in the UI path editor.
`pathName`	`String`	`""`	Name of the UI-defined path to follow.
`patrol`	`boolean`	`false`	When `true`, the Citizen patrols between waypoints.
`loopMode`	`String`	`"LOOP"`	Patrol end behaviour: `LOOP`, `PING_PONG`.
`pluginPatrolPath`	`String`	`""`	Name of the plugin-API patrol path (used with `startCitizenPatrol`).
`pluginPatrolSpeed`	`float`	`2.0`	Walk speed used during plugin-controlled patrol.

Construct with new PathConfig(). Apply via setCitizenPathConfig(citizenId, pathConfig).

Overview

Core API

Advanced

CitizenData NPC Model Reference — HyCitizens Plugin

Constructor

Quick Start Example

Identity

Position & Scale

Appearance

Behavior

Interactions

Combat & Health

Build docs developers (and LLMs) love

Overview

Core API

Advanced

Documentation Index

​Constructor

​Quick Start Example

​Identity

​Position & Scale

​Appearance

​Behavior

​Interactions

​Combat & Health

Build docs developers (and LLMs) love

Constructor

Quick Start Example

Identity

Position & Scale

Appearance

Behavior

Interactions

Combat & Health