Vault — abstrakcyjne API ekonomii i uprawnień Minecraft

Czym jest Vault i czemu jest „obowiązkowy"

Vault to warstwa pośrednicząca. Definiuje interfejsy Economy, Permission, Chat i Group. Pluginy „dostarczające" implementują te interfejsy. Pluginy „konsumujące" używają ich, nie wiedząc, kto stoi po drugiej stronie.

• Plugin ekonomiczny (EssentialsXEco, CMI, TheNewEconomy) rejestruje się jako provider Vault Economy,
• Plugin uprawnień (LuckPerms) rejestruje się jako provider Vault Permission,
• Plugin sklepu (ChestShop, ShopGUI+) pyta Vault: „ile pieniędzy ma gracz X?",
• Vault przekazuje pytanie do aktualnego providera i zwraca odpowiedź.

Bez Vault'a każdy sklep musiałby implementować osobno integrację z każdym pluginem ekonomicznym — sprzeczność niemożliwa do utrzymania.

Instalacja i uruchomienie

1. Pobierz Vault z SpigotMC (jest też w Modrinth/Hangar pod nazwą VaultUnlocked, fork bardziej aktywny),
2. Wrzuć JAR do plugins/,
3. Zainstaluj plugin ekonomiczny (np. EssentialsX z modułem Eco lub CMI),
4. Restart serwera,
5. Sprawdź status: /vault-info.

Komenda /vault-info pokazuje, jaki provider obsługuje Economy, Permission, Chat. Brak providera = niektóre pluginy nie zadziałają.

Providery — kto naprawdę obsługuje co

Economy (jeden z poniższych):

• EssentialsXEco — najpopularniejszy, w zestawie z EssentialsX,
• CMI Economy — wbudowany w płatny CMI,
• TheNewEconomy — z funkcją multiwallet (waluty per świat),
• Treasury — bardziej nowoczesny system, kompatybilny przez most z Vault'em,
• iConomy — historyczny, dziś rzadko spotykany.

Permission & Chat:

• LuckPerms — standard branżowy, dostarcza Permission + Chat (prefiksy),
• PermissionsEx — legacy, do migracji,
• GroupManager — bardzo stary, nie zalecany.

Komendy Vault'a

/vault-info                          # status: providery, wersja
/vault-convert                       # konwersja waluty między providerami

Vault sam nie udostępnia komend graczom. /eco, /pay, /balance należą do plugin'u ekonomicznego (EssentialsXEco).

Konwersja między ekonomiami: /vault-convert przepisuje salda z jednego providera do drugiego. Idealne przy migracji z EssentialsXEco do CMI.

Pluginy korzystające z Vault'a (czyli „prawie wszystkie")

• EssentialsX — komendy /eco, /balance, /pay,
• ChestShop, QuickShop, ShopGUI+ — sklepy graczy,
• AuctionHouse, EasyAuctions — domy aukcyjne,
• EssentialsXChat — prefiksy z Vault Chat,
• EconomyShopGUI — sklep serwerowy,
• WorldGuard — opcjonalna integracja z Vault (kupowanie regionów),
• Jobs Reborn — wypłaty za pracę,
• VotingPlugin — nagrody pieniężne za głosowanie,
• PlaceholderAPI Vault expansion — placeholdery %vault_eco_balance%.

Problem dwóch providerów — typowa pułapka

Gdy zainstalujesz EssentialsXEco i CMI Economy jednocześnie, oba rejestrują się jako providery Vault Economy. Vault wybierze jednego (zwykle ten z wyższym priorytetem), drugi staje się bezczynny — ale pluginy mogą się myć.

Objaw: gracz ma /balance: 1000 w EssentialsX, ale w ChestShop ma 0. Albo wieczorem ma 1000, rano 500.

Rozwiązanie:

# config.yml Essentials
disable-eco: true     # gdy używasz CMI Economy

Albo odwrotnie — wyłącz CMI Economy w jego konfiguracji. Tylko jeden provider Economy na serwer.

VaultUnlocked — fork dla nowych Minecraftów

Oryginalny Vault jest utrzymywany sporadycznie. VaultUnlocked to fork z aktywnym rozwojem:

• kompatybilny w 100% z pluginami oczekującymi Vault'a (drop-in replacement),
• regularne aktualizacje pod nowe wersje Minecrafta,
• dodatkowe API dla nowoczesnych funkcji (multi-currency, BigDecimal balance),
• wsparcie dla Paper, Folia, Purpur.

Na nowych serwerach (2025+) lepiej instalować VaultUnlocked zamiast oryginału. Większość pluginów nie zauważy różnicy.

Treasury — nowoczesna alternatywa

Treasury to próba zbudowania czystego API ekonomii od zera, bez bagażu Vault'a:

• nowoczesne API z asynchronicznymi callbackami,
• natywne wsparcie dla wielu walut,
• BigDecimal zamiast double (precyzja przy dużych liczbach),
• most do Vault'a (Treasury udostępnia Economy provider dla Vault'a).

Praktyka: instaluj Treasury + VaultUnlocked jednocześnie. Treasury obsługuje nowoczesne pluginy, Vault zostaje dla starszych — wszystko widzi tę samą walutę.

Vault w kodzie pluginu — mini przykład

Jeśli piszesz własny plugin, integracja z Vault zajmuje kilkanaście linii:

private Economy economy;

@Override
public void onEnable() {
    if (getServer().getPluginManager().getPlugin("Vault") == null) {
        getLogger().severe("Vault nie znaleziony!");
        getServer().getPluginManager().disablePlugin(this);
        return;
    }
    RegisteredServiceProvider<Economy> rsp = getServer()
        .getServicesManager().getRegistration(Economy.class);
    if (rsp == null) return;
    economy = rsp.getProvider();
}

public boolean charge(Player player, double amount) {
    if (economy.getBalance(player) < amount) return false;
    economy.withdrawPlayer(player, amount);
    return true;
}

Wszystkie ekonomiczne operacje przechodzą przez to samo API — bez wiedzy, czy działa EssentialsXEco czy CMI.

Diagnostyka problemów

• „No Vault economy provider found" — zainstaluj plugin ekonomiczny i restartuj,
• Balance pokazuje 0 wszędzie — sprawdź /vault-info, czy provider jest aktywny,
• Dwa różne salda w różnych pluginach — masz dwa providery (patrz wyżej),
• Prefiksy nie działają — sprawdź, czy LuckPerms rejestruje się jako Chat provider,
• Aktualizacja Minecrafta zepsuła Vault'a — rozważ VaultUnlocked.

Najczęstsze pułapki

• Brak Vault'a na liście pluginów — zapomnienie podstawowej zależności, połowa pluginów milcząco nie działa,
• Konflikt z multi-server economy — Vault nie synchronizuje między serwerami; potrzebujesz shared MySQL ekonomii,
• Aktualizacja Vault'a bez aktualizacji providera — w pewnym momencie zerwane API powoduje błędy w logu,
• Reload na żywo — Vault nie reaguje dobrze na /reload, providery mogą się rozjechać. Zawsze restart.

Podsumowanie

Vault to fundament, którego nie widać, ale którego brak zauważasz natychmiast. Zainstaluj go (najlepiej VaultUnlocked w 2026 r.), wybierz jeden plugin ekonomiczny, połącz z LuckPerms i masz działającą warstwę pieniędzy oraz uprawnień dla każdego innego pluginu.

Pamiętaj o trzech zasadach: tylko jeden Economy provider, regularna weryfikacja przez /vault-info, restart zamiast reloadu. Jeśli to się trzyma, Vault będzie dla Ciebie niewidoczny przez cały czas życia serwera — i o to chodzi w dobrym API.