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.

Every Citizen NPC in HyCitizens can be fully customized to match your server’s visual style. From the 3D model and scale to equipment, nametag display, map marker icons, and even live-updating Minecraft player skins — the appearance system gives you granular control over how each NPC looks and presents itself in the world.

​
Model & Scale

The modelId field determines which 3D model the Citizen uses. Set it to any valid Hytale model asset ID (for example, Human for a standard humanoid NPC). To display the Citizen as a Minecraft-style player model, set modelId to Player and enable isPlayerModel = true. The scale field controls the uniform size of the model. It accepts any float between 0.01 and 100.0, defaulting to 1.0. 
{
  "modelId": "Human",
  "scale": 1.0
}
Use \n in the name field to display multi-line nametags above the NPC. For example: "name": "Shop Keeper\nClick to trade".

​
Player Skins

When isPlayerModel is true, the Citizen renders using Hytale’s player model. You can supply a skin in two ways:
  • Live skin — Set skinUsername to a Minecraft username and enable useLiveSkin = true. HyCitizens fetches the skin from Mojang’s API and caches it. The cache is refreshed automatically every 30 minutes while the server is running.
  • Custom skin — Upload a custom skin through the plugin’s skin management interface. When a custom skin is active, useLiveSkin is automatically disabled and the skin is stored in the cachedSkin field.
{
  "isPlayerModel": true,
  "useLiveSkin": true,
  "skinUsername": "Notch"
}
Internally, skin usernames starting with random_ or custom_ are treated as generated identifiers and will never trigger a live lookup, even if useLiveSkin is true.

​
Nametag

The name field is displayed above the NPC as a nametag. Use \n to split the name across multiple lines — each non-empty line becomes a separate floating text entity.
​
name
string
The display name of the Citizen. Supports \n for multi-line output.
​
hideNametag
boolean
default:"false"
When true, suppresses the nametag entirely. The NPC body is still visible unless hideNpc is also set.
​
nametagOffset
float
default:"0.0"
Vertical offset applied to the nametag position, relative to the NPC’s head. Positive values move it higher.

​
Model Nametag

Instead of floating text, the nametag slot can display a 3D model (for example, a floating icon or emblem above the NPC’s head).
​
modelNametagEnabled
boolean
default:"false"
Enables the model-based nametag. When true, the text nametag is replaced by a 3D model entity.
​
nametagModelId
string
The model asset ID used for the nametag model.
​
nametagModelScale
float
default:"1.0"
Scale of the nametag model. Clamped between 0.01 and 100.0.
​
rotateNametagTowardsPlayer
boolean
default:"true"
When true, the nametag model rotates to always face the nearest player.

​
Rotate Toward Player

HyCitizens can make a stationary Citizen smoothly turn its head and body to face the nearest player.
​
rotateTowardsPlayer
boolean
default:"false"
Enables player-facing rotation. Only applies when the Citizen’s movement type is IDLE.
​
lookAtDistance
float
default:"25.0"
Maximum distance (in blocks) within which the Citizen will look at a player. Players further away are ignored.

​
Equipment

Citizens can hold and wear items using the following fields. Each field accepts a Hytale item ID string. Set a field to null or omit it to leave that slot empty.
FieldSlotExample value
npcHelmetHead armorArmor_Iron_Helmet
npcChestChest armorArmor_Iron_Chestplate
npcLeggingsLeg armorArmor_Iron_Leggings
npcGlovesGlovesArmor_Iron_Gloves
npcHandMain handWeapon_Sword_Iron
npcOffHandOff handFurniture_Crude_Torch
{
  "npcHelmet": "Armor_Iron_Helmet",
  "npcHand": "Weapon_Sword_Iron",
  "npcOffHand": "Furniture_Crude_Torch"
}

​
Visibility

​
hideNpc
boolean
default:"false"
When true, the NPC body entity is not spawned. The Citizen still exists in memory and can display a nametag, trigger interactions, and be queried via the API.
​
hideNametag
boolean
default:"false"
When true, suppresses the nametag above the NPC. The body is still visible unless hideNpc is also set.
An invisible NPC with a visible nametag is useful for creating floating text markers or trigger zones that respond to player interaction.

​
Map Marker

Citizens can appear as icons on the in-game map. All map marker settings are nested under the mapMarker configuration block.
​
mapMarkerEnabled
boolean
default:"false"
Enables the map marker for this Citizen.
​
mapMarkerType
string
default:"PIN"
The icon style. Accepted values:PIN · DOT · STAR · DIAMOND · SQUARE · QUESTION · EXCLAMATION · MONEY_SYMBOL · SHOP · TRADER · CHEST · SWORD · SHIELD · HEART · HOME · NPC_TYPE · CUSTOM
​
mapMarkerName
string
Label displayed alongside the map icon.
​
mapMarkerCustomIcon
string
Filename of a custom .png icon (e.g. my_icon.png). Only used when mapMarkerType is CUSTOM. The file path is normalized to just the filename — subdirectory prefixes are stripped automatically.
​
mapMarkerMaxDistance
float
default:"0.0"
Maximum distance from the player at which the marker is visible. Set to 0 for unlimited visibility.
{
  "mapMarkerEnabled": true,
  "mapMarkerType": "SHOP",
  "mapMarkerName": "Blacksmith",
  "mapMarkerMaxDistance": 200.0
}

Build docs developers (and LLMs) love

Get started for freeTalk to us