Citizens: NPC i postaci questowe na serwerze Minecraft

Citizens zamienia serwer w zamieszkany swiat. Bez niego NPC na serwerze albo w ogole nie ma, albo sa zrobione na chama z niewidzialnych zombie. Przejdziemy przez instalacje, konfiguracje i integracje z Quests czy Denizen, zeby na koncu mieli prawdziwych kupcow, straznikow i questgiverow.

Czym jest Citizens i dlaczego akurat ten plugin

Citizens to open-source plugin rozwijany od 2011 roku, i po 14 latach stal sie standardem branzowym dla NPC na Spigot i Paper. Out of the box tworzy statycznych i poruszajacych sie postaci, nadaje im skiny, ekwipunek, hologramy z imionami i reakcje na klikniecie. Sam questow ani sklepow nie robi, ale jego API to fundament, na ktorym dzialaja dziesiatki innych pluginow.

Alternatywy istnieja: ZNPCsPlus, FancyNpcs, Adyeshach. Sa nowsze, lzejsze i czasem szybsze na duzych serwerach, ale prawie zaden popularny plugin do questow nie gada z nimi bezposrednio. Jezeli chcesz Quests, BeautifulQuests, Sentinela, Denizena, ShopKeepers albo setki innych - wszystkie chca Citizens. W wiekszosci przypadkow wybor jest oczywisty.

W praktyce Citizens trzyma NPC na serwerach od malych prywatnych RP po duze sieci minigier. Plugin ma aktywny rozwoj, regularne wydania pod nowe wersje Minecrafta i Discord do bug-reportow.

Instalacja na Paper lub Spigot

Pobierz najnowszy .jar z oficjalnej strony albo z Spigot resources. Linia 2.0.x dziala na Paper i Spigot 1.20.x oraz 1.21.x. Dla 1.16-1.19 bierzesz starsze buildy z dev-channel.

.jar do plugins/, restart serwera. Po starcie pojawi sie:

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

saves.yml to twoje NPC. Backupuj plik razem ze swiatem. Jak sie uszkodzi, wszystkie NPC znikaja, a odtwarzanie recznie to zaden fun. Mi raz przepadlo 40 NPC przez crash w trakcie zapisu, od tamtej pory mam osobna kopie saves.yml co dwie godziny.

Jezeli piszesz wlasny plugin z integracja Citizens, dodaj CitizensAPI jako zaleznosc compileOnly i wpisz softdepend: [Citizens] w plugin.yml.

Tworzenie pierwszego NPC

Bazowa komenda:

/npc create Quester

NPC pojawia sie na twojej pozycji z automatycznie nadanym ID. Domyslnie uzywa twojego skina. Zmiana:

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

Mozesz podac dowolny aktywny nick Mojang, Citizens pobierze teksture. Dla pelnej kontroli uzyj MineSkin, wygeneruj tam wlasny skin, skopiuj URL i wklej go po --url. Skiny sa cache'owane lokalnie, zeby nie walic w API przy kazdym respawnie.

Bazowe komendy edycji

Najpierw zaznaczasz NPC: stan obok i kliknij LPM, albo uzyj /npc sel <id>. Wszystko ponizej dziala na zaznaczonym.

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

/npc equip otwiera GUI, do ktorego wkladasz zbroje i przedmiot do reki. /npc move teleportuje NPC do ciebie. /npc lookat kaze mu obracac sie do najblizszego gracza. /npc rename obsluguje legacy & i na nowych wersjach tagi MiniMessage, jezeli wlaczone w config.yml.

Przydatne dodatki:

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

/npc copy klonuje NPC ze wszystkimi traitami, co oszczedza czas przy szeregu identycznych straznikow.

Zachowanie: patrol, follow, wander

Citizens ma w pakiecie trzy tryby ruchu. Dodaje sie je przez /npc behavior albo odpowiedni trait:

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

/npc path otwiera edytor sciezki. Dosadnie ustawiasz waypointy klikajac LPM w bloki, potem zapisujesz. NPC chodzi w petli. Niepotrzebne dla kupca, idealne dla patrolujacego straznika albo animacji wioski.

/npc wander to losowe wedrowanie w promieniu:

/npc wander --range 10 --delay 100

/npc follow przyczepia NPC do gracza. Przydatne do towarzyszy fabularnych w scenariuszach RP.

Jezeli standardowy pathfinder jest za glupi, zainstaluj Citizens-Pathfinder albo uzyj Sentinela z madrzejsza nawigacja. Domyslny czasem zacina sie na schodach i plotach.

System traitow

Trait to modul zachowania doczepiany do NPC. Citizens ma wbudowane trzon traitow, kolejne dochodza od pluginow trzecich:

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

gravity przelacza grawitacje dla latajacych NPC. controllable pozwala graczowi siasc i sterowac NPC jak koniem, dobre do cutscenek. sleep kladzie NPC do lozka.

Lista wszystkich dostepnych traitow:

/npc trait --list

Kazdy trait trzyma swoje dane w NPC i zapisuje sie w saves.yml. Usuniecie:

/npc trait --remove gravity

Komendy przy klikaniu

Najprzydatniejsza funkcja na serwerach bez plugina questowego. Citizens dolacza do NPC liste komend, ktore odpalaja sie przy klikniciu:

/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 odpala komende z poziomu gracza (musi miec realne permission). --op daje jednorazowe OP na te komende. --console odpala z konsoli, co zwykle jest tym co chcesz przy wydawaniu itemow lub pieniedzy.

Dodatkowe opcje:

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

cost sciaga kase przez Vault, cooldown dodaje pauze per-gracz, sequential wykonuje komendy po kolei przy kolejnych klikach, nie wszystkie na raz.

Integracja z Quests

Jezeli chcesz prawdziwe questy z postepem, celami i nagrodami, nie kombinuj przez /npc command. Sa gotowe pluginy nad Citizens.

Quests od LMBishopa (fork oryginalnego BlackVein) to najpopularniejszy wybor. Edytor GUI plus pliki yml, obsluguje questy na zabicia mobow, wydobycie blokow, dostawy, dialogi, rozgalezione wybory. Podpiecie do NPC jest proste:

/quests editor

W edytorze podajesz NPC ID dla giver i receiver, gracz odbiera questa klikajac.

BeautifulQuests to nowoczesna alternatywa skupiona na ladnym GUI. Funkcjonalnie podobny, wybor zwykle to kwestia gustu.

Do naprawde skomplikowanych nieliniowych scenariuszy patrz na Denizena.

Denizen: skrypty do powaznych scenariuszy

Denizen to pelny jezyk skryptowy dla Bukkita, ktory laczy sie z Citizens przez DenizenCitizens bridge. Skladnia wyglada jak YAML, ale ze zmiennymi, warunkami i tagami.

Prosty skrypt dialogu:

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 "Czesc <player.name>! Przynies mi 5 zelaza."
        - flag <player> waiting_iron
      chat trigger:
        1:
          trigger: /Dzieki/
          script:
          - chat "Nie ma za co."

Plugin daje kontrole praktycznie nad wszystkim: NPC, moby, world-eventy, ekonomia, ekwipunki. Krzywa nauki jest stroma, ale jak juz zalapiesz, robisz scenariusze niemozliwe w zwyklych plugin questowych: rozgalezione dialogi z pamiecia, zlozone cutscenki, kupcy ktorych zachowanie zalezy od pory dnia.

Duze serwery RP czesto pisza caly swoj content w Denizenie wlasnie ze wzgledu na te elastycznosc.

Sentinel: bojowi NPC

Citizens domyslnie jest pacyfista. Do straznikow, raid-bossow czy mobow na arene PvE instalujesz Sentinela. To addon tego samego autora, dzialajacy jako trait.

Zrobienie straznika:

/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 umie machac mieczem, strzelac z luku, rzucac kulami ognia i sniezkami. Ma grupy, zeby straznicy nie atakowali sie nawzajem, i system owner: NPC nie zaatakuje swojego tworcy.

Parametry walki sa konfigurowalne: zasieg ataku, obrazenia, predkosc, szansa na cios krytyczny, regen. Na duzych serwerach Sentinel robi i straz miejska, i bossow w lochach.

Hologramy nad NPC

Imie nad glowa to jednoliniowy hologram. Dla wielu linii albo ikon zainstaluj DecentHolograms lub HolographicDisplays i podepnij do NPC.

DecentHolograms laczy sie bezposrednio:

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

Hologram podaza za NPC w ruchu i znika przy despawnie. Duzo bardziej elastyczny od wbudowanego imienia, obsluguje PlaceholderAPI, mozesz pokazywac live zmienne.

Wydajnosc

Pojedynczy NPC kosztuje malo: pakiety renderu, sporadyczne update'y pozycji, trackery graczy. W praktyce 100 statycznych NPC na spawnie idzie bez problemu nawet na slabym VPS. Powyzej 500 zaczynaja sie niuanse.

Co obciaza serwer:

• Pathfinding. NPC z patrolem albo wander licza sciezke co tick. Duzo ich w jednym chunku to widac.
• Skanowanie celow Sentinela. Kazdy straznik skanuje promien w poszukiwaniu celow. 100 straznikow z promieniem 16 to tysiac sprawdzen entity na sekunde.
• Hologramy z PAPI. Jezeli nad kazdym NPC wisi hologram z %vault_eco_balance% odswiezany raz na sekunde, stukasz ekonomia setki razy na sekunde.

Tuning:

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

W config.yml wylacz look-close dla statycznych NPC, jak ich duzo. U kupcow i questgiverow okej, u dekoracyjnych obowiazkowo.

Przechowywanie i backup

Wszystkie NPC zyja w plugins/Citizens/saves.yml. Citizens zapisuje po timerze (save-task w config.yml, domyslnie co 5 minut) i przy graceful-shutdown. Crash zostawia tylko stan z ostatniego autozapisu.

Prosty cron na backup:

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

Co dwie godziny osobna kopia z timestampem. Recovery: skopiuj plik z powrotem, restart. Zadnych tabel DB, wszystko w jednym pliku, co ulatwia migracje.

Przy przeprowadzce na nowy host bierzesz saves.yml, traits/ i config.yml. NPC wracaja z tymi samymi ID, skinami i zachowaniami.

FAQ

Czy Citizens dziala na Folii?

Stan na wiosne 2026 - czesciowo. Folia odrzuca tradycyjny main thread i zastepuje go regionami, co psuje wiekszosc pluginow opartych na single-thread sync. Citizens 2.0.36+ ma eksperymentalny support Folii, ale wiele traitow i addonow (w tym Sentinel) jeszcze nie dziala. Jak konkretnie potrzebujesz plugin NPC pod Folie, patrz na FancyNpcs lub Adyeshach, oba pisane od poczatku pod region threading.

Jak zrobic NPC kupca z ekonomia?

Najprostsza droga to ShopKeepers z integracja Citizens. Instalujesz oba, podpinasz shop do NPC przez /shopkeeper stojac obok. ShopKeepers obsluguje Vault i dziala z dowolnym pluginem ekonomicznym. Dla zaawansowanych przypadkow (dynamiczne ceny, podatki, znizki dla gildii) DynamicShop lub TradersListGUI plus trait Citizens.

Czy moge zmusic NPC do chodzenia po trasie?

Tak, przez /npc path. Stawiasz waypointy LPM, plugin zapamietuje sciezke, NPC chodzi w petli. Jest randomizowany delay na waypoincie i tryb one-shot. Do skomplikowanych tras przez drzwi i portale lepszy jest skrypt Denizena z komendami walk i waitfor.

Citizens vs Sentinel: jaka roznica?

Citizens to baza, silnik NPC. Tworzy postac, naklada skin, podpina skrypty na klik, rysuje sciezke. Sentinel to addon nad Citizens dodajacy jedna rzecz: walke. Sentinel nie dziala bez Citizens, to rozszerzenie-trait. Dla questgiverow i kupcow wystarczy sam Citizens. Potrzebujesz straznikow, mobow, raid-bossow? Instalujesz oba.

Skiny sie nie laduja, co robic?

Najczesciej to problem z cache lub Mojang API. Sprawdz internet serwera, sprobuj /npc skin <nick> --update. Jezeli lookup po nicku nie dziala, uzyj bezposredniego URL tekstury przez MineSkin. Czasem pomaga usuniecie plugins/Citizens/skins.yml i pozwolenie pluginowi odbudowac cache.

NPC porusza sie szarpnieciami albo wpada pod ziemie

Symptom przestarzalej wersji albo konfliktu z anti-cheatem. Zaktualizuj Citizens do najnowszego buildu. Jak masz NoCheatPlus albo Matrix, wciagnij NPC Citizens na liste exempt po UUID albo tagu. Wpadanie pod ziemie zwykle dlatego, ze NPC zespawnowal w niezaladowanym chunku, ustaw keep-spawn-loaded: true w paper-world.yml dla tego swiata.

Co dalej

Citizens sam w sobie jest mocny, ale rozwija sie przez integracje. Minimalny stack na zywy serwer: Citizens + DecentHolograms + Quests + ShopKeepers. To pokrywa questgiverow, kupcow i NPC dekoracyjnych.

Jezeli planujesz zlozone scenariusze RP z dialogami, nauka Denizena oplaca sie dlugofalowo. Na serwerach skupionych na PvE nie zapominaj o Sentinelu i porzadnym pluginie do mobow w stylu MythicMobs.

I backupuj saves.yml. NPC to godziny pracy buildera i scenarzysty, stracic ich przez jeden crash boli.