Dokumentacja Pluginu wStaffPin
Spis Treści

1. Wstęp
2. Wymagania
3. Konfiguracja
4. Komendy
5. Funkcjonalności i Ograniczenia
   
6. Logika PINu i Liczenie Prób
   
7. Obsługa Zdarzeń
   
8. Dalsze Rozszerzenia i Modyfikacje
   
9. FAQ

Wstęp
wStaffPin to plugin na platformę Spigot, którego celem jest zwiększenie bezpieczeństwa kont administracyjnych poprzez dodanie warstwy autoryzacji PIN-em. Plugin działa w sposób zbliżony do popularnego AuthMe Reloaded – ogranicza możliwość wykonywania większości akcji do momentu podania poprawnego PIN-u. Funkcjonalność ta jest stosowana tylko przez graczy, którzy sami ustawią dla siebie PIN.

Wymagania

• Serwer Minecraft: Wersje od 1.8.8 do 1.21.5.
  
  
• Środowisko Java: JDK 1.8 lub wyższe.
  
  
• Platforma: Spigot lub pochodne (np. Paper).

Instalacja

1. Pobranie: Pobierz plugin z oficjalnej strony na spigotmc.org
   
   
2. Folder Plugins: Skopiuj pobrany plik JAR do folderu plugins na Twoim serwerze.
   
   
3. Restart/Reload Serwera: Uruchom ponownie serwer lub wykonaj reload, aby plugin został załadowany.
   
   
4. Konfiguracja: Po pierwszym uruchomieniu w folderze pluginu pojawią się pliki konfiguracyjne, które możesz edytować (np. config.yml).

Konfiguracja
Plik config.yml
Plik config.yml pozwala na pełną personalizację działania pluginu. Znajdziesz w nim sekcje dotyczące:

• Komunikatów: Wszystkie komunikaty (informujące o błędach, użyciu, ograniczeniach) są pobierane z tej sekcji. Przykłady:
  • messages.title – tytuł wyświetlany graczowi.
    
    
  • messages.wrong-pin – komunikat przy błędnym PIN-ie, gdzie używane są placeholdery <attempts> oraz <max> (np. "1/3").
    
    
  • messages.no-move, messages.no-chat itp. – komunikaty przy próbie wykonania zablokowanych akcji.
• List Komend:
  • allowed-commands – lista dozwolonych komend, które gracz może wpisać zanim zaloguje się.
    
    
  • commands.on-join, commands.on-login, commands.on-wrong, commands.on-max – listy komend wykonywanych odpowiednio przy dołączeniu, poprawnym logowaniu, błędnych próbach i po osiągnięciu limitu.
• Ustawienia:
  • attempts – maksymalna liczba prób wpisania PIN-u.
    
    
  • kick-delay – czas (w sekundach) po którym gracz zostanie wyrzucony, jeśli nie zaloguje się.
    
    
  • blindness – ustawienia efektu ślepoty (interval oraz duration).

Przykładowa zawartość pliku config.yml znajduje się poniżej:

# Komunikaty główne
messages:
title: "&d&lPIN DLA ADMINISTRACJI"
subtitle: "&8» &cWpisz swój PIN!&a /pin <kod>"
actionbar: "&d&lPIN DLA ADMINISTRACJI &8» &cWpisz swój PIN!&a /pin <kod>"
wrong-pin: "&czły PIN próba <attempts>/<max>"
correct-pin: "&aPIN poprawny. Dziękujemy."
usage-set: "&cUżyj: /pincreate <pin>"
usage-login: "&cUżyj: /pin <pin>"
no-permission: "&cNie masz permisji!"
only-player: "&cTylko gracz może wykonać tę komendę!"
kick-message: "Nie podałeś poprawnego PINu."
set-pin-success: "&aPIN został ustawiony. Przy następnym logowaniu musisz użyć PINu."

# Komunikaty dla zablokowanych akcji
no-move: "&cNie możesz się poruszać, dopóki się nie zalogujesz!"
no-command: "&cNie możesz używać komend, dopóki nie wpiszesz PINu!"
no-chat: "&cNie możesz pisać na czacie, dopóki się nie zalogujesz!"
no-inventory: "&cNie możesz korzystać z ekwipunku, dopóki się nie zalogujesz!"
no-drop: "&cNie możesz wyrzucać przedmiotów, dopóki się nie zalogujesz!"
no-pickup: "&cNie możesz podnosić przedmiotów, dopóki się nie zalogujesz!"
no-interact: "&cNie możesz wchodzić w interakcje, dopóki się nie zalogujesz!"

# Lista dozwolonych komend dla niezalogowanych graczy
allowed-commands:
- "/pin"
- "/pincreate"

# Komendy wykonywane przez plugin (można użyć %player% jako placeholder)
commands:
on-join:
- "say %player% dołączył do serwera."
on-login:
- "say %player% zalogował się."
on-wrong:
- "say %player% podał błędny PIN."
on-max:
- "banip %player% Nie masz już prób!"

# Ustawienia prób i timeout
attempts: 3
kick-delay: 60

# Ustawienia efektu Blindness (dla zasłonięcia widoku nieautoryzowanym graczom)
blindness:
interval: 40 # co ile ticków (domyślnie co 2 sekundy)
duration: 40 # czas trwania efektu (domyślnie 2 sekundy)

Komendy
/pincreate

• Opis:
  Komenda służy do ustawienia osobistego PIN-u. Może jej użyć tylko gracz posiadający odpowiednią permisję (wpin.use).
  
  
• Składnia:
  /pincreate <pin>
  
  
• Działanie:
  Po wpisaniu komendy, PIN jest zapisywany dla gracza, a licznik prób ustawiany na 0. Gracz otrzymuje komunikat potwierdzający ustawienie PIN-u. Przy następnym logowaniu na serwer zabezpieczenia zostaną aktywowane.

/pin

• Opis:
  Komenda służy do logowania się za pomocą wcześniej ustawionego PIN-u.
  
  
• Składnia:
  /pin <pin>
  
  
• Działanie:
  Po wpisaniu komendy plugin porównuje wpisany PIN z zapisanym.
  • PIN poprawny: Gracz uzyskuje dostęp, wykonywane są komendy skonfigurowane dla logowania (np. on-login), a licznik prób resetowany.
    
    
  • PIN niepoprawny: Wyświetlany jest komunikat z aktualną liczbą prób w formacie <aktualna próba>/<maksymalna liczba prób>. Dodatkowo wykonywane są komendy określone dla błędnych prób (on-wrong), a w przypadku przekroczenia limitu – także komendy z on-max.

Funkcjonalności i Ograniczenia
Plugin wStaffPin wprowadza zabezpieczenia podobne do AuthMe Reloaded, blokując dla niezalogowanych graczy następujące działania:

• Ruch:
  Całkowite zablokowanie przemieszczania się postacią. Gracz nie może zmienić pozycji – jeśli spróbuje, zostanie odesłany do miejsca, w którym się pojawił, a komunikat zostanie wyświetlony.
  
  
• Komendy:
  Poza listą dozwolonych komend (allowed-commands), wszystkie inne polecenia są blokowane. Użytkownik otrzymuje komunikat o niedozwolonej akcji.
  
  
• Czat:
  Wysyłanie wiadomości na czacie jest zablokowane.
  
  
• Ekwipunek:
  Gracz nie ma dostępu do ekwipunku – blokowane są zarówno klikanie w ekwipunek, jak i operacje typu podnoszenie czy wyrzucanie przedmiotów.
  
  
• Interakcje:
  Wszelkie interakcje z otoczeniem (otwieranie drzwi, naciskanie przycisków itp.) są zablokowane.
  
  
• Efekt Blindness:
  Plugin automatycznie nakłada efekt ślepoty, uniemożliwiając graczowi widzenie świata do momentu podania poprawnego PIN-u.

Logika PINu i Liczenie Prób

• Ustawianie PIN-u:
  Wykonywane przez komendę /pincreate. Po ustawieniu PIN-u dla danej sesji, gracz musi się nim zalogować przy następnym dołączeniu do serwera.
  
  
• Liczenie prób:
  Każda nieudana próba logowania zwiększa licznik prób. Komunikat o błędnym PIN-ie wyświetla się w formacie x/y, gdzie x to aktualna liczba prób, a y to maksymalny limit prób ustawiony w konfiguracji.
  
  
• Resetowanie Licznika:
  Po poprawnym wpisaniu PIN-u licznik jest resetowany do 0.
  
  
• Komendy na Błędne Próby:
  Plugin wykonuje komendy zdefiniowane w konfiguracji w zależności od sytuacji:
  • on-wrong: Komendy wykonywane przy każdej nieudanej próbie.
    
    
  • on-max: Komendy wykonywane w momencie przekroczenia maksymalnej liczby prób.

Obsługa Zdarzeń
Plugin wykorzystuje szereg eventów Spigot API, aby zablokować akcje gracza do czasu poprawnej weryfikacji PIN-u. Główne zdarzenia to:

• PlayerJoinEvent:
  Resetuje stan logowania, zapisuje pozycję gracza, uruchamia timer wyrzucenia po określonym czasie oraz wykonuje komendy z on-join.
  
  
• PlayerMoveEvent:
  Zapobiega poruszaniu się gracza – każda próba zmiany pozycji jest anulowana, a gracz otrzymuje komunikat (np. no-move).
  
  
• PlayerCommandPreprocessEvent:
  Przechwytuje wszystkie komendy poza dozwolonymi (zdefiniowanymi w allowed-commands) i blokuje ich wykonanie.
  
  
• AsyncPlayerChatEvent:
  Blokuje wysyłanie wiadomości na czacie.
  
  
• InventoryClickEvent, PlayerDropItemEvent, PlayerPickupItemEvent:
  Blokuje operacje związane z ekwipunkiem oraz przedmiotami.
  
  
• PlayerInteractEvent:
  Blokuje interakcje gracza z otoczeniem (np. otwieranie drzwi, naciskanie przycisków).

Dalsze Rozszerzenia i Modyfikacje
Plugin został napisany w sposób umożliwiający łatwe rozszerzanie funkcjonalności. Oto kilka pomysłów na rozwinięcie:

• Zapisywanie PIN-ów między restartami:
  Dodanie obsługi zapisu do pliku lub bazy danych.
  
  
• Integracja z systemem MySQL:
  Aby przechowywać dane o logowaniu oraz próbach w bazie danych.
  
  
• Większe możliwości konfiguracji:
  Dodanie kolejnych opcji konfiguracyjnych, np. możliwość personalizacji efektu Blindness.
  
  
• Dodatkowe blokady:
  Blokowanie innych interakcji, takich jak otwieranie skrzyń czy używanie przedmiotów z określonych slotów.

FAQ
1. Czy plugin dotyczy tylko użytkowników z PIN-em?
Tak, ograniczenia dotyczą jedynie graczy, którzy ustawili dla siebie PIN przy użyciu komendy /pincreate.

2. Czy mogę zmienić komunikaty i komendy wykonywane przez plugin?
Tak – wszystkie wiadomości, komendy oraz ustawienia są konfigurowalne w pliku config.yml.

3. Co się stanie po przekroczeniu maksymalnej liczby prób?
Plugin wykona komendy z listy commands.on-max, które domyślnie wykonują polecenie banowania IP gracza.

4. Jak mogę wyłączyć efekt Blindness?
Możesz zmienić lub wyłączyć efekt, modyfikując odpowiednie wartości w sekcji blindness pliku config.yml.