CreepiaBridge — Dokumentacja Pluginu

CreepiaBridge to lekka wtyczka Minecraft łącząca serwer z platformą Creepia. Odbiera zakupy ze sklepu przez Redis i wykonuje komendy w grze — bez wpływu na TPS serwera.

Architektura

Creepia Cloud → Redis Queue → CreepiaBridge → Bukkit dispatchCommand
                                    ↓
                              ACK → Redis → Backend

Kluczowe elementy:

• Redis BLPOP listener — dedykowany wątek daemon nasłuchujący na kolejce, zero zużycia CPU w idle
• JedisPool — pula połączeń dla krótkotrwałych operacji (heartbeat, ACK)
• Deduplicator — in-memory cache (max 10k wpisów) zapobiegający podwójnemu wykonaniu
• PendingDeliveryStore — plik YAML z dostawami dla graczy offline, periodic flush co 60s
• HMAC-SHA256 — każda wiadomość jest podpisana, niepodpisane są odrzucane

Komendy

Wszystkie komendy wymagają uprawnienia creepia.admin (domyślnie: OP).

Mechanizm dostawy

Gracz online

Gdy zakup dotyczy gracza, który jest online:

1. Komenda jest walidowana (HMAC + blocklista)
2. Placeholdery są zamieniane ({player}, {uuid})
3. Komenda jest wykonywana na main thread przez dispatchCommand
4. ACK SUCCESS jest wysyłany do backendu

Gracz offline

Gdy gracz jest offline:

1. Dostawa jest zapisywana do pamięci (i okresowo na dysk)
2. ACK QUEUED jest wysyłany do backendu
3. Gdy gracz dołączy — po opóźnieniu join-delay-ticks — plugin próbuje dostarczyć

Mechanizm retry

Retry następuje wyłącznie przy kolejnym dołączeniu gracza do serwera. Nie ma żadnego timera ani cyklicznego sprawdzania.

Scenariusz:

1. Gracz dołącza → plugin próbuje dostarczyć
2. Gracz rozłącza się zanim komenda się wykona → retry_count rośnie o 1
3. Gracz dołącza ponownie → kolejna próba
4. Po max-retries nieudanych prób → dostawa jest usuwana z ACK FAILED

Administrator może wymusić ponowną próbę komendą /creepia retry — sprawdzi dostawy dla wszystkich graczy aktualnie online.

Staggered delivery

Gdy gracz ma wiele oczekujących dostaw, są one wykonywane z małym opóźnieniem między sobą (1-3.5s), żeby nie przeciążyć serwera jednoczesnym wykonaniem wielu komend.

Placeholdery

Komendy wysyłane z platformy mogą zawierać:

Przykład: give {player} diamond 64 → give Steve diamond 64

Komendy wewnętrzne

Platforma może wysyłać specjalne komendy (prefix _CREEPIA_):

Heartbeat

Co 60 sekund plugin wysyła do Redis status serwera:

• Liczba graczy online / max
• Wersja serwera i pluginu
• TTL klucza: 90s (jeśli heartbeat nie przyjdzie przez 90s, backend uznaje serwer za offline)

Konfiguracja

Ustawienia administratora

security:
  blocked-commands:
    - "op"
    - "deop"
    - "stop"
    # ... dodaj własne

Komendy z tej listy nigdy nie zostaną wykonane, nawet jeśli platforma je wyśle. Plugin rozpoznaje prefiksy namespace (minecraft:op → op).

logging:
  verbose: false              # true = loguj wszystko (debug)
  suppress-repeated-errors: true  # ukryj powtarzające się błędy Redis

Ustawienia dostawy

delivery:
  join-delay-ticks: 60        # 3s opóźnienia po join (20 ticks = 1s)
  max-retries: 5              # po 5 nieudanych joinach → FAILED
  pending-max-size: 500       # max oczekujących dostaw
  pending-max-age-days: 30    # auto-usuwanie po 30 dniach
  deduplication-hours: 48     # okno deduplikacji transakcji
  save-interval-seconds: 60   # flush na dysk co 60s

Ustawienia techniczne

secret-key: "..."             # HMAC key — ustawiany przez /creepia auth
env: "prod"                   # local/test/prod — określa adres Redis
queue: "UNREGISTERED"         # kolejka Redis — NIE EDYTUJ

reconnect:
  initial-delay: 5            # początkowy backoff (sekundy)
  max-delay: 300              # max backoff (5 minut)
  multiplier: 2.0             # 5s → 10s → 20s → ... → 300s

redis:
  pool-size: 4                # połączenia w puli (bez BLPOP listenera)

Wymagania

• Minecraft 1.13+ (Spigot, Paper, Purpur, Folia*)
• Java 8+
• Dostęp do portów wychodzących (Redis, port 6379)

*Folia: plugin używa runTask/runTaskAsynchronously — wymaga adaptera dla Folia scheduler.

Wpływ na wydajność