HexVG-DatabaseAddon

Addon do Skripta obsługujący operacje bazodanowe na serwerze VenomGrave

---

O projekcie

HexVG-DatabaseAddon to addon do Skripta stworzony na potrzeby serwera VenomGrave. Sporo pracy poszło w to żeby asynchroniczność działała porządnie — w pewnym momencie musieliśmy przepisać cały system zapytań żeby pozbyć się deadlocków które freezowały serwer.

Plugin pozwala pisać skrypty które komunikują się z MySQL lub SQLite bez żadnej znajomości Javy. Połączenie, pula połączeń HikariCP, obsługa błędów, rollbacki transakcji, blokowanie graczy i tworzenie tabel — to wszystko jest po stronie pluginu. W Skripcie piszesz tylko co chcesz zrobić z danymi.

---

Funkcje

• Obsługa MySQL i SQLite
• W pełni asynchroniczne zapytania — serwer nigdy nie freezuje
• Transakcje z automatycznym rollbackiem przy błędzie
• System blokowania graczy — zapobiega race conditions przy duplikatach komend
• Gwarantowane tworzenie tabel — db ensure table blokuje dopóki tabela nie istnieje, bez race conditions na starcie
• Integracja z PlaceholderAPI — wartości z bazy dostępne w scoreboardach, tablistach, hologramach
• Ochrona przed SQL injection przez PreparedStatement
• Walidacja nazw tabel i kolumn
• Cache wyników per gracz
• Tryb debug z logowaniem zapytań i czasem wykonania
• Wszystkie biblioteki spakowane w jarze — brak dodatkowych zależności

---

Wymagania

Wymaganie	Wersja
Paper	1.16.5+
Skript	2.6+
Java	11+
PlaceholderAPI	opcjonalne

---

Instalacja

1. Wrzuć HexVG-DatabaseAddon.jar do folderu plugins/
2. Uruchom serwer — plugin wygeneruje config.yml
3. Skonfiguruj połączenie z bazą danych
4. Zrestartuj serwer

Przy MySQL pamiętaj żeby wcześniej ręcznie utworzyć bazę: CREATE DATABASE nazwa_bazy;

---

Konfiguracja

debug: false

database:
  type: SQLITE   # SQLITE lub MYSQL

  sqlite:
    file: database.db

  mysql:
    host: localhost
    port: 3306
    database: nazwa_bazy
    username: root
    password: ""
    pool-size: 5

---

Składnia Skript

Tworzenie tabeli (zalecane)

Blokuje dopóki tabela nie powstanie — bezpieczne w on skript load, bez wait ticks, bez race conditions nawet gdy kilku graczy dołączy jednocześnie.

on skript load:
    db ensure table "players" with query "CREATE TABLE IF NOT EXISTS players (uuid VARCHAR(36) PRIMARY KEY, name VARCHAR(16), coins INT DEFAULT 0)"

Pobieranie danych

execute db query "SELECT * FROM players WHERE uuid = ?" with values {_uuid}
wait 2 ticks
set {_coins} to column "coins" from row 1 of last db query result
set {_rows} to db row count of last db query result

Dodawanie rekordu

set {_cols::1} to "uuid"
set {_cols::2} to "coins"
set {_vals::1} to {_uuid}
set {_vals::2} to "0"
db insert into table "players" columns {_cols::*} values {_vals::*}

Aktualizacja i usuwanie

db update table "players" set "coins" to "%{_new}%" where "uuid" = {_uuid}
db delete from table "players" where "uuid" = {_uuid}

Transakcje

Kilka zapytań jako jedna atomowa operacja — albo wszystko się zapisuje, albo nic.

db begin transaction

db update table "players" set "coins" to "%{_new}%" where "uuid" = {_uuid}
wait 2 ticks
db insert into table "purchases" columns {_cols::*} values {_vals::*}
wait 2 ticks

db commit transaction

if last db transaction failed:
    send "&cCoś poszło nie tak. Coiny nie zostały pobrane." to player
    stop

send "&aZakup zakończony sukcesem!" to player

db begin transaction i db commit transaction nie wymagają wait — blokują wewnętrznie do czasu zakończenia operacji.

Blokowanie gracza

Zapobiega wielokrotnemu wywołaniu komendy zanim poprzednie wykonanie się skończy.

if player is db locked:
    send "&cPoczekaj chwilę przed ponownym użyciem tej komendy." to player
    stop
db lock player

# ... zapytania ...

db unlock player

PlaceholderAPI

Jeśli PlaceholderAPI jest zainstalowane, ekspansja rejestruje się automatycznie. Ustaw wartość ze Skripta po zapytaniu i działa wszędzie gdzie PAPI jest obsługiwane.

execute db query "SELECT coins FROM players WHERE uuid = ?" with values {_uuid}
wait 2 ticks
set {_coins} to column "coins" from row 1 of last db query result
db set placeholder "coins" to "%{_coins}%" for player

Placeholder	Opis
%hexvgdb_<klucz>%	wartość ustawiona przez db set placeholder
%hexvgdb_connected%	true / false — status połączenia z bazą
%hexvgdb_locked%	true / false — czy gracz ma aktywny lock

---

Ważne — wait ticks

Zwykłe zapytania są asynchroniczne, więc przed odczytaniem wyniku daj wait 2 ticks.

db ensure table, db begin transaction i db commit transaction nie wymagają wait — blokują wewnętrznie.

---

Komendy

Komenda	Opis	Uprawnienie
/hexvgdb status	Status połączenia z bazą	hexvg.database.admin
/hexvgdb debug	Włącza / wyłącza tryb debug	hexvg.database.admin
/hexvgdb reload	Przeładowuje konfigurację	hexvg.database.admin

Domyślnie dostępne tylko dla operatorów.

---

Przykładowe skrypty

W repozytorium znajdują się dwa przykłady:

• example.sk — system coinów z SELECT, INSERT, UPDATE, DELETE, transakcjami i lockami
• example_papi.sk — system statystyk (coiny, kills, rank) z pełną integracją PlaceholderAPI

---

Autorzy

Stworzony dla serwera VenomGrave przez HexVG Team.
Błędy i propozycje: https://github.com/VenomGrave/HexVG-DatabaseAddon/issues