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.

Patrol paths let Citizens walk a fixed route through the world, visiting a sequence of waypoints in order. Patrols are defined independently of any Citizen — you create a named path with the Patrol Stick tool, then assign that name to one or more Citizens. Citizens can loop the path continuously or reverse direction at the end, and each waypoint can include a configurable pause.

​
How Patrols Work

A PatrolPath consists of a name, a loop mode, and an ordered list of PatrolWaypoint objects. A Citizen begins patrolling when:
  1. Its movementBehavior.type is set to PATROL, and
  2. pathConfig.pluginPatrolPath contains the name of a saved patrol path.
HyCitizens starts the patrol automatically when the Citizen spawns or when its configuration is updated. If the named path does not exist, the Citizen stands idle until a matching path is created.
If the patrol path name set on a Citizen does not match any saved path, the Citizen will stand idle. Double-check that the name in pathConfig.pluginPatrolPath matches the path name exactly, including capitalization.

​
PathConfig Fields

The pathConfig block on a Citizen controls how it interacts with the patrol system:
​
pathConfig.pluginPatrolPath
string
The name of the patrol path this Citizen should follow. Must match the name of a saved PatrolPath exactly.
​
pathConfig.pluginPatrolSpeed
float
default:"2.0"
Movement speed used while walking the patrol route. Minimum value is 0.1. This is a relative speed multiplier applied to the Citizen’s walk speed.
​
pathConfig.loopMode
string
default:"LOOP"
How the Citizen behaves when it reaches the last waypoint. See Loop Modes below.
​
pathConfig.followPath
boolean
default:"false"
Internal field used by the NPC role system. HyCitizens manages this automatically when movementBehavior.type is PATROL.
​
pathConfig.patrol
boolean
default:"false"
Internal field used by the NPC role system. Managed automatically by HyCitizens.
​
pathConfig.patrolWanderDistance
float
default:"25.0"
How far the Citizen may wander from the patrol path during break phases (used by the underlying Hytale patrol state machine).

​
Loop Modes

The Citizen walks from the first waypoint to the last. After reaching the last waypoint, it returns to the first waypoint and repeats the route indefinitely.
{
  "pathConfig": {
    "loopMode": "LOOP"
  }
}
The Citizen walks from the first waypoint to the last, then reverses direction and walks back to the first waypoint. This back-and-forth cycle repeats indefinitely. Useful for guard patrols that cover a linear stretch.
{
  "pathConfig": {
    "loopMode": "PING_PONG"
  }
}

​
PatrolWaypoint Fields

Each waypoint in a patrol path has the following properties:
FieldTypeDescription
xdoubleWorld X coordinate of the waypoint.
ydoubleWorld Y coordinate of the waypoint.
zdoubleWorld Z coordinate of the waypoint.
pauseSecondsfloatHow long the Citizen pauses at this waypoint before continuing. Set to 0 for no pause.

​
Creating a Patrol Path with the Patrol Stick

The recommended way to create patrol paths in-game is with the Patrol Stick tool provided by HyCitizens.
1

Obtain the Patrol Stick

Use the HyCitizens admin command to receive the Patrol Stick item. Once held, it enters patrol path editing mode.
2

Place waypoints

Walk to each location where you want a waypoint and right-click to place a marker. Waypoints are recorded in the order you place them. Repeat for every stop on the route.
3

Name and save the path

Enter a unique name for the patrol path when prompted. The path is saved to disk and immediately available to all Citizens.
4

Assign the path to a Citizen

Set the Citizen’s movement type and path reference:
{
  "movementBehavior": {
    "type": "PATROL"
  },
  "pathConfig": {
    "pluginPatrolPath": "market_route",
    "pluginPatrolSpeed": 2.0,
    "loopMode": "LOOP"
  }
}
Save the Citizen. It will begin following the patrol path on its next spawn or configuration update.

​
Starting and Stopping Patrols via the API

Patrols can also be controlled programmatically through the HyCitizens API. The PatrolManager exposes methods to start, stop, and query patrol state for any Citizen at runtime. For full details, see the Patrol Manager API reference. 
// Start a patrol
citizensManager.startCitizenPatrol("guard_01", "market_route");

// Stop a patrol
citizensManager.stopCitizenPatrol("guard_01");

// Check if patrolling
boolean isPatrolling = citizensManager.isCitizenPatrolling("guard_01");

// Get the active path name
String activePath = citizensManager.getCitizenActivePatrolPath("guard_01");

Build docs developers (and LLMs) love

Get started for freeTalk to us