Create Your First Citizen NPC with HyCitizens In-Game

This guide walks you through creating a fully working NPC — with a custom name, a model, and a player interaction — entirely through the HyCitizens in-game UI. You will have a live, persistent Citizen in your world in under five minutes. Prerequisites:

HyCitizens installed and running (Installation guide)
Logged in as a player with the hycitizens.admin permission

Create Your First Citizen

Open the Citizens UI

Run the following command in-game:

/citizens

The Citizens management UI will open. From here you can create new Citizens, edit existing ones, and delete them. The first time you open it, the list will be empty.

Create a new Citizen

Click Create to open the new Citizen form. Fill in the following fields:

Name — Enter a display name, for example Village Merchant. This name appears as the NPC’s nametag above its head.
Model — Choose an entity type or model ID. For a human-looking NPC, select Human (or Player if you want a player-shaped model with a configurable skin).

Once you are happy with the name and model, proceed to the next step before saving.

Set the NPC's position

Walk to the exact spot in the world where you want the Citizen to stand. Then, inside the Citizens UI, click Set Position to Mine. HyCitizens will capture your current coordinates and assign them to the Citizen.The Citizen will spawn at this position immediately after you save, and will return to this position after every server restart.

Add an interaction message

Navigate to the Interactions tab within the Citizen editor. Click Add Message and enter a greeting, for example:

Hello! Welcome to the village.

This message will be sent to any player who interacts with the Citizen. You can add multiple messages and choose whether they are delivered randomly or in sequence.

Save the Citizen

Click Save. HyCitizens immediately spawns the NPC at the position you set. You should see your Village Merchant appear in the world with its nametag visible overhead.Walk up to the Citizen and interact with it — you will receive the message you configured.

What Happens on Server Restart

HyCitizens automatically persists all Citizen data to mods/HyCitizensData/data.json every time you save. When the server restarts, the plugin reads this file during startup and respawns every Citizen at its saved position — no manual steps required. You can verify this by restarting your server and confirming that Village Merchant reappears exactly where you placed it.

Next Steps

Now that your first Citizen is live, explore the full range of configuration options:

Customize Appearance

Change the model, apply player skins, adjust scale, equip armor and held items, and toggle nametag visibility.

Configure Movement

Set up idle, wander, patrol, and follow behaviors to make your Citizens move naturally through the world.

Set Up Interactions

Add command actions, permission requirements, and multiple messages triggered by player interactions.

Developer API

Spawn and manage Citizens programmatically, and listen for Citizen events from your own plugins.

Get Started

In-Game Management

Citizen Configuration

Create Your First Citizen NPC with HyCitizens In-Game