Minecraft plugin Citizens

🔌 About Citizens

Citizens — is a Minecraft server plugin that allows server operators and developers to create and manage server‑side NPCs (non‑player characters) such as shopkeepers, guards, statues and scripted characters. It provides an API for addons and integrations and is maintained as Citizens2 for modern Paper/Spigot servers.

🎯 Purpose

Citizens addresses the need for persistent, configurable NPCs that can enrich gameplay, provide shops/pathing/dialogue, and serve as scripted world characters. It solves the problem of lacking server‑side NPC support and gives plugin authors a stable API to extend NPC behavior. ()

⚙ Key features

• Create persistent NPCs of many entity types (players, mobs, non‑living entities) using in‑game commands or API. ()
• Traits system: modular behaviors that can be attached to NPCs (extensions/addons implement traits). ()
• Pathing and movement for NPCs (waypoints, walking). ()
• Integration points for addons (e.g., Denizen, Sentinel, Trader and other third‑party extensions). ()
• Plugin API for developers to program custom NPC behaviors and traits. ()

🧩 Who it's for

• Server owners running Paper/Spigot who need NPCs for shops, roleplay, guides, or worldbuilding.
• Plugin developers who want an API to create custom NPC behaviors and integrations.
• Administrators that need persistent world objects that can run commands or interact with players.

🏗 Example usages

• Create shopkeeper NPCs that open GUIs or run commands when clicked.
• Spawn guards with combat traits (via addon like Sentinel) to protect areas.
• Place static statues or quest givers with dialogue and scripts (Denizen integration).

⌨️ Commands

The Citizens plugin exposes the primary commands /citizens and /npc with many subcommands. Below are commonly used, confirmed commands (see permissions for nodes). All command names and nodes are taken from the Citizens documentation and permissions listing. ()

Note: Citizens has many subcommands and plugin authors may add commands via traits or addons. For a full command list consult the Citizens Wiki and the plugin resources. ()

🔐 Permissions

Default behavior: many Citizens permissions default to OP by default (see official permissions documentation). Below are commonly referenced nodes confirmed in the Citizens permissions documentation. ()

If your server uses a permissions plugin, map these nodes to groups as appropriate. For an up‑to‑date and exhaustive list, check the plugin.yml or the Citizens permissions page. ()

⚙ Installation

📥 Installation

• Download the Citizens .jar from the official release (Spigot/CI/GitHub). ()
• Place the .jar into your server plugins/ folder.
• Fully restart the server (do not rely on /reload).
• On first run the plugin will create its data folder and files (see Wiki for exact filenames). ()

📦 Dependencies

• Citizens2 does not require a mandatory external plugin to run its core NPC functionality. Some features rely on optional addons (third‑party) such as Denizen (scripting), Sentinel (combat/guard behavior), Trader/CitiTraders (shops) — these are not required by core Citizens but are commonly used together. ()

🧾 Configuration

• Citizens generates its data files and directories under plugins/Citizens/ on first run (consult the Wiki for details). ()
• Many features are configurable via the plugin data files; third‑party traits/addons often add their own config.
• Database: core Citizens stores NPC data in flat files (saves); some addons may offer MySQL/SQLite storage — check addon docs (Citizens core does not require a DB by default). If you need external DB support, verify via the specific addon documentation. ()

🧠 Additional information

Known conflicts / limitations

• Because Citizens manipulates entities, pathing and AI, conflicts may appear with other plugins that heavily modify entity behavior or register the same command nodes — test in staging before production. (General guidance from documentation and community resources.) ()
• Proxy/multi‑server setups: compatibility depends on architecture and addons used; verify behavior for cross‑server persistence. ()

FAQ

Q: Does Citizens collect metrics? A: Citizens has historically used Metrics/bStats for anonymous telemetry; opt‑out instructions are available in the plugin metrics config. ()

Q: Is there a developer API? A: Yes — Citizens exposes an API for creating traits and integrating with NPCs. See the GitHub repo and Wiki for API docs. ()

Q: Do I need Denizen or Sentinel? A: No — these are optional addons that extend NPC capability (scripting, combat). Citizens core runs without them. ()

Q: Where to report bugs or get support? A: The community Wiki, the GitHub issues tracker and the Citizens Discord are official support channels. ()

Support / Community

• Official site and downloads: Citizens official site and Spigot resource. ()
• Source & API: GitHub repository (CitizensDev/Citizens2). ()
• Documentation: Citizens Wiki. ()

When using Citizens on production servers, test traits and addons on a staging environment and map permission nodes carefully. Citizens is best suited to servers that need persistent, scriptable NPCs and a stable API for extension. ()