HexVG-DatabaseAddon

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

https://github.com/VenomGrave/HexVG-DatabaseAddon

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.

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

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

%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

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 przez HexVG Team.
Błędy i propozycje: https://github.com/VenomGrave/HexVG-DatabaseAddon/issues

Fajne, chociaż ja osobiście czekam aż ktoś calkiem przepisze system zapisywania zmiennych, bo trzymanie wszystkiego w jednym miejscu bez specjalnej kontroli zapisu jest troche ew

Godzinę temu, Fendi napisał:

Fajne, chociaż ja osobiście czekam aż ktoś calkiem przepisze system zapisywania zmiennych, bo trzymanie wszystkiego w jednym miejscu bez specjalnej kontroli zapisu jest troche ew

Dzięki za opinię.

No właśnie dlatego ten plugin w ogóle powstał, bo domyślny system Skripta jest dość ograniczony jeśli chodzi o kontrolę nad danymi. Tutaj masz pełną kontrolę — własne tabele, własne zapytania, sam decydujesz kiedy i co zapisujesz.

Co do aktualizacji —  w najbliższym czasie wrzucimy nową wersję. Między innymi wchodzą transakcje, więc jeśli kilka zapytań musi wykonać się razem albo żadne, to plugin sam zadba o rollback gdy coś pójdzie nie tak.

Update v1.2.0

Spory update — cztery nowe rzeczy.

1. Transakcje

Możesz teraz wykonać kilka zapytań jako jedną atomową operację — albo wszystko się zapisze, albo nic. Jeśli cokolwiek się posypie w trakcie, plugin automatycznie cofa wszystko i ustawia flagę którą możesz sprawdzić w Skripcie.

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." to player
    stop

send "&aZakup udany!" to player

2. Blokowanie graczy

Zapobiega race conditions gdy gracz wywołuje komendę kilka razy zanim poprzednia się skończy. Locki trzymane są w pamięci pluginu — żadnych zmiennych Skriptowych.

if player is db locked:
    send "&cPoczekaj chwilę." to player
    stop
db lock player

# ... zapytania ...

db unlock player

3. db ensure table

Nowy efekt do tworzenia tabel który rozwiązuje problem z race conditions na starcie serwera. Blokuje wykonanie skryptu dopóki tabela faktycznie nie powstanie — nie trzeba już kombinować z wait ticks ani flagami.

# Nowe
on skript load:
    db ensure table "players" with query "CREATE TABLE IF NOT EXISTS players (...)"
# Stare
on skript load:
    check db table "players"
    wait 20 ticks
    if db table "players" doesn't exist:
        execute db query "CREATE TABLE IF NOT EXISTS players (...)"
        wait 5 ticks

4. PlaceholderAPI

Jeśli macie PlaceholderAPI na serwerze, plugin automatycznie rejestruje własne placeholdery. Ustawiacie wartość ze Skripta po zapytaniu i działa wszędzie — scoreboard, tablist, hologramy, cokolwiek obsługuje PAPI.

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

Od tej chwili %hexvgdb_coins% zwraca aktualną wartość dla gracza.

PlaceholderAPI jest opcjonalne — bez niego plugin działa dokładnie tak samo jak wcześniej.

W repozytorium są dwa przykładowe skrypty — example.sk z systemem coinów i nowy example_papi.sk pokazujący system statystyk z pełną integracją PlaceholderAPI.

Jak coś nie działa albo macie pomysły — piszcie w komentarzach albo otwórzcie Issue na GitHubie.