Citizens: NPCs and quest characters on a Minecraft server

Citizens turns a server into a populated world. Without it you either have no NPCs at all or some hacked-together solution with invisible zombies. We will walk through installation, setup and integration with Quests or Denizen, so you end up with proper merchants, guards and questgivers.

What Citizens is and why this one

Citizens is an open-source plugin developed since 2011, and after 14 years it became the industry standard for NPCs on Spigot and Paper. Out of the box it creates static and moving characters, applies skins, equipment, name holograms and click reactions. It does not provide quests or shops by itself, but its API is what dozens of other plugins build on.

There are alternatives: ZNPCsPlus, FancyNpcs, Adyeshach. They are newer, lighter and sometimes faster on huge servers, but almost no popular quest plugin talks to them directly. If you install Quests, BeautifulQuests, Sentinel, Denizen, ShopKeepers or any of a hundred other plugins, they all want Citizens. So in most cases the choice is obvious.

In practice Citizens currently powers NPCs on servers from small private RP shards to large minigame networks. The plugin has active development, regular releases for new Minecraft versions and a Discord for bug reports.

Installing on Paper or Spigot

Grab the latest .jar from the official site or from Spigot resources. The 2.0.x series works on Paper and Spigot 1.20.x and 1.21.x. For 1.16-1.19 use older builds from the dev channel.

Drop the .jar into plugins/, restart. After startup you will see:

plugins/Citizens/
├── config.yml
├── saves.yml
├── traits/
└── messages.yml

saves.yml holds your NPCs. Back it up alongside the world. If the file gets corrupted, every NPC vanishes, and rebuilding them by hand is no fun. I lost 40 NPCs once because of a crash mid-save, ever since I keep a separate copy of saves.yml every two hours.

If you plan to write your own plugin with Citizens integration, add CitizensAPI as a compileOnly dependency and put softdepend: [Citizens] in plugin.yml.

Creating your first NPC

The basic command:

/npc create Quester

The NPC spawns at your position with an auto-assigned id. By default it uses your own player skin. To change it:

/npc skin Notch
/npc skin --url https://textures.minecraft.net/texture/abc123...

You can pass any current Mojang username, and Citizens fetches the texture. For full control use MineSkin, generate a custom skin, copy the URL and paste it after --url. Skins get cached locally so the API is not hammered on every respawn.

Basic editing commands

First you select an NPC: stand near it and left-click, or run /npc sel <id>. Everything below operates on the selected NPC.

/npc rename &eMerchant
/npc lookat <player|coords>
/npc equip
/npc move
/npc despawn
/npc spawn
/npc remove
/npc remove all

/npc equip opens a GUI where you place armor and an item in hand. /npc move teleports the NPC to you. /npc lookat makes it face the nearest player. /npc rename supports legacy & colors and on modern versions MiniMessage tags if enabled in config.yml.

Useful extras:

/npc list
/npc help <page>
/npc tphere
/npc tp
/npc copy

/npc copy clones an NPC with all its traits, which saves time when you build a row of identical guards.

Behavior: patrol, follow, wander

Citizens ships with three movement modes. They are added through /npc behavior or the matching trait:

/npc path
/npc wander
/npc follow <player>

/npc path opens a path editor. You literally place waypoints by left-clicking blocks, then save. The NPC walks the loop. Useless for a merchant, perfect for a patrolling guard or village ambient animation.

/npc wander does random walking inside a radius:

/npc wander --range 10 --delay 100

/npc follow attaches the NPC to a target player. Handy for story companions in RP scenarios.

If the default pathfinder feels dumb, install Citizens-Pathfinder or use Sentinel which has smarter navigation. The vanilla one sometimes gets stuck on stairs and fences.

Trait system

A trait is a behavior module attached to an NPC. Citizens ships with several core traits, others come from third-party plugins:

/npc trait gravity
/npc trait sneak
/npc trait sleep
/npc trait controllable

gravity toggles gravity for flying NPCs. controllable lets a player ride and steer the NPC like a horse, useful for cutscenes. sleep puts the NPC into a bed.

List every available trait:

/npc trait --list

Each trait stores its data inside the NPC and persists in saves.yml. Remove a trait with:

/npc trait --remove gravity

Click commands

The most useful feature on servers without a quest plugin. Citizens can attach a list of commands that fire when the NPC is clicked:

/npc command add say Hello %player%!
/npc command add --player heal %player%
/npc command add --op gamemode creative %player%
/npc command add --console give %player% diamond 1
/npc command list
/npc command remove <id>

--player runs the command as the player (they need the actual permission). --op grants temporary op for one command. --console runs from console, which is what you usually want for giving items or money.

Extra options:

/npc command cooldown 30
/npc command cost 100
/npc command permissions essentials.heal
/npc command sequential

cost charges money through Vault, cooldown adds a per-player delay, sequential runs commands one by one across clicks instead of all at once.

Quests integration

If you need real quests with progress, objectives and rewards, do not roll your own with /npc command. Use a quest plugin on top of Citizens.

Quests by LMBishop (a fork of the original BlackVein project) is the most popular pick. GUI editor plus yml files, supports kill quests, mining, deliveries, dialogue, branching choices. Linking to NPCs is simple:

/quests editor

In the editor you set NPC IDs for giver and receiver, and a player picks up the quest by clicking.

BeautifulQuests is a modern alternative focused on a polished GUI. Functionally similar, the choice is mostly taste.

For really complex non-linear scenarios, look at Denizen.

Denizen: scripting for serious scenarios

Denizen is a full Bukkit scripting language that integrates with Citizens through the DenizenCitizens bridge. The syntax looks like YAML but with variables, conditions and tags.

A simple dialogue script:

greet_quest:
  type: assignment
  actions:
    on assignment:
    - trigger name:chat state:true
    - trigger name:click state:true
  interact scripts:
  - 10 GreetInteract

GreetInteract:
  type: interact
  steps:
    1:
      click trigger:
        script:
        - chat "Hi <player.name>! Bring me 5 iron."
        - flag <player> waiting_iron
      chat trigger:
        1:
          trigger: /Thanks/
          script:
          - chat "Anytime."

The plugin gives you control of basically everything: NPCs, mobs, world events, economy, inventories. The learning curve is steep, but once you get it, you build scenarios impossible in regular quest plugins: branching dialogues with memory, complex cutscenes, merchants whose behavior depends on time of day.

Big RP servers often write their entire content in Denizen for exactly that flexibility.

Sentinel: combat NPCs

Citizens by default is a pacifist. For guards, raid bosses or PvE arena mobs, install Sentinel. It is an addon by the same author and works as a trait.

Building a guard:

/npc create Guard
/npc trait sentinel
/sentinel addtarget MONSTER
/sentinel addtarget PLAYER
/sentinel ignore OWNER
/sentinel range 16
/sentinel damage 8
/sentinel armor 0.3

Sentinel knows how to swing a sword, use a bow, throw fireballs and snowballs. It supports groups so guards do not friendly-fire, and an owner system so an NPC will not attack its creator.

Combat parameters are tunable: attack range, damage, speed, crit chance, regen. Big servers use Sentinel for both city guards and dungeon bosses.

Holograms above NPCs

The name above the head is a single-line hologram. For multiple lines or icons, install DecentHolograms or HolographicDisplays and link it to the NPC.

DecentHolograms attaches directly:

/dh create questgiver
/dh line add questgiver &aQuest Giver
/dh line add questgiver &7Click to start
/dh attach questgiver <npc-id>

The hologram follows the NPC when it moves and disappears on despawn. Far more flexible than the built-in name and supports PlaceholderAPI, so you can show live variables.

Performance

A single NPC costs little: render packets, occasional position updates and player trackers. In practice 100 static NPCs at spawn run fine even on a weak VPS. Past 500, things start to matter.

What loads the server:

• Pathfinding. NPCs with patrol or wander recalculate paths every tick. A bunch of them in one chunk noticeably hurts.
• Sentinel target scans. Each guard scans a radius for targets. A hundred guards with radius 16 means a thousand entity checks per second.
• Holograms with PAPI. If every NPC has a hologram with %vault_eco_balance% updating once a second, you are hitting the economy backend a hundred times per second.

Tuning:

npc:
  default-look-close:
    enabled: false
  default-look-distance: 6
  pathfinder:
    new-finder: true

In config.yml disable look-close for static NPCs when there are many. Acceptable for merchants and questgivers, mandatory for purely decorative ones.

Storage and backup

Every NPC lives in plugins/Citizens/saves.yml. Citizens persists them on a timer (save-task in config.yml, default 5 minutes) and on graceful shutdown. A crash loses everything since the last autosave.

A simple cron backup:

0 */2 * * * cp /opt/server/plugins/Citizens/saves.yml /opt/backup/citizens-$(date +\%Y\%m\%d-\%H).yml

Every two hours a separate timestamped copy. Recovery is just copy the file back and restart. No DB tables, everything in one file, which makes migrations easy.

When moving to a new host, take saves.yml, traits/ and config.yml. NPCs come back up with the same ids, skins and behavior.

FAQ

Does Citizens work on Folia?

As of spring 2026, partially. Folia drops the traditional main thread and replaces it with regions, which breaks most plugins that assume single-threaded sync. Citizens 2.0.36+ has experimental Folia support, but many traits and addons (including Sentinel) are not there yet. If you specifically need an NPC plugin for Folia, look at FancyNpcs or Adyeshach, both written with region threading in mind.

How do I make a merchant NPC with economy?

The simplest route is ShopKeepers with Citizens integration. Install both, attach a shop to the NPC with /shopkeeper while standing next to it. ShopKeepers supports Vault and works with any economy plugin. For more advanced cases (dynamic prices, taxes, guild discounts) use DynamicShop or TradersListGUI plus a Citizens trait.

Can I make an NPC follow a route?

Yes, with /npc path. Place waypoints by left-clicking, the plugin remembers the path, the NPC walks it on a loop. There is randomized waypoint delay and a one-shot mode. For complex routes through doors and portals a Denizen script with walk and waitfor commands is more reliable.

Citizens vs Sentinel: what is the difference?

Citizens is the base, the NPC engine. It creates the character, applies the skin, attaches click scripts, draws the path. Sentinel is an addon on top of Citizens that adds one thing: combat. Sentinel does not run without Citizens, it is a trait extension. If you only need questgivers and merchants, Citizens alone is enough. Need guards, mobs or raid bosses? Install both.

Skins do not load, what now?

Usually a cache or Mojang API issue. Check the server has internet, try /npc skin <name> --update. If a name lookup fails, use a direct texture URL via MineSkin. Sometimes deleting plugins/Citizens/skins.yml and letting the plugin rebuild the cache helps.

The NPC moves jerkily or falls through the ground

Symptom of an outdated build or anti-cheat conflict. Update Citizens to the latest jar. If you run NoCheatPlus or Matrix, exempt Citizens NPCs by UUID or tag. Falling through the ground usually means it spawned in an unloaded chunk, set keep-spawn-loaded: true in paper-world.yml for that world.

What next

Citizens by itself is powerful, but really shines through integrations. The minimum stack for a living server: Citizens + DecentHolograms + Quests + ShopKeepers. That covers questgivers, merchants and decorative NPCs.

If you plan complex RP scenarios with branching dialogue, learning Denizen pays off long term. For PvE-heavy servers, do not skip Sentinel and a proper mob plugin like MythicMobs.

And keep backing up saves.yml. NPCs are hours of builder and writer work, losing them to a single crash hurts.