Skript Workshop Guida

Guida per Skript

Realizzata da @Skript_Workshop sotto la penna di @taserato, NotRadish - ultimo update: 25/01/2024

Salve a tutti, questa è una guida per il plugin di Minecraft "Skript". La guida è stata ideata per persone che iniziano da zero oppure persone che hanno bisogno di approfondimenti, quindi è divisa in capitoli:

Capitoli:

Capitolo 1: Le basi di Skript

Prima iniziare a Skriptare, bisogna imparare le basi di skript e come funziona o agisce nel tuo server minecraft. Ci sono diversi elementi che compongono il codice di uno Skript, che sarebbero:

L'evento:
Un evento è un'azione che viene espressa da un giocatore, dal server, o automaticamente. Tutti gli skript devono avere un evento per poter funzionare. La condizione: La condizione è una parte di un codice, che, solitamente dopo un evento, decide se continuare a eseguire il codice seguente o meno. La condizione può essere qualsiasi cosa, dalla vita di un giocatore al meteo corrente in un mondo.
L'effetto:
L'effetto è il codice dello skript, quello che viene sempre dopo un evento o una condizione. Applica effetti ai giocatori, suona un file .ogg, e qualsiasi altra cosa desideri. L'espressione: L'espressione è un "placeholder" che contiene un'informazione specifica, rispetto ad un giocatore, una variabile o un'azione del server. "Types" o "tipi": Un type è un modo in cui skript identifica un qualsiasi oggetto che necessita, per esempio "text", "grass block" o "player". Domanda: Mi devo memorizzare tutte le condizioni, gli eventi, e tutte gli elementi elencati?
Assolutamente NO! Bensì è importante saper distinguere un evento da una condizione, memorizzare tutti gli eventi e tutte le condizioni è quasi impossibile, anche se molti vengon da sè, ovviamente se si ha abilità in lingua inglese.
Skript fornice una lista ufficiale di tutti gli elementi del codice nel link qui: documentazioni ufficiali
E' importante tener conto di questa documentazione, dato che è essenziale se sei alle prime armi con skript.
Una volta memorizzati gli elementi del codice, possiamo muoverci verso il prossimo step: iniziare a scrivere il codice.
Per scrivere gli Skript si può usare qualsiasi programma che permette di modificare un file di testo. Io, personalmente, consiglio questi:
Sublime Text (quello che utilizzo io)
Notepad++ (e skript XML)
La scelta del programma per scrivere è davvero soggettiva, siete liberi di scegliere quello con cui vi trovate meglio e con cui riuscite ad aumentare la vostra performance al massimo.
Scrivendo skript, è importante indentare (= mettere in ordine il codice tramite spazi / tabulazioni) con degli spazi nel testo, che possono essere:
Una tabulazione (accessibile con tasto TAB, più comune) 2 spazi 4 spazi Come la scelta del programma, anche questa è molto soggettiva. Vi consiglio di utilizzare quella con cui vi trovate meglio. Nella maggior parte dei linguaggi informatici, le tabulazioni sono più usate. Vi consiglio strettamente di utilizzarle se volete espandere le vostre conoscenze con altri tipi di codice.
Scriverò del codice che utilizzerò come esempio. Siete liberi di copiare il codice e provarlo per voi.
Come definire un comando
Per definire un comando, bisogna utilizzare la stringa "command /comando a tua preferenza:" fate attenzione a non usare l'evento "on command:".
Questo comando ti invia un messaggio quando scritto in chat.
Ricordatevi di usare "trigger:" dopo ogni comando, altrimenti non funzionerà. Ogni comando può avere diverse opzioni, che vanno messe prima di "trigger:", qui elencate: permission: permesso a tua preferenza: rimuove la possibilità di eseguire il comando a chi non ha questo permesso.
permission message: testo: il messaggio che invia se una persona senza permessi prova ad eseguire il comando.
aliases: comando 1, comando 2: permette di impostare dei comandi extra con la stessa funzione del comando che hai appena impostato.
cooldown: timespan: permette di impostare un cooldown ad un comando
bypass permission: permesso a tua preferenza: permette di impostare un permesso che dà la possibilità di rimuovere il cooldown al comando
cooldown message: testo: il messaggio che invia se una persona prova a eseguire il comando mentre è in cooldown
description: testo: il messaggio che invia nella schermata di /help, raramente usato ma se vuoi andare nel dettaglio ti consiglio di usarlo.
I loop
I loop sono un effetto molto particolare di skript. Farò un esempio più semplice possibile. Immaginate una corda, che passa attraverso tanti elementi: possono essere tutti i giocatori, una lista variabile, oppure dei blocchi. Una volta che un loop viene effettuato, il codice dopo di esso viene effettuato per ogni elemento che la corda incontra. Quindi, per esempio, possiamo creare una cosa del genere:
Questo comando invia la prima stringa a tutti i poliziotti online nel mondo "roleplay" Per accedere al soggetto affetto al loop, bisogna utilizzare sempre il prefix "loop-". Per esempio: loop-offline player loop-player loop-block loop-value loop-value-2

Capitolo 2: Variabili

Una variabile è una funzione quasi essenziale che skript porta. Normalmente, in java, non è disponibile, ma skript lo rende possibile tramite il file "variables.csv" che trovate nella cartella "Skript".

La variabile è il metodo che usa skript per salvare oggetti, testo, inventari, qualsiasi cosa tu voglia. Per impostare una variabile si usa questa string:
Esempi di come settare una variabile.
Questa variabile può essere usata ovunque, per esempio:
Questo codice non permette di saltare se si è feriti. Ci sono 3 tipi diversi di variabile:
Variabile GLOBALE e SINGOLA:
Una variabile globale è una variabile che non è assegnata ad alcun giocatore, può essere {guidaskript} o qualsiasi cosa tu voglia. Non ha bisogno di eventi per essere usata.
Una variabile "singola", invece, è una variabile che all'interno contiene il nome o l'uuid di un giocatore, quindi è accessibile tramite un evento che ne affligge uno.
Esempio nell'immagine scorsa.
Variabile LOCALE:
Una variabile locale è una variabile che inizia con un underscore ("_"), è utilizzata per variabili che necessitano di un breve tempo di uso, per esempio:
Questo codice invia un messaggio di saluto ad un giocatore. La variabile locale non è condivisa tra eventi diversi o skript diversi, per questo non viene salvata nel file nominato all'inizio del capitolo ("variables.csv").
Variabile LISTA:
Una lista variabile è una variabile che contiene molteplici oggetti: possono essere giocatori, blocchi, testo o qualsiasi cosa tu voglia. Le liste variabili sono utilizzabili per esempio per una lista di blocchi oppure una lista di messaggi, come le variabili elencati in precedenza possono essere qualsiasi cosa tu voglia, però questo tipo di variabile può contenere più elementi.
Per crearne una, usa questo codice:
Come aggiungere oggetti ad una variabile. A differenza delle variabili precedenti, questa non ha bisogno di essere settata, però può essere fatto in ogni caso, in questo esempio:
Questo codice, con il 10% di possibilità, elimina la prima lettera di un messaggio.

Capitolo 3: Addon e Hook

Un addon è un plugin, solitamente creato dall'utenza, che permette agli sviluppatori di skript di migliorare la propria esperienza mentre si fanno skript, aggiungendo nuove funzioni.

Certi addon sono molto importanti per funzioni che vuoi a portata di mano, per esempio:
SkBee è il plugin più utile per usare funzioni come il tab complete o la modifica avanzata degli NBT.
skript-placeholders è il plugin più utile per creare dei placeholder accessibili a PlaceHolderAPI
WolvSK è il plugin più utile per utilizzare EssentialsX e le GUI con le incudini.
Gli addon, oltre che molto utili, sono decine e decine, e sarebbe impossibile nominarli tutti. Per utilizzarli, semplicemente mettete il plugin nella cartella dove sono tutti gli altri e restartate il server, non funzionerà utilizzando plugman o simili.
Ogni addon approvato ha la sua documentazione sul sito di SkUnity (https://docs.skunity.com/addons), i più usati hanno molto spesso anche diversi esempi per aiutarvi a maneggiarlo al meglio.
Invece, un hook, è uno skript che si connette a un plugin installato nel tuo server tramite skript-reflect (vedi capitolo 6).
Un hook può essere utile se non sei abile con skript-reflect e vuoi usare delle funzioni più simili a skript normale, viene spesso utilizzato come versione più "light" degli addon ma raramente è documentato, quindi l'unico modo per utilizzarne uno è aprendo il file e vedendo le funzioni che aggiunge.

Capitolo 4: Function

Le function sono delle funzioni che possono essere applicate al codice. Ne esistono di 2 tipi diversi:

Una function che ritorna una valuta specifica Una function che effettua un'azione Una function che ritorna una valuta specifica (per esempio) può essere usata nelle GUI fatte tramite inventario di una chest.
Questo comando apre una GUI con un barrier come slot 1
Questo codice può essere ridotto tramite una function del genere:
Questa function ritorna una GUI
Questa GUI adesso può essere aperta con:
Apri la function appena scritta sopra
Quindi, queste function che ritornano una valuta possono essere usate per ridurre il lag al massimo, e per riuscire a impostare un oggetto specifico senza doverlo settare ogni volta che si apre il comando (come nella prima immagine).
Per scrivere questo tipo di function bisogna formularle in questo modo:
{} = variabile a tua scelta, parsed come il tuo return type ovviamente I return type più usati (ergo i più utili) sono:
Text (testo) Inventory (gui) Item (oggetto) Per esempio, le function che ritornano del testo possono essere inserite tra percentuali (% = SHIFT+5) e sono utilizzabili come delle espressioni (se non sai cosa siano guarda il capitolo 1).
All'inizio del capitolo ho elencato 2 tipi di function: quella che ti ho appena spiegato, e questa, che è una function che effettua un'azione.
Questi tipi di function hanno lo stesso scopo delle altre function, ovvero ridurre il lag, quindi qui ti faccio vedere come si possono usare. Userò come esempio lo skript "keysManette" fatto da me nel canale.
Questa function ammanetta un giocatore.
Nelle function è possibile inserire tra le parentesi degli oggetti che verranno affetti da quest'ultima, nell'esempio puoi vedere il modo in cui si usano.
(p: player) significa: il giocatore che viene inserito ({_p}) tra le parentesi verrà sottoposto al codice di seguito. Per accedere al giocatore, bisognerà utilizzare il testo prima dei due punti ":", che può essere una parola, un testo, o quello che vuoi. Una volta decisa questa stringa, usate le parentesi graffe, con all'interno un underscore e dopo la stringa che avete utilizzato nelle parentesi tonde, in questo caso "p" è diventato "{_p}".
Per utilizzare l'effettiva function, scrivete il nome della function (con le maiuscole esatte, mi raccomando), e all'interno, se ci sono, i soggetti o gli oggetti affetti dalla function, che possono essere sempre i return type elencati qualche riga fa.
Quindi, per ammanettare un giocatore, si dovrà usare questa stringa:
keyAmmanetta(player)
Ovviamente per usare "player" ci dovrà essere un evento che ingaggia un player, una clicked entity, o qualsiasi cosa.

Capitolo 5: skript-reflect (Non per principanti)

skript-reflect è un plugin che permette di utilizzare API di plugin, server remoti o qualsiasi cosa. Viene utilizzato per diverse funzioni:

Aggiungere nuove espressioni, eventi o effetti
Utilizzare dei plugin installati nel server, modificandone il loro comportamento / creando nuove funzioni
Utilizzare le class di java
Traslare un plugin a uno skript
Spesso, personalmente, lo uso quando sto facendo uno skript complicato e le funzioni che servono a me non sono supportate in alcun modo da skript o un altro addon. Si possono vedere tutte le funzioni tramite i javadocs di bukkit e spigot oppure aprendo un plugin utilizzando un decompiler

Capitolo 6: FAQ (Frequently Asked Questions)

Perchè uno skript che ho installato (o che ho fatto io) non funziona?

Ci sono diversi fattori per il quale uno skript può smettere di funzionare. Alcuni di questi possono essere:
Un plugin che interferisce con gli eventi di skript: Per controllare se c'è un plugin che interferisce con degli eventi specifici, vi consiglio prima di tutto di controllare la console. Solitamente, quando un evento viene chiamato, se si ha problemi, un errore viene inviato alla console. Se non accade, vi consiglio di pensare sui vostri plugin e provare a rimuoverli uno ad uno (o disabilitarli con PlugManX) fino a che lo skript non funziona.
Errori nello skript
Per individuare errori nello skript, bisogna effettuare il comando "/skript reload %nome dello skript%".
Questo, normalmente, dovrebbe inviare 2 messaggi separati, avvisandoti che lo skript sta essendo ricaricato e poi quanto tempo ci ha messo a ricarcarsi.
Nel tempo in cui si ricarica, ci potranno essere degli errori, che sono inviati con un messaggio ad alta visibilità e quindi non dovreste avere problemi scoprendo dov'è l'errore.
Versione di skript vecchia
Nelle vecchie versioni di skript, certi eventi, effetti o funzioni non sono supportate. Vi consiglio di aggiornare alla più recente release che non sia in beta.
Il link con tutte le release ufficiali è:
https://github.com/SkriptLang/Skript/releases
Il file "server.jar" non supporta certi eventi / certe funzioni.
Certi tipi di server non supportano certi eventi, vi consiglio altamente di usare paper per avere il massimo supporto possibile con skript. Il tipo del server dovrebbe essere facilmente installabile all'interno della console del vostro server, assieme alla versione di java.
Dove trovo informazioni, quali sono i migliori siti che posso usare?
I siti più ottimali da usare sono pochi, solitamente i problemi vengono esposti sul forum o sul discord di SkUnity
sito di skunity
Questo sito permette anche di utilizzare un parser, ovvero un elemento che è capace di analizzare il tuo skript per errori, addon e variabili.
Per vedere ogni espressione, funzione etc nello specifico, consiglio di consultare:
docs.skriptlang.org/
Già nominato in precedenza, questo sito (ufficiale di skript) contiene tutte le possibili espressioni contenute nel plugin. Se ti serve una cosa, lì la trovi.
Per trovare addon o funzioni che vi servono, potete usare:
https://skripthub.net/docs/ o https://docs.skunity.com/syntax/ (molto simili)
Questi siti contengono, oltre alle funzioni normali di skript, la maggior parte delle funzioni degli addon.
Non usate qualsiasi modello di IA che non prenda informazioni direttamente dal web (ad esempio, ChatGPT usa informazioni dal 2021) per fare i vostri skript. Skript è fatto per essere un linguaggio semplice e non dovrebbe essere fatto con supporti esterni.