Sono disponibili alcuni strumenti per aiutarvi a gestire lo spazio di gioco di Roll20 in modo coerente. È possibile richiamare una funzione di strumento da qualsiasi punto dei propri script (ad esempio, all'interno di qualsiasi callback di evento). La documentazione completa sulle funzioni è disponibile alla voce " Mod Scripts: Documentazione sulle funzioni".
Underscore.js
Potete avvalervi della libreria Underscore.js (tramite l’oggetto globale _ ) per semplificarvi il lavoro. Underscore mette a disposizione funzioni di supporto quali _.each (per iterare su un array di oggetti). Per ulteriori informazioni, consulti la documentazione di Underscore.
Registrazione
log(messaggio)
È possibile utilizzare questa funzione per registrare l'output nella Mod Output Console nella pagina Script Editor. Utile per il debug dei vostri script e per comprendere meglio cosa accade all’interno della Mod Script sandbox.
on("change:graphic", function(obj) {
log("Rilevata modifica per l'oggetto con ID: " + obj.id);
});Solo per Mod Script sandbox v1.5. Ove possibile, i messaggi di errore includono un oggetto di contesto che identifica l’oggetto Roll20 interessato, ad esempio:
ERRORE: la funzione toBelow() deve essere richiamata con un oggetto grafico, di testo o di percorso di Roll20. Chiamato con [personaggio Roll20 -NM0tVij02hIfnoTdihc].
Ordine degli oggetti
toFront(obj) e toBack(obj)
Queste due funzioni consentono di spostare un oggetto presente sul tavolo di gioco in primo piano (o in secondo piano) rispetto al livello su cui si trova attualmente. Si noti che è necessario passare un oggetto effettivo, come ad esempio quello che si riceve in una callback di evento o chiamando getObj o findObjs.
toAbove(obj, target) e toBelow(obj, target)
Solo per Mod Script sandbox v1.5. Posizionare l'oggetto immediatamente sopra o sotto l'elemento di destinazione nell'ordine di sovrapposizione. Il target può essere un oggetto grafico, di testo, percorso o percorso v2, oppure l’ID di uno di tali oggetti. I metodi toFront e toBack accettano l'oggetto stesso. Questi stessi tipi dispongono inoltre di metodi di istanza toFront(), toBack(), toAbove(target) e toBelow(target).
Numeri casuali
numero casuale intero (massimo)
Restituisce un numero intero casuale compreso tra 1 e max, utilizzando lo stesso generatore dei dadi di Roll20. Utilizzi questo per i dadi. Math.floor(Math.random() * max) + 1 è distribuito in modo uniforme per le dimensioni dei dadi effettivamente utilizzati; la distorsione modulare è un problema a sé stante (numero intero % n).
math.random()
Potete richiamare Math.random() come di consueto nei vostri script di mod, certi che i risultati saranno casuali, poiché il Math.random() “predefinito” in JavaScript è stato sostituito con il generatore di numeri casuali (PRNG) crittograficamente sicuro su cui si basa Roll20. Pertanto, gli script esistenti che utilizzano Math.random() possono essere impiegati con la certezza che i risultati siano davvero il più possibile vicini alla casualità, per quanto ciò sia possibile su un computer.
Per un lancio di dadi, si consiglia di utilizzare randomInteger(max). Si tratta dello stesso generatore utilizzato dal motore dei dadi.
Il giocatore è il GM
playerIsGM(id giocatore)
Indica se quel giocatore è attualmente un GM. Consente di passare alle promozioni e alla funzione “rientrare come giocatore” senza dover riavviare il sistema. playerIsGM("API") è falso: la chat inviata tramite script utilizza l'ID giocatore "API", che non corrisponde a nessun giocatore nel gioco.
Personaggio
setDefaultTokenForCharacter(personaggio, token)
Imposta il segnalino di default per l'oggetto personaggio fornito in base ai dettagli dell'oggetto segnalino fornito. Entrambi gli oggetti devono già esistere. Questo sovrascriverà qualsiasi segnalino di default attualmente associato al personaggio.
Effetti speciali (FX)
spawnFx(x, y, tipo, pageid)
Genera un effetto di breve durata nella posizione x,y del tipo specificato. Se si omette il parametro ` pageid` o si passa un valore non definito, verrà utilizzata per impostazione predefinita la pagina in cui si trovano attualmente i giocatori (`playerpageid` nell'oggetto `Campaign`).
Per gli effetti integrati, il tipo deve essere una stringa e corrispondere a uno dei seguenti valori: beam-color, bomb-color, breath-color, bubbling-color, burn-color, burst-color, explode-color, glow-color, missile-color, nova-color, splatter-color
Laddove il termine “colore” nel testo sopra riportato si riferisce a uno dei seguenti: acido, sangue, fascino, morte, fuoco, gelo, sacro, magico, melma, fumo, acqua
Per gli effetti personalizzati, il campo "type" deve contenere l'ID dell'oggetto custfx corrispondente all'effetto personalizzato.
spawnFxBetweenPoints(punto1, punto2, tipo, idpagina)
Funziona allo stesso modo di `spawnFx`, ma invece di un singolo punto si specificano due punti, nel formato {x: 100, y: 100}. Ad esempio: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"). Gli effetti di raggio, respiro e spruzzi si propagano tra i due punti. Le coordinate sono espresse in pixel della pagina, con gli stessi marginisinistro e superiore delle immagini. Le coordinatex/y di finestre e porte utilizzano l'asse invertito e non corrispondono a queste coordinate.
I seguenti tipi di effetto devono sempre utilizzare `spawnFxBetweenPoints` anziché ` spawnFx`: `beam-color`, `breath-color`, `splatter-color`
Solo per Mod Script sandbox v1.5. Gli effetti di tipo “trave” puntano direttamente verso il punto 2 (è stato corretto un errore nel calcolo dell’angolo).
spawnFxWithDefinition(x, y, definizione, idPagina)
Crea un effetto personalizzato ad hoc nelle coordinate x, y. La definizione è un oggetto JavaScript, non una stringa JSON. La struttura è identica a quella di una definizione Custom FX. Se si omette pageid o si passa un valore non definito, viene utilizzata la pagina corrente dei giocatori (Campaign().get("playerpageid")).
Playlist del jukebox
riproduciJukeboxPlaylist(idplaylist)
Prende l'ID della cartella (ottenibile dalla proprietà _jukeboxfolder dell'oggetto Campaign) della playlist e avvia la riproduzione di tale playlist per tutti i giocatori.
interrompiJukeboxPlaylist()
Non richiede alcun argomento e interrompe qualsiasi playlist attualmente in riproduzione.
Vario
sendPing(sinistra, alto, idPagina, idGiocatore, spostaTutto, visibileA)
Invia un segnale al tavolo di gioco (come se si tenesse premuto il pulsante del mouse). "sinistra " e " in alto " indicano i pixel della pagina. È necessario specificare il "pageid". playerid è facoltativo e costituisce il quarto argomento: il giocatore a cui viene attribuito il ping. Se lo si omette o si passa un valore falso, il ping viene attribuito a "api" (giallo).
Si passi il valore "true" alla funzione moveAll per far scorrere i giocatori fino a quel punto. Il parametro `visibleTo` limita chi può visualizzare il ping: un ID giocatore, un array di ID o una stringa delimitata da virgole. Omettete questo parametro oppure specificate "", per inviare un ping a tutti.
I ritardi impostati con `setTimeout` nell'esempio riportato di seguito vengono azzerati al riavvio della sandbox.
on("chat:message", function(msg) {
if (msg.type !== "api" || msg.content.indexOf("!pingtest") !== 0) return;
var players = findObjs({_type: "player"});
if (players.length < 1) return;
var player1 = players[0].id;
var player2 = players.length > 1 ? players[1].id : player1;
var allPlayerIDs = players.map(function(player) { return player.id; });
var pageid = Campaign().get("playerpageid");
// pageid è il terzo argomento; playerid è il quarto. L'attributo "null" associa il ping a "api".
sendPing(300, 300, pageid, null, true);
setTimeout(function() {
// Impostando "visibleTo" su "" si invia un ping a tutti
sendPing(1500, 500, pageid, msg.playerid, true, "");
}, 1000);
setTimeout(function() {
sendPing(1200, 500, pageid, null, true, player1);
}, 2000);
setTimeout(function() {
sendPing(900, 100, pageid, player2, true, [player1, player2]);
}, 3000);
setTimeout(function() {
sendPing(300, 300, pageid, player1, true, allPlayerIDs.join());
}, 4000);
});Nota sulle distanze e le griglie in Roll20
Su una griglia quadrata, un'unità corrisponde a 70 pixel. Il parametro `snapping_increment` della pagina indica il numero di unità che compongono ciascuna casella della griglia, `scale_number` rappresenta la distanza di un’unità e `scale_units` indica il nome dell’unità (spesso “ft”). I valori predefiniti sono: 1 unità = 5 piedi = 1 quadrato = 70 pixel. Un GM può impostare 1 unità pari a 10 piedi, oppure ogni quadrato pari a 2 unità (140 pixel).
Le griglie esagonali non utilizzano quel quadrato di 70 pixel. Le posizioni delle finestre e delle porte utilizzano un asse y invertito; quelle relative alla partesinistra/superiore del grafico no.