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.

The schedule system allows Citizen NPCs to follow time-based routines that mirror a day-in-the-life pattern. A blacksmith might work at the forge in the morning, wander around the market at midday, and stand guard at the inn at night. Schedules are defined as a list of time-windowed entries on each Citizen, with each entry specifying where to go, what to do on arrival, and how to travel there.

​
How Schedules Work

Each Citizen has a scheduleConfig block. When scheduleConfig.enabled is true, HyCitizens evaluates the list of entries every tick against the current in-game time. The active entry (the one with the highest priority whose time window contains the current time) dictates the Citizen’s behavior. Time values use a 24-hour float format:
  • 8.0 = 8:00 AM
  • 12.5 = 12:30 PM
  • 17.75 = 5:45 PM
  • 0.0 = midnight
When no entry is active, the Citizen falls back to the behavior defined by fallbackMode.
Schedule entries can overlap in time. When two entries are active simultaneously, the entry with the highest priority value wins.

​
ScheduleEntry Fields

Each item in scheduleConfig.entries has the following fields:
FieldTypeDefaultDescription
idstringrequiredUnique identifier for this entry within the Citizen’s schedule.
namestring""Human-readable display name shown in the schedule debug UI.
enabledbooltrueSet to false to temporarily disable this entry without deleting it.
startTime24double8.0When the entry activates (24-hour float). Clamped to 0–24.
endTime24double17.0When the entry deactivates (24-hour float). If endTime24 < startTime24, the window wraps midnight.
locationIdstring""References a ScheduleLocation by its id. The Citizen travels here on activation.
activityTypeenumIDLEWhat the Citizen does after arriving. See activity types below.
arrivalRadiusfloat1.5How close (blocks) the Citizen must get before the travel phase is considered complete. Minimum 0.25.
travelSpeedfloat10.0Movement speed used while traveling to the target location. Minimum 1.0.
wanderRadiusfloat5.0Wander radius used when activityType is WANDER. Minimum 1.0.
patrolPathNamestring""Name of the patrol path used when activityType is PATROL.
followCitizenIdstring""Citizen ID to follow when activityType is FOLLOW_CITIZEN.
followDistancefloat2.0Follow distance when activityType is FOLLOW_CITIZEN. Minimum 0.1.
arrivalAnimationNamestring""Animation played once when the Citizen arrives at the location.
arrivalAnimationSlotint0Animation slot index for the arrival animation.
priorityint0When multiple entries overlap in time, the entry with the highest value is used.

​
Activity Types

ValueBehavior after arrival
IDLECitizen stands still at the target location.
WANDERCitizen wanders within wanderRadius of the target location.
PATROLCitizen follows the patrol path named in patrolPathName.
FOLLOW_CITIZENCitizen follows the Citizen identified by followCitizenId.

​
ScheduleLocation Fields

Locations are defined in scheduleConfig.locations and referenced by their id from schedule entries.
FieldTypeDescription
idstringUnique identifier referenced by ScheduleEntry.locationId.
namestringHuman-readable label for the location.
worldUUIDUUIDThe world in which this location exists.
positionVector3dX/Y/Z world coordinates.
rotationVector3fX/Y/Z Euler rotation applied on arrival.

​
Fallback Mode

​
scheduleConfig.fallbackMode
string
default:"USE_BASE_BEHAVIOR"
Determines what the Citizen does when no schedule entry is active:
  • USE_BASE_BEHAVIOR — the Citizen reverts to its normal movementBehavior and base role configuration.
  • GO_TO_DEFAULT_LOCATION_IDLE — the Citizen travels to the location referenced by defaultLocationId and stands idle there.
  • HOLD_LAST_SCHEDULE_STATE — the Citizen remains in the state from the most recently active schedule entry rather than reverting.
​
scheduleConfig.defaultLocationId
string
When fallbackMode is active and this field is set, the Citizen travels to this location ID before resuming its base behavior.

​
Example Schedule Setup

The following walkthrough creates a simple two-entry schedule for a blacksmith NPC who works at the forge by day and rests at the inn at night.
1

Create the locations

Add two locations to scheduleConfig.locations:
{
  "scheduleConfig": {
    "locations": [
      {
        "id": "forge",
        "name": "The Forge",
        "worldUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "position": { "x": 120.0, "y": 64.0, "z": -45.0 },
        "rotation": { "x": 0.0, "y": 1.57, "z": 0.0 }
      },
      {
        "id": "inn",
        "name": "The Inn",
        "worldUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "position": { "x": 95.0, "y": 64.0, "z": -30.0 },
        "rotation": { "x": 0.0, "y": 0.0, "z": 0.0 }
      }
    ]
  }
}
2

Create the schedule entries

Add two entries to scheduleConfig.entries:
{
  "entries": [
    {
      "id": "work_shift",
      "name": "Working at the Forge",
      "enabled": true,
      "startTime24": 7.0,
      "endTime24": 18.0,
      "locationId": "forge",
      "activityType": "WANDER",
      "wanderRadius": 4.0,
      "travelSpeed": 10.0,
      "arrivalAnimationName": "Craft",
      "arrivalAnimationSlot": 0,
      "priority": 0
    },
    {
      "id": "rest",
      "name": "Resting at the Inn",
      "enabled": true,
      "startTime24": 18.0,
      "endTime24": 7.0,
      "locationId": "inn",
      "activityType": "IDLE",
      "travelSpeed": 10.0,
      "priority": 0
    }
  ]
}
Note that the rest entry spans midnight because endTime24 (7.0) < startTime24 (18.0).
3

Enable the schedule

Set scheduleConfig.enabled to true on the Citizen:
{
  "scheduleConfig": {
    "enabled": true,
    "fallbackMode": "USE_BASE_BEHAVIOR",
    "defaultLocationId": "forge"
  }
}
The Citizen will now follow the schedule. Save the Citizen to persist the changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us