Jak zainstalować i połączyć plugin voxelshop

Co robi plugin voxelshop?

Plugin voxelshop łączy itemshop z serwerem Minecraft. Pobiera opłacone zamówienia i wykonuje przypisane do produktów komendy z uprawnieniami konsoli serwera. Dzięki temu sklep może zlecać wydawanie zakupów bez ręcznego wpisywania każdej komendy przez administratora.

Najkrótsza ścieżka instalacji: dodaj serwer w sklepie, wybierz go w zakładce Plugin, pobierz skonfigurowany plik .jar, umieść go w folderze plugins i uruchom ponownie serwer. Następnie sprawdź status połączenia w panelu.

Pobrany dla Twojego serwera JAR zawiera klucz sekretny API sklepu. Traktuj go jak hasło. Nie przesyłaj go graczom ani nie dodawaj do publicznej paczki serwera. Klucz pozwala odczytywać zamówienia i oznaczać ich realizację.

Zanim zaczniesz: silnik serwera i wersja pluginu

Ta instrukcja dotyczy pluginu Bukkit przeznaczonego do serwerów Java Edition korzystających z Paper, Spigot lub Bukkit. Nie jest instrukcją instalacji moda na Fabric lub Forge ani dodatku do Bedrock Dedicated Server. Plugin instalujesz na serwerze gry, na którym mają wykonywać się komendy produktów.

Nie przyjmuj, że każda wersja Minecraft będzie zgodna tylko dlatego, że panel pozwala ją wybrać. Zgodność zależy także od wydania pluginu, silnika i Javy. Przed zmianą serwera używanego przez graczy sprawdź tę samą kombinację na kopii testowej i zachowaj kopię plików.

Stan na 10 września 2026: publiczne pobieranie voxelshop udostępnia plugin 0.2.0, a endpoint wersji wskazuje go również jako minimum. Wersja 0.2.0 korzysta z API v2. Starszych plików 0.1.x nie traktuj jako zamiennika aktualnego wydania.

Nie zakładaj też zgodności z Javą 8: obecny plik używa funkcji plikowych dostępnych od Javy 11. To nie jest pełna deklaracja wymagań serwera. Wersję Javy dobierz przede wszystkim do używanego wydania Paper lub Spigot.

Przygotuj dostęp do panelu voxelshop, plików serwera i jego konsoli. Serwer musi móc wykonywać wychodzące połączenia HTTPS do voxelshop.pl. Do tego połączenia nie trzeba uruchamiać RCON ani otwierać dodatkowego portu przychodzącego.

1. Wybierz właściwy serwer w panelu

Otwórz swój sklep w panelu voxelshop i przejdź do zakładki Plugin. Na stronie „Plugin na serwer” wybierz odpowiednią pozycję w polu Serwer. Jeżeli sklep nie ma jeszcze serwera, użyj przycisku Dodaj serwer i wróć do pobierania.

Przy kilku trybach gry sprawdź nazwę przed pobraniem. Przykładowo plik przygotowany dla Survivalu powinien trafić na serwer Survival, na którym są pluginy obsługujące komendy jego produktów. Dla kolejnego serwera pobierz osobny plik po zmianie wyboru.

2. Pobierz plugin z konfiguracją

Kliknij Pobierz plugin. Panel przygotowuje archiwum JAR z trzema wartościami: identyfikatorem sklepu, kluczem sekretnym API i identyfikatorem wybranego serwera. Przy pierwszej instalacji nie musisz ich wpisywać ręcznie.

Przycisk Plugin bez konfiguracji pobiera inną wersję tego samego pliku: bez uzupełnionych danych sklepu i serwera. Wybierz go tylko wtedy, gdy zamierzasz skonfigurować połączenie samodzielnie.

3. Wgraj JAR i uruchom serwer

1. Zatrzymaj serwer w panelu hostingu.
2. Otwórz główny folder serwera przez menedżer plików lub SFTP.
3. Wgraj pobrany .jar bezpośrednio do folderu plugins. Nie rozpakowuj go i nie wkładaj do mods.
4. Jeśli aktualizujesz plugin, zastąp stary JAR. W folderze powinna zostać jedna wersja pluginu voxelshop.
5. Uruchom serwer i sprawdź konsolę.

Taki sposób umieszczenia pliku i restartu opisuje również oficjalna instrukcja instalacji pluginów Paper. W konsoli wpisz plugins, a w grze, mając odpowiednie uprawnienia, /plugins. Plugin powinien być włączony. Czerwona pozycja lub błąd ładowania wymagają sprawdzenia logs/latest.log.

Przy ponownej instalacji sprawdź istniejący plugins/voxelshop/config.yml. Samo podmienienie JAR-a nie zastępuje automatycznie zapisanej konfiguracji. Jeżeli przenosisz połączenie do innego serwera lub sklepu, zatrzymaj serwer i popraw wartości w tym pliku. Nie kasuj całego folderu pluginu: może zawierać dane oczekujących potwierdzeń realizacji zamówień.

4. Ręczna konfiguracja, jeśli jest potrzebna

Po pierwszym uruchomieniu plugin zapisuje domyślny plik plugins/voxelshop/config.yml. Jeśli pobrałeś wariant bez konfiguracji, zatrzymaj serwer i uzupełnij go:

storeId: "ID_TWOJEGO_SKLEPU"
secret: "TWOJ_KLUCZ_SEKRETNY_API"
serverId: "ID_WYBRANEGO_SERWERA"

To przykład z opisami pól, nie gotowe dane do połączenia. W sekcji Ręczna konfiguracja panel pokazuje ID sklepu i pozwala skopiować Klucz sekretny API. ID serwera znajdziesz w adresie jego strony zarządzania, w części po /server/. Nie wpisuj tu nazwy trybu gry, adresu IP ani portu Minecraft.

Wklej sam klucz do secret, bez dopisywania Bearer. Nagłówek autoryzacji przygotowuje plugin. Zachowaj nazwy pól i cudzysłowy, zapisz plik, a następnie ponownie uruchom serwer.

5. Sprawdź połączenie z itemshopem

Wróć do strony Plugin i wybierz serwer, który właśnie uruchomiłeś. Panel automatycznie odświeża dane i może pokazać:

Nie oczekuj zmiany natychmiast po kliknięciu startu. Serwer musi załadować plugin, wysłać zapytanie, a panel odświeżyć dane.

Online potwierdza kontakt z API. Nie potwierdza poprawności komend produktu ani nadania rangi graczowi. Po połączeniu osobno sprawdź działanie komendy w konsoli na koncie testowym. Przed udostępnieniem produktu graczom zweryfikuj również cały proces płatności i dostarczenia w odpowiednim środowisku testowym.

Plugin nie łączy się: krótka diagnostyka

Jeśli status jest Online, ale gracz nie dostał zakupu, sprawdź stan zamówienia i wynik komend. Nie ponawiaj nadawania nagrody w ciemno: część komend mogła już zostać wykonana.

Otwórz panel voxelshop, wybierz swój sklep i połącz właściwy serwer w zakładce Plugin.