Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ElectroGamesDev/HyCitizens/llms.txt

Use this file to discover all available pages before exploring further.

HyCitizens provides a flexible movement system that controls how Citizen NPCs behave when not in combat. Movement is configured through the movementBehavior block on each Citizen, which defines both the movement type and the parameters that govern it. You can make NPCs stand still, roam freely, walk a patrol route, or shadow another Citizen — all tunable down to speed and radius.

​
Movement Types

Set movementBehavior.type to one of the following values:
The NPC does not move on its own. It remains at its spawn position. When combined with rotateTowardsPlayer, the NPC will still track the nearest player with its head and body.
{
  "movementBehavior": {
    "type": "IDLE"
  }
}
The NPC wanders freely within a circular area defined by wanderRadius (default 10.0). The center of the wander area is the Citizen’s spawn position.
{
  "movementBehavior": {
    "type": "WANDER",
    "walkSpeed": 10.0,
    "wanderRadius": 12.0
  }
}
Similar to WANDER, the NPC roams within a circular boundary. The boundary radius is also controlled by wanderRadius.
{
  "movementBehavior": {
    "type": "WANDER_CIRCLE",
    "wanderRadius": 8.0
  }
}
The NPC wanders within a rectangular area. The rectangle’s dimensions are set with wanderWidth (X axis) and wanderDepth (Z axis), both defaulting to 10.0.
{
  "movementBehavior": {
    "type": "WANDER_RECT",
    "wanderWidth": 20.0,
    "wanderDepth": 10.0
  }
}
The NPC follows a named patrol path created with the Patrol Stick tool. Set pathConfig.pluginPatrolPath to the name of the patrol path. See the Patrols page for full setup instructions.
{
  "movementBehavior": {
    "type": "PATROL"
  },
  "pathConfig": {
    "pluginPatrolPath": "market_route",
    "pluginPatrolSpeed": 2.0,
    "loopMode": "LOOP"
  }
}
The NPC moves to stay near another Citizen identified by followCitizenId. The NPC maintains a distance of followDistance units (default 2.0) from the leader. Multiple followers automatically arrange themselves in a ring formation around the leader.
{
  "movementBehavior": {
    "type": "FOLLOW_CITIZEN",
    "walkSpeed": 4.0
  },
  "followCitizenId": "guard_captain",
  "followDistance": 2.5
}

​
Speed Settings

​
movementBehavior.walkSpeed
float
default:"10.0"
The movement speed of the NPC in blocks per second. When loading a FOLLOW_CITIZEN Citizen from the config file without an explicit walkSpeed, the config loader defaults to 4.0 to match a typical leader’s pace — but the model’s built-in default is 10.0.
​
movementBehavior.runSpeed
float
default:"6.0"
The NPC’s run speed, used when the NPC transitions to a faster movement state (for example, during combat chasing). Set via the run threshold in the underlying role template.

​
Wander Parameters

These fields are only meaningful for wander-type movement behaviors.
​
movementBehavior.wanderRadius
float
default:"10.0"
Radius of the circular wander area for WANDER and WANDER_CIRCLE modes. The NPC will not stray further than this distance from its spawn position.
​
movementBehavior.wanderWidth
float
default:"10.0"
Width (X dimension) of the rectangular wander boundary for WANDER_RECT mode.
​
movementBehavior.wanderDepth
float
default:"10.0"
Depth (Z dimension) of the rectangular wander boundary for WANDER_RECT mode.
If a wandering NPC becomes stuck (no meaningful position change for more than 35 seconds), HyCitizens automatically teleports it back to its spawn position after a 20-second recovery cooldown.

​
Follow Settings

​
followCitizenId
string
The id of the leader Citizen that this NPC should follow. Must be a valid Citizen ID in the same world. If the referenced Citizen does not exist or is in a different world, the follower stands idle.
​
followDistance
float
default:"2.0"
Target distance in blocks that the NPC tries to maintain from the leader. Minimum value is 0.1.
Citizens using FOLLOW_CITIZEN movement automatically form a ring formation around the leader NPC. When multiple Citizens follow the same leader, they distribute themselves evenly in concentric rings of up to six slots each, preventing them from stacking on top of one another.

​
Animation Behaviors

Animations are defined as a list of AnimationBehavior entries on the Citizen. Each entry specifies when an animation plays and for how long. Multiple animation behaviors can be active simultaneously across different animation slots.
Plays the specified animation continuously. HyCitizens re-sends the animation command every ~2 seconds to keep it active on the client.
{
  "type": "DEFAULT",
  "animationName": "Idle_Peaceful",
  "animationSlot": 0
}
Plays the animation once every intervalSeconds seconds.
{
  "type": "TIMED",
  "animationName": "Wave",
  "animationSlot": 1,
  "intervalSeconds": 10.0,
  "stopAfterTime": true,
  "stopAnimationName": "Idle_Peaceful",
  "stopTimeSeconds": 3.0
}
Plays once when a player interacts with the NPC (either left-click or F key, depending on interaction trigger settings).
{
  "type": "ON_INTERACT",
  "animationName": "Bow",
  "animationSlot": 1
}
Plays once when a player enters within proximityRange blocks of the NPC.
{
  "type": "ON_PROXIMITY_ENTER",
  "animationName": "Greet",
  "animationSlot": 1,
  "proximityRange": 8.0
}
Plays once when a player moves beyond proximityRange blocks from the NPC.
{
  "type": "ON_PROXIMITY_EXIT",
  "animationName": "Wave_Goodbye",
  "animationSlot": 1,
  "proximityRange": 8.0
}

​
Animation Fields

FieldTypeDefaultDescription
animationNamestring""The name of the animation to play.
animationSlotint00-based animation slot index. Different slots can play independently.
intervalSecondsfloat5.0Seconds between plays (for TIMED type only).
proximityRangefloat8.0Detection radius in blocks (for proximity types only).
stopAfterTimebooleanfalseWhether to automatically transition to a stop animation after a duration.
stopAnimationNamestring""Animation to play after stopTimeSeconds. Falls back to the DEFAULT animation for the same slot if empty.
stopTimeSecondsfloat3.0How long to play the main animation before switching to stopAnimationName.

Build docs developers (and LLMs) love

Get started for freeTalk to us