Skript - tworzenie pluginów bez Javy

Co to jest Skript

Skript to plugin dla serwerów opartych na Bukkit/Spigot/Paper, który dostarcza własny język skryptowy do rozszerzania funkcjonalności serwera. Projekt powstał w 2011 roku, a od 2016 roku jest rozwijany przez społeczność pod nazwą SkriptLang. Kod źródłowy jest dostępny na GitHubie.

Zwykłe pisanie pluginów wymaga znajomości Javy, konfiguracji środowiska Maven/Gradle, kompilacji, wgrania pliku .jar i restartu serwera. Ze Skriptem wystarczy otworzyć plik tekstowy z rozszerzeniem .sk, wpisać kilka linii kodu, wpisać /skript reload nazwaPliku i gotowe - nowa mechanika działa na żywo, bez restartu.

Skrypt Skriptu wygląda niemal jak angielskie zdania. Zamiast pisać złożone metody Javy, piszesz: "on join: send 'Witaj!' to player". To sprawia, że Skript jest jednym z najlepszych narzędzi dla adminów, którzy chcą tworzyć unikalne doświadczenia na swoim serwerze bez wielomiesięcznej nauki programowania.

Na Skript działa ogromna liczba serwerów - od małych serwerów dla przyjaciół po duże sieci z tysiącami graczy. Możesz nim zbudować systemy ekonomii, areny PvP z kolejkowaniem, questy, własne GUI, systemy rang, bounty i dziesiątki innych mechanik. Skript nie zastąpi każdego pluginu, ale dla własnych, unikalnych systemów to pierwsze narzędzie, po które powinien sięgnąć każdy admin.

Składnia Skript

Skrypt Skriptu zbudowany jest z czterech podstawowych elementów:

• Zdarzenia (Events) - co wyzwala wykonanie kodu. Przykład: on join, on break, on chat
• Warunki (Conditions) - sprawdzają, czy coś jest prawdą. Przykład: if player has permission "vip"
• Efekty (Effects) - wykonują akcję. Przykład: send "Wiadomość" to player, give player 1 of diamond
• Wyrażenia (Expressions) - zwracają wartość. Przykład: the player's health, the name of the victim

Wcięcia (indentation) są kluczowe - Skript używa tabulatorów lub spacji do oznaczenia bloków kodu, podobnie jak Python. Każdy blok kodu pod zdarzeniem lub warunkiem musi być wcięty o jeden poziom głębiej.

Komentarze zaczynają się od #. Wszystko po tym znaku w danej linii jest ignorowane przez parser. Warto pisać komentarze po polsku - ułatwiają zrozumienie kodu kilka miesięcy po jego napisaniu.

Ważne zasady składni:

• Pliki skryptów mają rozszerzenie .sk i leżą w katalogu plugins/Skript/scripts/
• Pliki zaczynające się od - (np. -stary_skrypt.sk) są wyłączone i nie są ładowane
• Reload konkretnego pliku: /skript reload nazwaPliku
• Reload wszystkich skryptów: /skript reload all
• Lista skryptów: /skript list

Pierwszy skrypt - przykład

Najprostszy przykład - powitanie gracza przy dołączeniu i ochrona rud diamentów dla graczy bez uprawnień VIP:

on join:
    send "Witaj na serwerze, %player%!" to player
    give player 1 of bread

on break of diamond ore:
    if player does not have permission "server.vip":
        cancel event
        send "&cNie masz uprawnień do wydobycia diamentów!" to player

Rozłożenie tego przykładu na czynniki pierwsze:

• on join: - zdarzenie wyzwalane gdy gracz dołącza do serwera
• send "..." to player - efekt wysyłający wiadomość do gracza
• give player 1 of bread - efekt dający przedmiot
• on break of diamond ore: - zdarzenie wyzwalane przy niszczeniu rudy diamentów
• if player does not have permission "...": - warunek sprawdzający uprawnienia
• cancel event - efekt anulujący zdarzenie (blok nie zostaje zniszczony)

Zauważ, że kod czyta się niemal jak angielski tekst. To jest właśnie siła Skriptu - nawet osoba bez doświadczenia w programowaniu może zrozumieć, co skrypt robi.

Zdarzenia (Events)

Zdarzenia to serce Skriptu. Każdy skrypt reaguje na jakieś zdarzenie. Oto najczęściej używane:

Zdarzenia można filtrować bezpośrednio w nagłówku - na przykład on break of stone: wyzwoli się tylko przy niszczeniu kamienia, a on death of a zombie: tylko przy śmierci zombie. Takie filtrowanie jest wydajniejsze niż sprawdzanie warunku wewnątrz zdarzenia.

Warunki (Conditions)

Warunki pozwalają sterować logiką skryptu. Skript obsługuje warunki pozytywne i negatywne w naturalnym języku angielskim:

• if player is online / if player is not online
• if player has permission "node" / if player does not have permission "node"
• if player's health is greater than 10
• if player is in world "pvp"
• if player's gamemode is survival
• if attacker is a player
• if victim is a zombie
• if player has 5 of diamond in inventory
• if message contains "spam"

Warunki można łączyć operatorami and (oba muszą być prawdą) oraz or (wystarczy jeden). Można też stosować zagnieżdżone bloki if. Blok else i else if działają tak samo jak w innych językach programowania.

Efekty (Effects)

Efekty to akcje wykonywane przez Skript. To najbogatsza kategoria - Skript oferuje setki wbudowanych efektów:

Zmienne

Zmienne w Skripcie to jeden z najpotężniejszych mechanizmów. Są zapisywane automatycznie na dysku (plik plugins/Skript/variables.csv) i trwają między restartami serwera. Nie potrzebujesz zewnętrznej bazy danych dla prostych danych.

Rodzaje zmiennych:

• Lokalna (_zmienna) - istnieje tylko w czasie wykonania bieżącego bloku kodu, nie jest zapisywana. Używaj do wartości tymczasowych
• Globalna ({zmienna}) - dostępna z każdego skryptu, zapisywana na dysku. Przykład: set {punkty} to 100
• Przypisana do gracza ({zmienna::%player%}) - przechowuje wartość osobno dla każdego gracza. Kluczowy wzorzec dla systemów ekonomii, rang, statystyk
• Lista ({lista::*}) - kolekcja wartości. Możesz dodawać, usuwać, iterować po elementach. Przykład: add "Steve" to {admins::*}

Przykłady operacji na zmiennych:

• set {balance::%player%} to 500 - ustawia wartość
• add 100 to {balance::%player%} - dodaje do wartości liczbowej
• remove 50 from {balance::%player%} - odejmuje od wartości liczbowej
• delete {balance::%player%} - usuwa zmienną
• if {balance::%player%} is not set: - sprawdza, czy zmienna istnieje

Uwaga: domyślny plik CSV nie jest zbyt wydajny przy dużej liczbie graczy. Przy tysiącach rekordów rozważ addon skript-yaml lub skorzystanie z zewnętrznej bazy danych przez skript-reflect.

Własne komendy

Skript umożliwia definiowanie własnych komend z argumentami, opisami i uprawnieniami. To jeden z najczęstszych przypadków użycia:

command /bal []:
    trigger:
        if arg-1 is not set:
            send "Twoje saldo: &a%{balance::%player%}%" to player
        else:
            send "Saldo gracza %arg-1%: &a%{balance::%arg-1%}%" to player

command /pay  :
    trigger:
        if {balance::%player%} >= arg-2:
            remove arg-2 from {balance::%player%}
            add arg-2 to {balance::%arg-1%}
            send "&aPrzelano &e%arg-2%$ &ado %arg-1%." to player
        else:
            send "&cNie masz wystarczających środków." to player

Parametry definicji komendy:

• command /nazwa [<typ>]: - deklaracja komendy z opcjonalnym argumentem (typy: player, text, number, integer, item i inne)
• description: Opis komendy - opis widoczny w /help
• permission: node.uprawnienia - wymagane uprawnienie (domyślnie brak ograniczeń)
• permission message: Tekst błędu - wiadomość dla graczy bez uprawnień
• aliases: /alias1, /alias2 - alternatywne nazwy komendy
• cooldown: 30 seconds - cooldown między użyciami
• trigger: - blok kodu wykonywany po wpisaniu komendy

Argumenty dostępne są jako arg-1, arg-2 itd. lub przez nazwę (arg "gracz"). Sprawdź, czy argument jest ustawiony przez if arg-1 is set: przed jego użyciem.

Własne GUI (inwentarze)

Jedną z najbardziej spektakularnych funkcji Skriptu jest możliwość tworzenia interaktywnych menu w formie okien inwentarza (tzw. Chest GUI). Gracze klikają na przedmioty, które wyzwalają akcje:

command /menu:
    trigger:
        open chest with 3 rows named "&8Menu serwera" to player
        format slot 11 of player with diamond sword named "&bPvP Arena":
            teleport player to location(100, 64, 100, world "pvp")
        format slot 13 of player with emerald named "&aShop":
            execute player command "/shop"
        format slot 15 of player with book named "&eStworzenia":
            execute player command "/craft"

Wbudowany system GUI Skriptu jest prosty, ale ograniczony. Do bardziej zaawansowanych menu - z paginacją, dynamicznym odświeżaniem, slotami gracza - używa się addonu SkBee, który dostarcza znacznie bogatsze API do budowania interfejsów.

Typowe zastosowania GUI w Skripcie:

• Menu główne serwera z przyciskami do sekcji
• Shop - kupowanie i sprzedaż przedmiotów przez inwentarz
• Selektor klas/rang dla graczy
• Panel administracyjny z szybkimi akcjami
• Kolorowy interfejs questów z nagrodami
• Menu teleportacji do świata/areny

Pętle i harmonogramy

Skript obsługuje pętle iterujące po kolekcjach oraz harmonogramy cykliczne:

every 5 minutes:
    loop all players:
        add 10 to {balance::%loop-player%}
        send "&aOtrzymałeś &e10$ &apasywnego dochodu!" to loop-player

Kluczowe konstrukcje:

• every 5 minutes: - wykonuj kod co 5 minut (od startu serwera)
• every 1 second: - wykonuj co sekundę (używaj ostrożnie - to dużo wywołań)
• loop all players: - iteracja po wszystkich online graczach
• loop all entities in world "świat": - iteracja po encjach w świecie
• loop {lista::*}: - iteracja po elementach listy
• loop-player, loop-value, loop-index - zmienne dostępne wewnątrz pętli

Wewnątrz kodu asynchronicznego (np. po wait) zmienna player może nie być już dostępna jeśli gracz się rozłączył. Zawsze sprawdzaj if player is online: po wait.

Addony - SkBee, skript-reflect, SkQuery

Sam Skript ma ograniczenia - nie możesz np. manipulować NBT przedmiotów, tworzyć tablic wyników Scoreboard ani korzystać z zaawansowanego API Bukkit. Tu wchodzą addony - dodatkowe pluginy rozszerzające możliwości Skriptu o nowe składniki (elements).

SkBee

Najpopularniejszy i najbardziej wszechstronny addon. Dostarcza:

• Zaawansowane GUI (BossBar, Book, Anvil, Chest z paginacją)
• Manipulację NBT przedmiotów i encji - ustaw customową nazwę, lore, enchantmenty, custom model data
• Tablice wyników (Scoreboard) - wyświetl sidebar z informacjami dla graczy
• Struktury (WorldEdit-like) - skopiuj i wklej fragmenty świata skryptem
• Mapy blokowe - rysowanie na customowych mapach
• Integracja z PacketEvents dla zaawansowanych efektów wizualnych

skript-reflect

Najsilniejszy addon, ale wymagający więcej wiedzy. Pozwala wywoływać dowolne klasy Javy i metody Bukkit API bezpośrednio ze Skriptu. Możesz robić dosłownie wszystko, co można zrobić w pluginie Java - tylko składnią Skriptu. Używaj gdy wbudowane elementy Skriptu i SkBee nie wystarczają.

skript-placeholders (PlaceholderAPI)

Integracja z PlaceholderAPI. Pozwala używać placeholderów z innych pluginów w tekście wysyłanym przez Skript (%player_name%, %essentials_balance% itp.) oraz rejestrować własne placeholdery dostępne dla innych pluginów.

SkQuery

Starszy, ale wciąż używany addon dodający dodatkowe syntaktyki, efekty i wyrażenia nieobecne w standardowym Skripcie. Część funkcji SkQuery jest dziś dostępna w samym Skripcie lub SkBee, ale na serwerach z legacy skryptami SkQuery może być konieczny.

Inne addony warte uwagi

• Skript-yaml - czytanie i zapisywanie plików YAML (lepsza alternatywa dla zmiennych przy dużej ilości danych)
• Skript-db - bezpośrednie zapytania SQL do bazy danych MySQL/SQLite
• SkriptWebAPI - wysyłanie żądań HTTP z Skriptu (do zewnętrznych API)

Wydajność i dobre praktyki

Skript jest wolniejszy niż natywny plugin Java - to fakt, który trzeba zaakceptować. Interpreter języka skryptowego zawsze ma narzut w stosunku do skompilowanego kodu. Jednak przy rozsądnym użyciu różnica jest niezauważalna dla graczy:

• Unikaj pętli co tick (co 1/20 sekundy) - używaj every 1 second zamiast every 1 tick. Jeśli musisz tick, niech pętla robi jak najmniej
• Minimalizuj pętle po wszystkich graczach i encjach - zamiast co sekundę sprawdzać wszystkich graczy, używaj zdarzeń (on join, on move) i lokalnego stanu
• Używaj zmiennych lokalnych (_zmienna) dla wartości tymczasowych - nie są zapisywane na dysku i nie blokują I/O
• Ogranicz operacje dyskowe - każda operacja na globalnej zmiennej może triggerować zapis. Grupuj zmiany
• Filtruj zdarzenia w nagłówku - on break of diamond ore: jest wydajniejsze niż on break: if event-block is diamond ore:
• Nie duplikuj kodu - używaj funkcji (function nazwaFunkcji(arg: type):) dla wielokrotnie używanej logiki
• Profiluj skrypty - Spark Profiler pokaże, które skrypty zjadają CPU. Uruchom /spark profiler i sprawdź co zajmuje czas

Na serwerach z 50+ graczami dobrze napisany Skript działa bez problemów. Problemy zaczynają się przy bardzo dużych mapach, pętlach co tick lub nieprzemyślanej architekturze skryptów.

Porady dla początkujących

• Zacznij od małych rzeczy - napisz najpierw skrypt powitalny (on join), potem prosty system ekonomii. Nie próbuj od razu tworzyć skomplikowanego systemu questów
• Używaj skIDE lub VSCode z rozszerzeniem - kolorowanie składni znacznie ułatwia pisanie. Rozszerzenie "Skript" dla VSCode daje podświetlanie i podstawowe podpowiedzi
• Czytaj błędy w konsoli - Skript generuje czytelne komunikaty błędów z numerem linii. Przed pytaniem na forum zawsze przeczytaj błąd do końca
• Dokumentacja i forum - oficjalna dokumentacja na docs.skriptlang.org i forum SkriptLang Forum to najlepsze źródła
• Sprawdzaj wersję kompatybilności - niektóre addony nie są aktualizowane na bieżąco. Zawsze sprawdź, czy addon obsługuje Twoją wersję Skriptu i Minecrafta przed instalacją
• Rób kopie zapasowe skryptów - przed większymi zmianami skopiuj działający plik. /skript reload nie cofa zmian automatycznie
• Komentuj kod po polsku - za 3 miesiące będziesz wdzięczny, że wiesz co skrypt robi bez czytania każdej linii

Powiązane strony: EssentialsX (podstawowe komendy serwera), PlaceholderAPI (placeholdery w tekście Skriptu), katalog wszystkich pluginów.