Plugin Minecraft

Zainstaluj i skonfiguruj plugin, który automatycznie wydaje zakupy na Twoim serwerze.

Plugin łączy serwer gry ze sklepem i wykonuje komendy opłaconych zamówień — bez Twojego udziału. Łączy się sam, szyfrowanym połączeniem wychodzącym, więc nie otwierasz żadnego portu. Gdy serwer był offline, zaległe dostawy są nadrabiane po ponownym połączeniu.

​

Wymagania

• Java 17 lub nowsza,
• Paper/Spigot 1.19+, Folia, BungeeCord albo Velocity 3.x,
• serwer dodany w panelu (zobacz Serwery),
• prawo zapisu w folderze plugins/ItemShop/ (konfiguracja i dziennik realizacji).

​

Zainstaluj plugin

1. Pobierz plugin

   W sekcji Plugin w panelu pobierz uniwersalny plik JAR i umieść go w folderze plugins/. Nie instaluj jednocześnie kilku wariantów pluginu.

2. Wygeneruj klucz i konfigurację

   Wybierz serwer i kliknij Wygeneruj klucz pluginu, a potem skopiuj lub pobierz gotowy config.yml. Klucz jest widoczny tylko raz — jeśli go zgubisz, wygeneruj nowy.

3. Wgraj konfigurację

   Zapisz plik jako plugins/ItemShop/config.yml i uruchom serwer.

4. Sprawdź połączenie

   Komenda /itemshop pokazuje stan połączenia. W panelu serwer powinien zmienić się na online.

Wygeneruj klucz przed skopiowaniem pliku. Plik bez klucza zawiera WKLEJ_TUTAJ_KLUCZ w miejscu klucza i nie zadziała.

Jedna konfiguracja dotyczy jednego serwera. Masz kilka serwerów — wygeneruj osobny config.yml dla każdego. Po zmianach serwerów w panelu wygeneruj plik ponownie.

​

Konfiguracja

Generator wypełnia wszystko za Ciebie. Przykładowy plik:

config.yml

apiUrl: "https://itemshop.dev"
apiKey: "isk_..."
serverId: "..."
joinDeliveryDelaySeconds: 2
blockedCommands:
  - op
  - deop
  - stop
  - restart
  - reload
  - whitelist
blockedServers:
  - auth
  - login
playersUpdateIntervalSeconds: 30
sendPlayerNames: true
debug: false

Pole	Znaczenie
apiUrl	adres ItemShop — bez /api/v2 i bez ścieżki; w produkcji zawsze https://
apiKey	klucz pluginu (zaczyna się od isk_)
serverId	identyfikator jednego serwera z panelu
joinDeliveryDelaySeconds	opóźnienie dostawy po wejściu gracza na serwer
blockedCommands	komendy, których plugin nigdy nie wykona, nawet jeśli są w produkcie
blockedServers	tryby za proxy, na których dostawa czeka (np. lobby logowania)
playersUpdateIntervalSeconds	jak często plugin wysyła liczbę graczy online
sendPlayerNames	czy wysyłać też listę nicków (liczba graczy jest wysyłana zawsze)
debug	szczegółowe logi — włączaj tylko na czas diagnozy

Zmiany w pliku wczytasz komendą /itemshop reload. Nie używaj globalnego /reload serwera — może zostawić plugin w niespójnym stanie.

​

Bezpieczeństwo

• Klucz pluginu działa tylko w zakresie realizacji zamówień Twojego sklepu, ale traktuj go jak hasło: nie publikuj config.yml, nie wrzucaj go do repozytorium ani zgłoszeń pomocy.
• Jeśli klucz mógł wyciec, wygeneruj nowy, a stary usuń w kluczach API (zobacz Klucze API).
• Nie usuwaj pliku fulfillment-journal.json w folderze pluginu — bez niego nie da się bezpiecznie rozstrzygnąć dostawy przerwanej awarią.

​

Jak przebiega dostawa

Opłacone zamówienie trafia do pluginu od razu. Jeśli kilka instancji jest połączonych, komendy wykona tylko jedna. Przed pierwszą komendą plugin zapisuje stan na dysku, więc po awarii wie, na czym skończył:

• jeśli wszystkie komendy się wykonały, plugin po restarcie tylko potwierdza realizację — nie powtarza komend,
• jeśli serwer padł w trakcie wykonywania komend, wynik jest niepewny. Zamówienie trafia wtedy do ręcznej weryfikacji, a Ty decydujesz: zrealizowane albo ponów (zobacz Zamówienia).

To celowy wybór: lepiej poprosić Cię o decyzję niż ryzykować podwójne wydanie produktu. Szczegóły techniczne opisuje protokół pluginu.

​

Przetestuj przed sprzedażą

1. Utwórz produkt z niegroźną komendą testową, np. say Test {PLAYER}.
2. Kup go z kodem rabatowym 100% — nie angażujesz wtedy operatora płatności.
3. Sprawdź /itemshop, log serwera i zmianę statusu: opłacone → przetwarzanie → zrealizowane.
4. Powtórz z graczem offline, po wejściu gracza i po restarcie serwera przed dostawą.
5. Osobno przetestuj prawdziwego operatora w trybie testowym (zobacz Płatności).

​

Diagnostyka

Plugin zgłasza brak konfiguracji

Sprawdź dokładne nazwy pól: apiUrl, apiKey, serverId. Klucz musi zaczynać się od isk_, a apiUrl nie może kończyć się na /api/v2.

Połączenie jest odrzucane (unauthorized)

Wygeneruj nowy klucz w sekcji Plugin. Klucz musi być aktywny i należeć do tego samego sklepu co serverId.

Zamówienie czeka na gracza

Sprawdź pisownię nicku, przełącznik Wymagaj gracza online i listę blockedServers. Wejście gracza lub zmiana trybu uruchamia dostawę zaległości po joinDeliveryDelaySeconds.

Zamówienie wymaga ręcznej weryfikacji

Plugin wykrył przerwaną dostawę — część komend mogła się wykonać. Najpierw sprawdź stan gracza i logi serwera, potem wybierz w panelu zrealizowane albo ponów.

Serwer jest offline w panelu

Plugin nie wysłał sygnału od ponad 5 minut. Sprawdź /itemshop, log serwera i czy serwer ma dostęp do internetu. Zamówienia poczekają do ponownego połączenia.

​

Dalej

Serwery

Funkcje serwera i status online.

Protokół pluginu

Techniczny opis komunikacji pluginu ze sklepem.