Configuring Citizen Combat and Attitude in HyCitizens

HyCitizens exposes a deep combat configuration system built on top of Hytale’s NPC AI. You can control whether a Citizen ignores players, defends itself when provoked, or charges on sight — and then fine-tune every aspect of how it fights: attack distance, strafing weights, back-off behavior, blocking probability, and detection ranges. Health overrides, regeneration, and configurable respawn delays give you full control over the NPC’s survivability.

Attitude

The attitude field determines how a Citizen responds to nearby players before combat begins.

Value	Behavior
`PASSIVE`	The Citizen never initiates or enters combat, regardless of damage taken.
`NEUTRAL`	The Citizen ignores players until attacked. After taking damage, it enters combat.
`AGGRESSIVE`	The Citizen detects players within its view/hearing range and attacks on sight.

{
  "attitude": "NEUTRAL"
}

Aggressive Citizens will attack players on sight regardless of any interaction configuration. Ensure takesDamage is also enabled if you want the Citizen to take damage in return — otherwise it will be invulnerable while still attacking.

Damage Settings

takesDamage

boolean

default:"false"

When false, the Citizen is invulnerable and cannot be killed. Set to true to allow players (and other entities) to deal damage.

overrideHealth

boolean

default:"false"

When true, the Citizen’s maximum health is overridden by healthAmount instead of the model’s default.

healthAmount

float

default:"100.0"

The Citizen’s maximum and starting health when overrideHealth is true.

overrideDamage

boolean

default:"false"

When true, the Citizen’s melee attack damage is overridden by damageAmount instead of the role’s default.

damageAmount

float

default:"10.0"

Melee attack damage dealt by the Citizen when overrideDamage is true.

Health Regeneration

healthRegenEnabled

boolean

default:"false"

Enables passive health regeneration out of combat.

healthRegenAmount

float

default:"1.0"

Health points restored per regeneration tick.

healthRegenIntervalSeconds

float

default:"5.0"

Seconds between each regeneration tick.

healthRegenDelayAfterDamageSeconds

float

default:"5.0"

Seconds the Citizen must go without taking damage before regeneration resumes.

Respawn

respawnOnDeath

boolean

default:"true"

When true, the Citizen automatically respawns at its spawn position after death.

respawnDelaySeconds

float

default:"5.0"

Seconds to wait before respawning. During this window the Citizen does not exist in the world.

Combat Configuration

The combatConfig block fine-tunes the Citizen’s in-combat movement and attack AI. All fields map directly to the underlying Hytale NPC role system.

Field	Type	Default	Description
`attackType`	string	`Root_NPC_Attack_Melee`	The attack interaction ID used when the Citizen performs a melee swing.
`attackDistance`	float	`2.0`	Distance at which the Citizen can execute an attack.
`chaseSpeed`	float	`0.67`	Relative speed (fraction of `walkSpeed`) used when chasing a target.
`combatBehaviorDistance`	float	`5.0`	Distance within which the Citizen switches from smart chasing to combat-oriented movement.
`combatStrafeWeight`	int	`10`	Weighted chance to use strafing movement in combat. Set to `0` to disable strafing.
`combatDirectWeight`	int	`10`	Weighted chance to move directly toward the target. Set to `0` to disable direct approach.
`backOffAfterAttack`	boolean	`true`	Whether the Citizen backs away after executing an attack.
`backOffDistance`	float	`4.0`	How far the Citizen retreats after an attack.
`desiredAttackDistanceMin`	float	`1.5`	Minimum preferred distance from the target while in attack range.
`desiredAttackDistanceMax`	float	`1.5`	Maximum preferred distance from the target while in attack range.
`attackPauseMin`	float	`1.5`	Minimum seconds to wait between consecutive attacks.
`attackPauseMax`	float	`2.0`	Maximum seconds to wait between consecutive attacks.
`combatRelativeTurnSpeed`	float	`1.5`	Multiplier for how fast the Citizen turns to face its target during combat.
`blockAbility`	string	`Shield_Block`	Interaction ID used when blocking. Set to empty to disable blocking.
`blockProbability`	int	`50`	Percentage chance (0–100) the Citizen blocks while backing away.
`targetRange`	float	`4.0`	Distance within which a target maintains priority over other nearby targets.
`combatAlwaysMovingWeight`	int	`0`	Weighted chance for the Citizen to keep moving at all times during combat.
`combatStrafingDurationMin`	float	`1.0`	Minimum seconds spent strafing in a single direction before changing.
`combatStrafingDurationMax`	float	`1.0`	Maximum seconds spent strafing in one direction.
`combatStrafingFrequencyMin`	float	`2.0`	Minimum seconds between strafe bursts.
`combatStrafingFrequencyMax`	float	`2.0`	Maximum seconds between strafe bursts.
`combatAttackPreDelayMin`	float	`0.2`	Minimum seconds of wind-up before the attack animation fires.
`combatAttackPreDelayMax`	float	`0.2`	Maximum seconds of wind-up before the attack animation fires.
`combatAttackPostDelayMin`	float	`0.2`	Minimum seconds of recovery after the attack animation completes.
`combatAttackPostDelayMax`	float	`0.2`	Maximum seconds of recovery after the attack animation completes.
`backOffDurationMin`	float	`2.0`	Minimum seconds spent backing away after an attack.
`backOffDurationMax`	float	`3.0`	Maximum seconds spent backing away after an attack.
`combatFleeIfTooCloseDistance`	float	`0.0`	If the target is closer than this distance, the Citizen flees rather than attacks. Set to `0` to disable.
`combatMovingRelativeSpeed`	float	`0.6`	Speed multiplier applied while the Citizen moves during combat (relative to `walkSpeed`).
`combatBackwardsRelativeSpeed`	float	`0.3`	Speed multiplier applied while the Citizen moves backwards during back-off phases.
`useCombatActionEvaluator`	boolean	`false`	When `true`, enables the Hytale combat action evaluator for more complex attack decision-making.
`targetSwitchTimerMin`	float	`5.0`	Minimum seconds the Citizen is locked onto one target before it can switch.
`targetSwitchTimerMax`	float	`5.0`	Maximum seconds before the Citizen may switch targets.

Detection Configuration

The detectionConfig block controls how the Citizen perceives threats in its environment.

Field	Type	Default	Description
`viewRange`	float	`15.0`	Maximum distance (blocks) at which the Citizen can see a target. Set to `0` to disable sight.
`viewSector`	float	`180.0`	Field-of-view angle (degrees) within which targets are visible.
`hearingRange`	float	`8.0`	Maximum distance at which the Citizen can hear a target. Set to `0` to disable hearing.
`absoluteDetectionRange`	float	`2.0`	Distance within which a target is always detected, regardless of line-of-sight or angle. Set to `0` to disable.
`alertedRange`	float	`45.0`	Detection range when the Citizen is in the alerted state. Should not exceed `leashDistance`.
`alertedTimeMin`	float	`1.0`	Minimum seconds spent in the alerted state before transitioning to combat.
`alertedTimeMax`	float	`2.0`	Maximum seconds in the alerted state.
`chanceToBeAlertedWhenReceivingCallForHelp`	int	`70`	Percentage chance (0–100) that this Citizen becomes alerted when a nearby allied NPC calls for help.
`confusedTimeMin`	float	`1.0`	Minimum seconds the Citizen acts confused after losing its target.
`confusedTimeMax`	float	`2.0`	Maximum seconds of confused behavior.
`searchTimeMin`	float	`10.0`	Minimum seconds spent actively searching for a lost target before returning to idle.
`searchTimeMax`	float	`14.0`	Maximum seconds spent searching.
`investigateRange`	float	`40.0`	Distance within which the Citizen will move to investigate a reported attack from another NPC.

{
  "attitude": "AGGRESSIVE",
  "takesDamage": true,
  "overrideHealth": true,
  "healthAmount": 200.0,
  "respawnOnDeath": true,
  "respawnDelaySeconds": 10.0,
  "combatConfig": {
    "attackDistance": 2.0,
    "chaseSpeed": 0.67,
    "combatStrafeWeight": 10,
    "backOffAfterAttack": true,
    "blockProbability": 40
  },
  "detectionConfig": {
    "viewRange": 20.0,
    "hearingRange": 10.0,
    "absoluteDetectionRange": 2.0,
    "alertedRange": 45.0
  }
}

Get Started

In-Game Management

Citizen Configuration

Configuring Citizen Combat and Attitude in HyCitizens

Attitude

Damage Settings

Health Regeneration

Respawn

Combat Configuration

Detection Configuration

Build docs developers (and LLMs) love

Get Started

In-Game Management

Citizen Configuration

Documentation Index

​Attitude

​Damage Settings

​Health Regeneration

​Respawn

​Combat Configuration

​Detection Configuration

Build docs developers (and LLMs) love

Attitude

Damage Settings

Health Regeneration

Respawn

Combat Configuration

Detection Configuration