Citizens: NPC и квестовые персонажи на Minecraft сервере

Citizens - это плагин, который превращает сервер в обитаемый мир. Без него NPC на сервере либо нет совсем, либо они сделаны костылями через невидимых зомби. Разберём, как поставить, настроить и связать с Quests или Denizen, чтобы получить полноценных торговцев, охранников и квестодателей.

Что такое Citizens и почему именно он

Citizens - open-source плагин, который развивается с 2011 года и за 14 лет стал отраслевым стандартом для NPC на Spigot и Paper. Из коробки он умеет создавать неподвижных и движущихся персонажей, вешать на них скины, броню, имена-голограммы и реакции на клик. Сам по себе он не делает квестов и магазинов, но даёт API, через который это умеют десятки других плагинов.

Альтернативы есть: ZNPCsPlus, FancyNpcs, Adyeshach. Они моложе, легче и иногда быстрее на больших серверах, но почти ни один популярный quest-плагин не умеет работать с ними напрямую. Если ставишь Quests, BeautifulQuests, Sentinel, Denizen, ShopKeepers и сотню других - они хотят именно Citizens. Поэтому в большинстве случаев выбор очевиден.

На практике Citizens сейчас держит NPC на серверах от мелких приватных RP до крупных миниигровых сетей. У плагина живая разработка, регулярные релизы под новые версии Minecraft и активный Discord для багрепортов.

Установка на Paper или Spigot

Скачивай свежий .jar с официального сайта или с Spigot resources. Версии 2.0.x совместимы с Paper и Spigot 1.20.x - 1.21.x. Для 1.16-1.19 берёшь старые сборки из dev-канала.

Кладёшь .jar в plugins/, перезапускаешь сервер. После старта появятся:

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

saves.yml - это твои NPC. Бэкапь его регулярно вместе с миром. Если файл побьётся, все NPC исчезнут, и восстанавливать их вручную небыстрое удовольствие. У меня лично один раз пропали 40 NPC из-за крашa во время сохранения, с тех пор делаю отдельный бэкап saves.yml каждые два часа.

Если будешь писать свои плагины с интеграцией Citizens - подключай CitizensAPI как compileOnly зависимость, а в plugin.yml ставь softdepend: [Citizens].

Создание первого NPC

Базовая команда выглядит так:

/npc create Quester

NPC появляется прямо на твоей позиции, его id присваивается автоматически. По умолчанию это игроковский скин с твоим ником. Чтобы сменить:

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

Можно указать ник любого живого аккаунта Mojang, и Citizens подтянет его текстуру. Для полного контроля используй MineSkin - там генерируешь свой скин, получаешь URL и подсовываешь его в --url. Скины кешируются локально, чтобы не дёргать API на каждом respawn.

Базовые команды редактирования

Сначала выбираешь NPC - встань рядом и нажми ЛКМ или используй /npc sel <id>. Дальше всё работает с выбранным.

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

/npc equip открывает GUI, куда кидаешь броню и предмет в руку. /npc move переносит NPC к тебе. /npc lookat заставляет его поворачиваться к ближайшему игроку. /npc rename поддерживает legacy-цвета через & и для современных версий MiniMessage-теги, если включил их в config.yml.

Полный список с алиасами:

/npc list
/npc help <страница>
/npc tphere
/npc tp
/npc copy

/npc copy дублирует NPC со всеми traits, что экономит время если делаешь линию из одинаковых охранников.

Поведение: patrol, follow, wander

Из коробки Citizens умеет три режима движения. Их добавляют через /npc behavior или соответствующий trait:

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

/npc path запускает редактор маршрута. Ты буквально расставляешь точки кликом ЛКМ по блокам, потом сохраняешь. NPC будет циклически ходить между ними. Для торговца это лишнее, для патрульного охранника или анимации деревенской жизни - то что надо.

/npc wander - случайные блуждания в радиусе. Можно ограничить зоной:

/npc wander --range 10 --delay 100

/npc follow цепляет NPC к указанному игроку. Полезно для сюжетных компаньонов в RP-сценариях.

Если стандартного pathfinding не хватает, ставь Citizens-Pathfinder или используй Sentinel с его более умной навигацией. Стандартный иногда залипает на лестницах и заборах.

Trait система

Trait - это модуль поведения, который вешается на NPC. Citizens поставляется с базовыми, остальные добавляют сторонние плагины:

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

gravity отключает гравитацию для летающих NPC. controllable позволяет игроку сесть на NPC и управлять им как лошадью, удобно для квестовых сцен. sleep укладывает NPC в кровать.

Полный список доступных traits:

/npc trait --list

Каждый trait хранит свои данные внутри NPC и сохраняется в saves.yml. Удалить trait:

/npc trait --remove gravity

Команды на клик

Самая полезная фича для серверов без Quests. Citizens умеет вешать на NPC список команд, которые запускаются при клике:

/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 запускает команду от имени игрока (нужны permissions у самого игрока). --op временно даёт оп-права на одну команду. --console запускает от консоли, что обычно и нужно для выдачи предметов или денег.

Дополнительные параметры:

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

cost берёт деньги через Vault, cooldown задаёт паузу между использованиями, sequential выполняет команды по очереди при каждом клике, а не все сразу.

Quests интеграция

Если нужны нормальные квесты с прогрессом, целями и наградами - не надо изобретать через /npc command. Есть готовые плагины поверх Citizens.

Quests от LMBishop (форк оригинального BlackVein) - самый популярный. Управление через GUI и yml-файлы, поддерживает квесты на убийство мобов, добычу блоков, доставку предметов, диалоги, ветвящиеся выборы. Привязка к NPC простая:

/quests editor

В редакторе указываешь NPC ID для giver и receiver, и игрок получает квест по клику.

BeautifulQuests - современный аналог с упором на красивый GUI. По функционалу похож, выбор обычно по вкусу.

Если нужны действительно сложные нелинейные сценарии - смотри в сторону Denizen.

Denizen: скриптинг для серьёзных сценариев

Denizen - это полноценный язык скриптинга для Bukkit, который интегрируется с Citizens через DenizenCitizens bridge. Синтаксис похож на YAML, но с переменными, условиями и тегами.

Простой пример скрипта диалога:

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 "Привет, <player.name>! Принеси мне 5 железа."
        - flag <player> waiting_iron
      chat trigger:
        1:
          trigger: /Спасибо/
          script:
          - chat "Не за что."

Плагин даёт контроль над всем что движется: NPC, мобы, события мира, экономика, инвентарь. Кривая обучения крутая, но один раз освоив, ты делаешь сценарии которые в обычных quest-плагинах нереальны: ветвящиеся диалоги с памятью, сложные кат-сцены, динамическое поведение торговцев в зависимости от времени суток.

Большие RP-серверы часто пишут весь свой контент на Denizen именно из-за этой гибкости.

Sentinel: боевые NPC

Citizens сам по себе пацифист. Если нужны охранники, рейд-боссы или мобы для PvE-арены - ставь Sentinel. Это addon от того же автора что и Citizens, написан под него и работает как trait.

Создание охранника:

/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 умеет драться мечом, луком, посохом, стрелять огненными шарами и бросать снежки. Поддерживает группы, чтобы охранники не били друг друга, и owner-систему: NPC не атакует своего создателя.

Параметры боя гибко настраиваются: дистанция атаки, урон, скорость, шанс крита, регенерация. На крупных серверах из Sentinel делают и охрану городов, и боссов в данжах.

Голограммы над NPC

Имя над головой - это базовый текст одной строкой. Если нужно несколько строк или иконки, ставь DecentHolograms или HolographicDisplays и привязывай к NPC.

DecentHolograms умеет линковаться с NPC напрямую:

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

Голограмма следует за NPC при движении и пропадает когда тот despawn. Это намного гибче встроенного имени и поддерживает PlaceholderAPI - можно показывать живые переменные.

Производительность

Один NPC потребляет немного: рендер пакета, изредка обновление позиции и трекеров игрока. На практике 100 неподвижных NPC на спавне идут без проблем даже на слабом VPS. Когда счёт переваливает за 500, начинаются нюансы.

Что грузит сервер:

• Pathfinding. NPC с патрулём или wander-режимом считают маршрут каждый тик. Если их много в одном чанке, это ощутимо.
• Sentinel боевые проверки. Каждый охранник сканирует радиус на цели. Сотня охранников с радиусом 16 это уже тысяча проверок entity в секунду.
• Голограммы и PAPI. Если над каждым NPC висит голограмма с %vault_eco_balance% обновляющаяся раз в секунду, ты дёргаешь экономику сотни раз в секунду.

Оптимизация:

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

В config.yml отключаешь look-close для статичных NPC если их много. У торговцев и квестодателей это допустимо, у декорационных лучше совсем выключить.

Хранение и бэкап

Все NPC живут в plugins/Citizens/saves.yml. Citizens сохраняет их по таймеру (save-task в config.yml, по умолчанию каждые 5 минут) и при graceful-shutdown. При краше сервера потеряются изменения с момента последнего автосохранения.

Простейший cron на бэкап:

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

Раз в два часа отдельная копия saves.yml с timestamp. Восстановление - просто скопировать файл обратно и перезапустить сервер. Никаких отдельных таблиц БД, всё в одном файле, что удобно при миграциях.

Если переезжаешь на новый сервер: переноси saves.yml, traits/ и config.yml. NPC поднимутся с теми же id, скинами и поведением.

FAQ

Citizens работает на Folia?

На момент весны 2026 - частично. Folia убирает традиционный главный поток и заменяет его регионами, что ломает большинство плагинов завязанных на синхронность. Citizens 2.0.36+ имеет экспериментальную поддержку Folia, но многие traits и addons (включая Sentinel) пока не работают. Если нужен NPC-плагин под Folia - смотри FancyNpcs или Adyeshach, они изначально пишутся под region-threading.

Как сделать NPC-торговца с экономикой?

Простейший путь - ShopKeepers с интеграцией Citizens. Ставишь оба плагина, привязываешь shop к NPC через /shopkeeper рядом с ним. ShopKeepers поддерживает Vault и работает с любой экономикой. Если нужно сложнее (динамические цены, налоги, скидки гильдиям) - DynamicShop или TradersListGUI плюс Citizens trait.

Можно ли заставить NPC двигаться по маршруту?

Да, через /npc path. Расставляешь точки ЛКМ, плагин запоминает путь, NPC циклически между ними ходит. Поддерживается рандомизация задержки на точке и режим one-shot. Для сложных маршрутов через двери и порталы лучше Denizen скрипт с walk-командами и waitfor-точками.

Citizens vs Sentinel: в чём разница?

Citizens - это база, движок NPC. Создаёт персонажа, вешает скин, скрипт на клик, маршрут. Sentinel - addon поверх Citizens, который добавляет одну вещь: бой. Сам Sentinel без Citizens не работает, это надстройка-trait. Если нужны квестодатели и торговцы - хватит Citizens. Нужны охранники, мобы, рейд-боссы - ставь оба.

Скины не загружаются, что делать?

Чаще всего проблема в кеше или Mojang API. Проверь подключение сервера к интернету, попробуй /npc skin <ник> --update. Если скин по ник-нейму не подтягивается, используй прямой URL текстуры через MineSkin. Иногда помогает удалить plugins/Citizens/skins.yml и дать плагину пересоздать кеш.

NPC двигается рывками или проваливается под землю

Симптом старой версии или конфликта с anti-cheat. Обнови Citizens до последнего билда. Если стоит NoCheatPlus или Matrix, добавь Citizens NPC в exemption-список через UUID или метку. Проваливание под землю обычно от того что NPC спавнится в незагруженном чанке: сделай keep-spawn-loaded: true в paper-world.yml для нужного мира.

Что дальше

Citizens сам по себе мощный инструмент, но раскрывается через интеграции. Минимальный стек для живого сервера: Citizens + DecentHolograms + Quests + ShopKeepers. Этого хватит на квестодателей, торговцев и декоративных NPC.

Если планируешь сложные RP-сценарии с диалогами и ветвлениями - изучай Denizen, в долгую он окупается. Для серверов с PvE-контентом не забудь про Sentinel и нормальный mob-плагин типа MythicMobs.

И главное - бэкапь saves.yml. NPC это часы работы билдера и сценариста, потерять их из-за одного крашa обидно.