Vault Plugin Minecraft: ekonomia i uprawnienia, most API (2026)

Każdy, kto kiedyś instalował EssentialsX, ChestShop, mcMMO, Jobs lub praktycznie dowolny plugin ekonomii, widział Vault na liście zależności. Od razu pytanie: czym jest ten magiczny jar, dlaczego dziesiątki pluginów go wymagają i co się stanie bez niego. Krótka odpowiedź: Vault to most API. Sam nic nie robi, ale bez niego pluginy nie potrafią rozmawiać z ekonomią ani systemem uprawnień.

W tym materiale wszystko po kolei: jak działa Vault wewnątrz, czym są service providers, jak go zainstalować, którzy dostawcy ekonomii i uprawnień są aktywni w 2026, jak złapać błąd "no compatible economy plugin found", kiedy przejść na fork VaultUnlocked i kiedy Vault wcale nie jest potrzebny.

Vault to API, a nie funkcjonalność

Najważniejsze nieporozumienie: ludzie myślą, że Vault sam prowadzi ekonomię, daje uprawnienia, zarządza czatem. Nieprawda.

Vault to warstwa abstrakcji. Gdy ChestShop chce poznać saldo gracza, nie dzwoni bezpośrednio do EssentialsX. Dzwoni do Vault: "daj mi saldo gracza X". Vault deleguje zapytanie do pluginu, który zarejestrował się jako Economy Provider. Może to być EssentialsX Eco, CMI, TNE, GemsEconomy, BeastTokens.

Po co taka warstwa? Żeby jeden plugin sklepu działał na dowolnej ekonomii bez znajomości jej wnętrza. Twórca ChestShop pisze raz przeciw API Vault, admin wybiera backend.

Tak samo z uprawnieniami. mcMMO chce sprawdzić czy gracz ma mcmmo.skills.mining. Pyta Vault, Vault pyta zarejestrowany Permission Provider (LuckPerms, GroupManager, PermissionsEx itd.), dostaje true lub false.

Vault udostępnia trzy API:

• Economy (net.milkbowl.vault.economy.Economy)
• Permission (net.milkbowl.vault.permission.Permission)
• Chat (net.milkbowl.vault.chat.Chat)

Bez zarejestrowanego dostawcy API istnieje, ale zwraca atrapę. Dlatego błąd "no compatible economy plugin found" oznacza: Vault stoi, ale nikt nie zarejestrował się jako dostawca ekonomii.

Jak działa mechanizm Service Provider

Bukkit/Paper ma wbudowaną klasę ServicesManager. To rejestr usług: każdy plugin może zarejestrować implementację interfejsu, każdy inny może o nią poprosić.

Pod maską wygląda to tak. EssentialsX przy starcie:

Bukkit.getServicesManager().register(
    Economy.class,
    new EssentialsEconomy(),
    essentialsPlugin,
    ServicePriority.Normal
);

ChestShop przy starcie:

RegisteredServiceProvider<Economy> rsp =
    Bukkit.getServicesManager().getRegistration(Economy.class);
if (rsp == null) {
    log.severe("No compatible economy plugin found!");
    return;
}
Economy econ = rsp.getProvider();

Vault sam nie rejestruje się jako implementacja w tym schemacie. Definiuje tylko interfejsy i zapewnia kompatybilność między wersjami. Dlatego "Hooked into Vault" w logu znaczy: plugin znalazł klasy Vault w classpath i może rozmawiać z dostawcą.

Jeśli kolejność ładowania pluginów jest zła (plugin ekonomii startuje później niż sklep), rejestracja przyjdzie z opóźnieniem. Vault rozwiązuje to przez leniwy lookup: sklep nie powinien zapamiętywać referencji Economy w onEnable, lepiej pobierać ją przy pierwszym zapytaniu.

Instalacja Vault

Najkrótszy rozdział. Vault to jeden jar.

1. Wejdź na github.com/MilkBowl/Vault/releases i ściągnij najnowszą stabilną (w 2026 to gałąź 1.7.x).
2. Wrzuć Vault.jar do plugins/.
3. Restart serwera. Nie /reload, to psuje rejestrację serwisów.

Weryfikacja:

/plugins

Na liście pojawi się Vault na zielono. Dalej /vault-info pokaże dostawców:

/vault-info

Zdrowy serwer:

Vault v1.7.3-SNAPSHOT Information
Economy: EssentialsX Economy [Enabled]
Permissions: LuckPerms [Enabled]
Chat: LuckPerms-Chat [Enabled]

Jeśli przy Economy widać (Disabled) lub none, żaden plugin się nie zarejestrował. Idź do sekcji o błędach.

Dostawcy ekonomii

Vault nie przechowuje sald. Robi to dostawca. W 2026 na Paper 1.21+ wybór wygląda tak.

EssentialsX Economy

Najpopularniejszy wariant. Część EssentialsX. Pobierasz pełny pakiet: EssentialsX.jar, EssentialsXChat.jar, plus osobno Geo, AntiBuild itp. Moduł ekonomii siedzi w głównym EssentialsX.jar.

Konfiguracja w plugins/Essentials/config.yml:

currency-symbol: '$'
starting-balance: 100.0
max-money: 10000000000000
min-money: -10000

Po starcie /bal pokazuje saldo, /pay przelewa, /eco administruje. Vault podchwytuje rejestrację automatycznie.

CMI Economy

CMI to płatny all-in-one (zastępuje EssentialsX, AdminFun, dużo więcej). Ma własną ekonomię.

W plugins/CMI/config.yml:

Economy:
  Enabled: true
  StartingMoney: 100.0
  Currency:
    Format: '$ {amount}'

CMI rejestruje się w Vault z priorytetem Normal. Jeśli równolegle stoi EssentialsX Eco, wybucha konflikt: oba się rejestrują, wygrywa pierwszy załadowany. Rozwiązanie: wyłączyć ekonomię w jednym z pluginów lub pobawić się ServicePriority w configu.

TheNewEconomy (TNE)

TheNewEconomy to samodzielny plugin ekonomii bez naleciałości. Multi-waluta (kilka walut na jednym serwerze), banki, oprocentowanie, ustawienia regionalne.

Core:
  Currency:
    Default:
      Major_Name: Dollar
      Major_Plural: Dollars
      Symbol: '$'
      Decimal_Places: 2

TNE świetne na serwerach z wieloma walutami (np. waluta główna + tokeny za głosowanie).

GemsEconomy

GemsEconomy też multi-waluta, prościej niż TNE w funkcjach, ale wygodniej w administracji. Zapis w MySQL, działa stabilnie w sieci BungeeCord/Velocity.

Kompatybilność ekonomii z Vault

Dostawca	Vault	VaultUnlocked	Multi-waluta	Magazyn
EssentialsX Eco	tak	tak	nie	YAML
CMI Economy	tak	tak	nie	SQLite/MySQL
TheNewEconomy	tak	tak	tak	MySQL/H2
GemsEconomy	tak	tak	tak	MySQL
BeastTokens	tak	przez adapter	tak (tokeny)	MySQL
iConomy	porzucone	nie	nie	YAML

Wniosek: na typowy SMP bierz EssentialsX Eco, na złożony RPG/PvP patrz w stronę TNE lub GemsEconomy.

Dostawcy uprawnień

Z uprawnieniami w 2026 jest jeden realny wybór, LuckPerms. Reszta jest martwa lub legacy.

LuckPerms

LuckPerms królem. Standardowa instalacja, LuckPerms-Bukkit-5.x.x.jar do plugins/, gotowe. Vault widzi automatycznie zarówno dostawcę uprawnień, jak i czatu (dla prefiksów/sufiksów).

Sprawdzenie:

/vault-info

Powinno pokazać:

Permissions: LuckPerms [Enabled]
Chat: LuckPerms-Chat [Enabled]

LuckPerms natywnie implementuje Vault API. Bez dodatkowej konfiguracji.

GroupManager

GroupManager szedł ze starym EssentialsX, w nowych wersjach został wycięty. Jeśli z jakiegoś powodu siedzisz na 1.8 z GroupManagerem: dawno nieutrzymywany, a hooki ekonomii Vault działają krzywo.

PermissionsEx (PEX)

Martwy projekt. Nie używaj, ma krytyczne bugi z gubieniem uprawnień. Jeśli masz serwer na PEX, migracja do LuckPerms przez /lp import pex.

Bukkit superperms

Jeśli plugin uprawnień nie stoi w ogóle, Vault spada do standardowych Bukkit superperms. Uprawnienia wczytują się z permissions.yml i operacyjnie działają tylko /op. Dla poważnego serwera bezużyteczne.

Porównanie dostawców uprawnień

Dostawca	Utrzymanie	Vault	Konteksty	Werdykt
LuckPerms	aktywne	tak	tak	bierz
GroupManager	martwy	tak	nie	omijaj
PermissionsEx	martwy	tak	częściowo	migruj
Bukkit superperms	bazowe	atrapa	nie	omijaj

Dostawcy czatu

Vault Chat API to o prefiksach, sufiksach i wyświetlaniu grup. EssentialsXChat lub Carbon ciągnie prefiks z dostawcy czatu.

W 99% przypadków dostawcą czatu jest ten sam LuckPerms, bo implementuje równolegle interfejs Permission i Chat. Nic dodatkowego nie trzeba: zainstalowałeś LuckPerms, dostawca czatu się pojawił.

Z GroupManagerem (po co?) też się rejestruje jako Chat. CMI ma własny moduł czatu i rejestruje się jako Chat gdy Chat.Vault jest włączone.

Weryfikacja przez /vault-info i /papi parse

Najszybsza droga upewnić się, że Vault widzi wszystko:

/vault-info

albo krócej:

/vault

Trzy linie: Economy, Permissions, Chat, każda z nazwą dostawcy i statusem.

Można też przez PlaceholderAPI. PAPI plus rozszerzenie vault (/papi ecloud download Vault):

/papi parse <player_name> %vault_eco_balance%
/papi parse <player_name> %vault_eco_balance_formatted%
/papi parse <player_name> %vault_prefix%
/papi parse <player_name> %vault_suffix%
/papi parse <player_name> %vault_group%

Jeśli placeholdery zwracają pusty string lub nieprzetworzony tekst, Vault nie podchwycił dostawcy. Jeśli zwracają liczbę albo prefiks, działa.

Programowe sprawdzenie z configu pluginu (np. Citizens, Quests):

hooks:
  vault: true

Po restarcie plugin powinien zalogować "Hooked into Vault" lub podobnie.

Typowy błąd: no compatible economy plugin found

Najczęstsze zgłoszenie do supportu. W logu:

[ChestShop] No compatible economy plugin found!
[Jobs] Vault dependency found, but no economy plugin registered.
[mcMMO] Could not find Vault economy hook.

Przyczyny i kolejność diagnozy.

1. Vault nie zainstalowany

/plugins

Jeśli Vault nie świeci na zielono, ściągnij jar i wrzuć do plugins/.

2. Vault zainstalowany, brak dostawcy ekonomii

/vault-info

Jeżeli Economy: None lub Disabled. Postaw EssentialsX, CMI lub TNE. Jednego z nich.

3. Dostawca jest, ale moduł ekonomii wyłączony

Częste przy CMI. W plugins/CMI/config.yml:

Economy:
  Enabled: false

Ustaw true, restart.

Przy EssentialsX rzadziej: moduł ekonomii fizycznie brakuje. Pobierz pełny EssentialsX z essentialsx.net (nie tylko Chat).

4. Konflikt dwóch dostawców

/vault-info pokazuje jednego dostawcę, ale pluginy mówią, że saldo się nie zmienia. Możliwe: jeden plugin pisze do EssentialsX Eco, drugi czyta CMI Eco. Dwa różne salda. Rozwiązanie: zostaw jednego dostawcę, drugiemu wyłącz rejestrację.

5. Stary Vault

Vault sprzed 1.7 nie zna nowoczesnych zmian API Paper 1.21+. Zaktualizuj do 1.7.3+.

6. Konflikt z proxy

W sieci Velocity plugin ekonomii stoi na każdym backendzie osobno. Jeśli jest tylko na jednym, pozostałe piszą "no economy". Vault nie propaguje rejestracji przez proxy: każdy serwer ma własny zestaw pluginów.

VaultUnlocked: fork pod nowoczesne potrzeby

Oryginalny Vault rozwija się od 2011 i czasem zostaje w tyle: brak natywnego wsparcia multi-waluty, brak BigDecimal dla wielkich liczb, brak operacji asynchronicznych. Dlatego powstał fork VaultUnlocked.

VaultUnlocked daje:

• Multi-walutę na poziomie API
• BigDecimal zamiast double dla precyzji
• Async balance lookup
• Wstecznie zgodny z klasycznym Vault API (pluginy pisane pod Vault dalej działają)

Instalacja identyczna: jeden jar w plugins/. Tylko nie obu na raz, albo Vault, albo VaultUnlocked.

# Zamiana
rm plugins/Vault.jar
cp ~/downloads/VaultUnlocked.jar plugins/

Po restarcie sprawdź:

/vault-info

VaultUnlocked pokaże to samo plus zaznaczy, którzy dostawcy używają rozszerzonego API. EssentialsX, CMI, LuckPerms działają z VaultUnlocked bez modyfikacji.

Kiedy przejść:

• Serwer ma multi-walutę (dolary + tokeny + kryształy)
• Używasz TNE lub GemsEconomy i chcesz wycisnąć async
• Piszesz własne pluginy i potrzebujesz BigDecimal

Kiedy nie przechodzić: wszystko działa na klasycznym Vault, nie ruszaj.

Kiedy Vault nie jest potrzebny

Nie każdy serwer wymaga Vault. Przypadki, w których można go pominąć:

• Serwer PvP bez ekonomii i bez złożonych grup. Bez sklepów, bez EssentialsX Eco, uprawnienia opem + bazowy LuckPerms, nikt nie woła Vault.
• Survival z jednym pluginem sklepu który ma wbudowaną ekonomię. QuickShop potrafi działać bez Vault gdy stoi TNE lub Treasury.
• Minigry pod BungeeCord/Velocity. Bedwars/Skywars zwykle korzystają z własnej waluty przez pluginy coinów, bez Vault.
• Serwer czysto techniczny. Test, build server, kreatywka gdzie wszyscy mają opa.

Aktualny trend to Treasury, alternatywny most API obchodzący ograniczenia Vault. Jeśli wszystkie twoje pluginy wspierają i Vault, i Treasury, można żyć bez Vault. W realiach 2026 90% popularnych pluginów dalej hookuje się konkretnie do Vault.

Migracja ze starych pluginów na nowoczesny stack

Jeśli stawiasz serwer od zera w 2026, bazowy stack:

plugins/
  Vault.jar             # lub VaultUnlocked.jar
  LuckPerms-Bukkit.jar
  EssentialsX.jar
  EssentialsXChat.jar
  PlaceholderAPI.jar

Wystarczy na:

• Ekonomię (/bal, /pay, /eco)
• Uprawnienia przez LuckPerms (/lp, edytor webowy)
• Prefiksy/sufiksy w czacie
• Cokolwiek innego co wymaga Vault

Migracja ze starego serwera: backup, Vault do 1.7.x, EssentialsX do najnowszego (min. 2.20+), LuckPerms do 5.5+, restart, sprawdzenie /vault-info. Salda i grupy przeżyją, jeśli magazyn pluginów się nie zmieniał.

Dostrojenie priorytetów

Rzadko ale: dwa dostawcy ekonomii, trzeba wybrać głównego. Zajrzyj do configu głównego pluginu. EssentialsX Essentials/config.yml:

update-bed-at-daytime: true
# Priorytet rejestracji w Vault nie jest konfigurowalny wprost,
# steruje nim kolejność ładowania pluginów

Realny workaround: zmienić nazwę jara pluginu, żeby ładował się wcześniej lub później. Kolejność alfabetyczna. AAA-EssentialsX.jar załaduje się przed CMI.jar. Hack, działa.

Cywilizowana droga: jeden dostawca ekonomii na serwer. Dwie równoległe ekonomie prawie zawsze oznaczają zapomniany plugin albo błąd konfiguracji.

FAQ

Czy Vault sam tworzy pieniądze albo uprawnienia?

Nie. Vault to most API. Definiuje interfejsy Economy, Permission, Chat i daje opakowanie ServicesManager. Pieniądze trzyma dostawca (EssentialsX, CMI, TNE), uprawnienia trzyma LuckPerms.

Co się stanie jeśli postawię Vault i żadnego dostawcy?

Vault się załaduje, pluginy zależne też się załadują, ale przy zapytaniu o saldo lub uprawnienie dostaną null. W logach pojawi się "no compatible economy plugin found" lub podobnie.

Można używać Vault i VaultUnlocked razem?

Nie. Dwa jary z tymi samymi pakietami i klasami. Serwer albo się nie załaduje, albo będzie działał nieprzewidywalnie. Wybierz jednego.

LuckPerms i GroupManager równocześnie?

Bukkit technicznie pozwala, nie rób tego. Konfliktują, walczą o rejestrację, uprawnienia się gubią. Migracja z GroupManager do LuckPerms: /lp import groupmanager, usuń GroupManager.

Czy potrzebuję Vault na proxy Velocity?

Pluginy proxy (na samym Velocity) zwykle nie używają Vault. Vault to API Bukkita. Na backendach za proxy tak. Każdy ma swojego.

Dlaczego ChestShop pisze "no economy" mimo że stoi EssentialsX?

Sprawdź w /vault-info że Economy nie jest None. Jeśli None: moduł ekonomii EssentialsX wyłączony albo nie załadowany, zajrzyj do Essentials/server.log. Jeśli zielony, restart serwera: ChestShop mógł zacachować null podczas ładowania.

Zamknięcie

Vault to infrastruktura. Postawiłeś raz i zapomniałeś. Trudności zaczynają się gdy wybór ekonomii lub uprawnień odbywa się bez zrozumienia, który dostawca rejestruje co. Reguła: jeden dostawca na każde API, po starcie wszystkie trzy linie powinny być zielone, a każdy "no compatible plugin" rozwiązuje się w trzydzieści sekund przez /vault-info.

Jeśli serwer już oberwa atak, a ty równolegle próbujesz konfigurować stack pluginów, postaw sprawdzoną ochronę DDoS od MineGuard i spokojnie zajmij się konfiguracją. Sortowanie Vault i dostawców idzie znacznie przyjemniej, gdy ruch nie pada.