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 rich interaction system that lets Citizens respond to player input with commands, rich text messages, animations, and more. Each Citizen can be configured with multiple command actions and messages, each independently controlled by trigger type, delay, selection mode, and probability. You can also gate interactions behind permissions and create unique one-time experiences for a player’s very first encounter with an NPC.

​
Interaction Triggers

Every command action and message has an interactionTrigger field that determines which player input fires it:
TriggerWhen it fires
LEFT_CLICKWhen a player hits or attacks the NPC.
F_KEYWhen a player presses the interaction key (F) near the NPC.
BOTHEither a left-click or F key press (default).
When at least one action or message uses F_KEY or BOTH, HyCitizens automatically adds the [Press F] interaction hint above the NPC. You can force this hint to display regardless of trigger configuration with forceFKeyInteractionText = true.

​
Command Actions

Command actions run server or player commands when a player interacts with a Citizen. They are defined as a list under commandActions, with the selection mode set by commandSelectionMode.
​
command
string
required
The command string to execute, without a leading /. Supports placeholders (see below).Use the special prefix {SendMessage} to send a rich text message instead of executing a command: {SendMessage}{GOLD}Welcome, {PlayerName}!
​
runAsServer
boolean
default:"false"
When true, the command is executed with server-level permissions. When false, it runs as the interacting player.
​
delaySeconds
float
default:"0.0"
How many seconds to wait before executing this command after the interaction fires.
​
interactionTrigger
string
default:"BOTH"
Which input fires this action: LEFT_CLICK, F_KEY, or BOTH.
​
chancePercent
float
default:"100.0"
Probability (0–100) that this action executes when selected. A value of 100 means it always runs; 50 means it runs half the time.

​
Command Selection Mode

The commandSelectionMode field controls how multiple command actions are chosen when an interaction fires:
ModeBehavior
ALLEvery qualifying command runs in order.
RANDOMOne qualifying command is chosen at random.
SEQUENTIALCommands cycle round-robin per player — each interaction picks the next command.

​
Message Actions

Message actions send rich text directly to the interacting player’s chat. They are defined under messagesConfig.messages, with the selection mode set by messagesConfig.selectionMode.
​
message
string
required
The message text. Supports color codes, markdown-like formatting, and links (see formatting syntax below).
​
interactionTrigger
string
default:"BOTH"
Which input fires this message: LEFT_CLICK, F_KEY, or BOTH.
​
delaySeconds
float
default:"0.0"
How many seconds to wait before sending this message.
​
chancePercent
float
default:"100.0"
Probability (0–100) that this message is sent when selected.

​
Message Selection Mode

Set messagesConfig.selectionMode to control which messages are sent:
ModeBehavior
ALLEvery qualifying message is sent.
RANDOMOne qualifying message is chosen at random (default).
SEQUENTIALMessages cycle round-robin per player.

​
Message Formatting Syntax

{RED}This text is red.
{GOLD}This is gold text.
{LIGHTBLUE}Light blue text here.

​
Placeholders

The following placeholders are replaced dynamically in both command and message strings:
PlaceholderReplaced with
{PlayerName}The username of the interacting player.
{CitizenName}The Citizen’s name field (newlines replaced with spaces).
{NpcX}The Citizen’s current X coordinate (2 decimal places).
{NpcY}The Citizen’s current Y coordinate (2 decimal places).
{NpcZ}The Citizen’s current Z coordinate (2 decimal places).

​
Permission

You can gate interactions behind a Hytale permission node.
​
requiredPermission
string
A permission node string. If set and the player does not have this permission, the interaction is blocked and noPermissionMessage is shown. Leave empty to allow all players.
​
noPermissionMessage
string
Message shown to players who lack the required permission. Defaults to "You do not have permissions" if left empty.

​
First Interaction

The first-interaction system lets you fire a completely different set of commands and messages the very first time a player interacts with a Citizen. This is useful for tutorial NPCs, quest starters, or one-time welcome sequences.
​
firstInteractionEnabled
boolean
default:"false"
Enables the first-interaction flow. When true, the first time a specific player interacts with this Citizen, their UUID is recorded and the first-interaction commands and messages fire instead of (or in addition to) the normal ones.
​
postFirstInteractionBehavior
string
default:"NORMAL"
Controls what happens after the first-interaction sequence:
  • NORMAL — the normal commands and messages also run on subsequent interactions.
  • NONE — after the first interaction, normal commands and messages are skipped until reset.
​
runNormalOnFirstInteraction
boolean
default:"false"
When true, the normal commands and messages also run during the very first interaction alongside the first-interaction sequence.
The firstInteractionCommandSelectionMode and firstInteractionMessagesConfig.selectionMode fields follow the same ALL / RANDOM / SEQUENTIAL logic as the normal interaction flows.

​
Death Actions

The deathConfig block configures what happens when a Citizen is killed. Death events fire independently of normal interactions.
​
deathConfig.deathCommands
array
A list of CommandAction entries that execute when the Citizen dies. Follows the same command, runAsServer, delay, and chancePercent fields as normal command actions.
​
deathConfig.deathMessages
array
A list of CitizenMessage entries sent to the player who dealt the killing blow.
​
deathConfig.dropItems
array
Items dropped on death. Each entry has:
  • itemId — the Hytale item ID to drop.
  • quantity — number of items in the stack.
  • chancePercent — probability (0–100) that this item drops.
​
deathConfig.commandSelectionMode
string
default:"ALL"
Selection mode for death commands: ALL, RANDOM, or SEQUENTIAL.
​
deathConfig.messageSelectionMode
string
default:"ALL"
Selection mode for death messages: ALL, RANDOM, or SEQUENTIAL.
{
  "deathConfig": {
    "commandSelectionMode": "ALL",
    "messageSelectionMode": "RANDOM",
    "dropItems": [
      { "itemId": "Resource_Gold_Coin", "quantity": 3, "chancePercent": 100.0 },
      { "itemId": "Weapon_Sword_Iron",  "quantity": 1, "chancePercent": 25.0  }
    ],
    "deathCommands": [
      { "command": "broadcast {PlayerName} defeated the guard!", "runAsServer": true }
    ],
    "deathMessages": [
      { "message": "{RED}You have defeated me...", "chancePercent": 100.0 }
    ]
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us