Variabili globali
Variabile | Descrizione |
---|---|
_ |
Questo è l'oggetto namespace per la libreriaUnderscore.js. |
state |
Le proprietà dell'oggetto state persistono tra le sessioni di gioco. |
_ (Underscore)
Questo è l'oggetto namespace per la libreriaUnderscore.js. Underscore ha molte funzioni per la manipolazione delle collezioni.
state
Le proprietà dell'oggetto di stato persistono tra le sessioni di gioco. Lo stesso oggetto di stato è condiviso anche tra tutti gli script Mod (API) in una campagna, quindi è fortemente consigliato che quando si scrivono valori nello stato, si minimizzi il proprio impatto il più possibile al fine di evitare collisioni di nomi. Nota: lo stato viene serializzato con JSON, quindi non è possibile memorizzare funzioni o oggetti con riferimenti ciclici.
Funzioni Globali
Tipo di restituzione | Funzione | Descrizione |
---|---|---|
Oggetto Roll20 | Campagna |
Ottiene l'oggetto Campagna singleton di Roll20. |
Oggetto Roll20 | createObj |
Crea un nuovo oggetto Roll20. |
Array di oggettiRoll20 | filterObjs |
Ottiene tutti gli oggetti Roll20 che superano un test predicato. |
Array di oggettiRoll20 | findObjs |
Ottiene tutti gli oggetti Roll20 con proprietà che corrispondono a un dato insieme di attributi. |
Array di oggettiRoll20 | getAllObjs |
Ottiene tutti gli oggetti Roll20 nella campagna. |
varia | getAttrByName |
Ottiene il valore corrente o massimo di un attributo dell'oggetto Roll20. |
Oggetto Roll20 | getObj |
Ottiene un oggetto Roll20 specifico. |
u |
Registra un messaggio sulla console Mod (API). | |
su |
Registra un gestore di eventi. | |
onSheetWorkerCompleted |
Registra un gestore di eventi una tantum da eseguire dopo il completamento di uno stack completo diSheet Worker Scripts. | |
Boolean | playerIsGM |
Verifica se un giocatore attualmente ha i privilegi di GM. |
playJukeboxPlaylist |
Avvia la riproduzione di una playlist di jukebox. | |
Numero | randomInteger |
Genera un valore intero casuale. |
sendChat |
Invia un messaggio nella chat. | |
sendPing |
Invia un ping simile a tenere premuto il pulsante sinistro del mouse. | |
spawnFx |
Crea un emettitore di particelle. | |
spawnFxBetweenPoints |
Crea un emettitore di particelle che si muove da un punto a un altro. | |
spawnFxWithDefinition |
Crea un emettitore di particelle che non è rappresentato da un oggetto FX di Roll20. | |
stopJukeboxPlaylist |
Interrompe tutte le playlist jukebox currently playing. | |
toBack |
Sposta un oggetto grafico Roll20 dietro tutti gli altri oggetti grafici dello stesso livello sul tabletop. | |
toFront |
Sposta un oggetto grafico Roll20 sopra tutti gli altri oggetti grafici dello stesso livello sul tabletop. |
Campagna
Parametri
Nessun parametro
Restituisce
Il singolo oggetto campagna Roll20.
Esempi
var currentPageID = Campaign().get('playerpageid'), currentPage = getObj('page', currentPageID);
createObj
Parameters
TYPE(String) The type of Roll20 object to create. Only 'graphic', 'text', 'path', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', and 'macro' may be created. ATTRIBUTES(Object) The initial values to use for the Roll20 object's properties.
Returns
The Roll20 object that was created.
Examples
Quando crea un oggetto Roll20 che ha un oggetto genitore (come la creazione di un oggetto Roll20 attributo, che è figlio di un oggetto Roll20 carattere, deve fornire l'id del genitore inattributi
.
on('add:character', function(obj) { createObj('attribute', { name: 'Strength', current: 0, max: 30, characterid: obj.id }); });
Durante la creazione di un oggetto Roll20 path, è necessario fornire un valore per la proprietà di sola lettura_path
. Questo è un'eccezione alla regola che impedisce di impostare il valore delle proprietà di sola lettura durante la creazione degli oggetti Roll20.
createObj('path', { left: 7000, top: 140, width: 140, height: 140, layer: 'objects', path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]]) });
Durante la creazione di un oggetto Roll20 handout, non è possibile impostare il testo o le note di GM in fase di creazione.
var handout = createObj('handout', { name: 'A Letter Addressed to You', inplayerjournals: 'all', archived: false }); handout.set({ notes: 'Notes can only be set after the handout is created', gmnotes: 'GM Notes can only be set after the handout is created' });
filterObjs
Parametri
CALLBACK(Function) Una funzione predicato per testare tutti gli oggetti Roll20. La funzione di callback riceve un oggetto Roll20 come parametro e deve restituire sia vero (per gli oggetti Roll20 che saranno inclusi nel valore di ritorno di filterObjs) o falso (per tutti gli altri oggetti Roll20).
Restituisce
Un array di oggetti Roll20 che hanno superato il test del predicato.
Esempi
var nomeToken = getMyTokenName(), duplicaToken = filterObjs(function(obj) { if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === nomeToken) return false; return obj.get('name').indexOf(nomeToken) === 0 && /\d+$/.text(obj.get('name')); });
findObjs
Parametri
ATTRIBUTI(Oggetto) Una collezione di coppie chiave:valore da abbinare agli oggetti Roll20 nella campagna.OPZIONI(Oggetto, facoltativo) Se options.caseInsensitive è true, i confronti tra stringhe tra oggetti Roll20 e attributi saranno case-insensitive.
Restituisce
Un array di oggetti Roll20 con proprietà che corrispondono aattributi
.
Esempi
var npcs = findObjs({ type: 'character', controlledby: '' });
getAllObjs
Parametri
Nessun parametro
Restituisce
Un array di tutti gli oggetti Roll20 nella campagna.
Esempi
var everything = getAllObjs();
getAttrByName
Parametri
CHARACTER_ID(String) L'id dell'oggetto Roll20 personaggio che è il padre dell'oggetto Roll20 attributo di cui si desidera il valore. ATTRIBUTE_NAME(String) Il nome dell'oggetto Roll20 attributo di cui si desidera il valore. VALUE_TYPE(String, opzionale) "current" o "max" (predefinito "current" se omesso).
Torna a
La proprietàattuale
omax
dell'attributo appropriato. Se la proprietà desiderata non è impostata, verrà utilizzato il valore predefinito specificato dal foglio del personaggio (se esiste un valore predefinito).
Esempi
var character = getMyCharacter(), strength = getAttrByName(character.id, 'strength'), strength_max = getAttrByName(character.id, 'strength', 'max');
getObj
Parametri
TYPE(String) Il tipo di oggetto Roll20 da ottenere. ID(String) L'id univoco dell'oggetto Roll20 da ottenere.
Torna a
L'oggetto specificato Roll20.
Esempi
on('chat:message', function(msg) { var sendingPlayer = getObj('player', msg.playerid); });
log
Parametri
MESSAGE(varia) Il messaggio da inviare alla console Mod (API). Il parametro del messaggio verrà trasformato in una Stringa con JSON.stringify.
Restituisce
(Void)
Esempi
on('chat:message', function(msg) { log('Messaggio ricevuto da:'); log(getObj('player', msg.playerid)); });
"Messaggio ricevuto da:" {"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"player","_lastpage":""}
su
Parametri
EVENT(String) Ci sono cinque tipi di evento:readychangeadddestroychatAd eccezione di ready, tutti i tipi di evento devono essere anche abbinati a un tipo di oggetto. Per chat, questo è sempre message. Per tutto il resto, questa è la proprietà type di un oggetto Roll20. Oltre al tipo di oggetto, i changeevents possono anche specificare opzionalmente una proprietà dell'oggetto Roll20 specificato. Le 2-3 parti dell'evento (tipo, oggetto e opzionalmente proprietà) sono separate dai due punti. Quindi, le stringhe di event valide includono ma non si limitano a "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character" e "destroy:handout".CHIAMATA(Funzione) La funzione che verrà richiamata quando si verifica l'evento specificato. I parametri passati dipendono dal tipo di evento: gli eventi ready non hanno parametri di callback. Gli eventi change hanno un parametro obj, che è un riferimento all'oggetto Roll20 così come esiste dopo la modifica, e un parametro prev, che è un oggetto JavaScript semplice con proprietà corrispondenti all'oggetto Roll20 prima dell'evento di modifica. Gli eventi add hanno un parametro obj, che è un riferimento al nuovo oggetto Roll20. Gli eventi destroy hanno un parametro obj, che è un riferimento all'oggetto Roll20 che non esiste più. Gli eventi chat hanno un parametro msg, che contiene i dettagli del messaggio inviato in chat.
Restituisce
(Void)
Esempi
Gli eventi vengono scatenati nell'ordine in cui sono registrati e dal più specifico al meno specifico. In questo esempio, una modifica alla proprietàleft
di un oggetto grafico Roll20 comporterà la chiamata della funzionefunction3
, seguita dalla funzionefunction1
e poi dalla funzionefunction2
.
on('cambia:grafica', funzione1); on('cambia:grafica', funzione2); on('cambia:grafica:sinistra', funzione3);
aggiungere gli eventitenterà di attivarsi per gli oggetti Roll20 che sono già presenti nella campagna quando inizia una nuova sessione. Per prevenire questo comportamento, puoi attendere fino a registrare il tuo eventoaggiungifino a quando l'eventoprontonon viene attivato.
on('add:graphic', function(obj) { // Quando la sessione inizia, questa funzione sarà chiamata per ogni elemento grafico nella campagna // Questa funzione sarà anche chiamata ogni volta che viene creato un nuovo oggetto Roll20 grafico }); on('ready', function() { on('add:graphic', function(obj) { // Questa funzione verrà chiamata *solo* quando viene creato un nuovo oggetto Roll20 grafico, non per quelli già esistenti }); });
Il parametropre
per gli eventichangenon è un oggetto Roll20, ma un semplice oggetto JavaScript. Pertanto, non può utilizzare le funzioniget
oset
e non può omettere i trattini bassi iniziali nelle proprietà di sola lettura.
on('change:graphic', function(obj, prev) { var id1 = obj.id, // tutti e tre sono equivalenti id2 = obj.get('id'), id3 = obj.get('_id'), id4 = prev.id, // non definito id5 = prev.get('id'), // non definito non è una funzione id6 = prev._id; // corretto // entrambi sono equivalenti obj.set('left', 70); obj.set({ left: 70 }); prev.set('left', 70); // undefined non è una funzione prev.set({ // undefined non è una funzione left: 70 }); prev.left = 70; // corretto, anche se non cambierà nulla sul tavolo });
Per i campi asincroni degli oggetti Roll20 carattere e handout (note
,gmnotes
, ebio
), il parametroprev
non conterrà i dati necessari. (Invece avrà un identificatore numerico usato dal sistema.) Se hai bisogno di accedere al valore precedente di uno di questi campi, dovrai tenerne traccia tu stesso:
on('ready', function() { if (!state.example) state.example = { bioCache: {} }; }); on('change:character:bio', function(obj, prev) { obj.get('bio', function(text) { state.example.bioCache[obj.id] = text; // do stuff... if (shouldRevertBio()) { obj.set('bio', state.example.bioCache[obj.id]); } }); });
onSheetWorkerCompleted
Parameters
CALLBACK(Function) The function that will be called when the current 'stack' of Sheet Worker Scripts completes.
Returns
(Void)
Examples
This function is intended to be called prior to setWithWorker. The callback
function will be called only once.
var myCharacter = ..., mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0]; onSheetWorkerCompleted(function() { var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0]; // fare qualcosa con calculatedAttr.get('current'); }); mySourceAttr.setWithWorker({ current: 5 });
playerIsGM
Parametri
PLAYER_ID(String) L'id dell'oggetto Roll20 giocatore da controllare.
Restituzioni
true
se il giocatore ha attualmente i permessi di GM, ofalse
altrimenti.
Esempi
Questa funzione è particolarmente utile per limitare i comandi Mod (API) all'uso da parte del GM.
on('chat:message', function(msg) { if (msg.type == 'api') return; if (msg.content.indexOf('!playercommand') === 0) { // ... } else if (msg.content.indexOf('!gmcommand') === 0) { if (!playerIsGM(msg.playerid)) return; // ... } });
playJukeboxPlaylist
Parameters
PLAYLIST_ID(String) The id of the playlist to start playing.
Returns
(Void)
Examples
var playlists = JSON.parse(Campaign().get('jukeboxfolder')), myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName); playJukeboxPlaylist(myPlaylist.id);
randomInteger
Parameters
MAX(Number) The maximum number to return, inclusive.
Returns
Un intero casuale compreso tra 1 (incluso) e max
(incluso). Questa funzione ha una migliore distribuzione rispetto a Math.random()
, ed è raccomandata al suo posto. Questa funzione non utilizza la funzioneQuantum Rollutilizzata dal motore dei dadi, ma utilizza lo stesso algoritmo pseudorandom a cui il motore dei dadi si affida se Quantum Roll non è disponibile.
Esempi
Poiché questa funzione restituisce un numero intero da 1 amax
, è ideale per generare rapidamente il risultato di un lancio di dadi se non ha bisogno di tutta la forza del motore di dadidi Roll20.
var d20Result = randomInteger(20); // approssimativamente equivalente al lancio di un dado a 20 facce
sendChat Asynchronous
Parametri
SPEAKINGAS(String) Il nome da allegare al messaggio inviato. Se speakingAs ha il formato player|player_id o character|character_id, il messaggio verrà inviato come quel giocatore o personaggio. Altrimenti, il messaggio utilizzerà il nome fornito come se un GM avesse utilizzato il comando /as.MESSAGE(String) Il messaggio da inviare nella chat.CALLBACK(Function, opzionale) Se viene specificato un callback, il risultato del messaggio nella chat verrà passato ad esso anziché apparire nella chat. Il parametro del metodo di callback è un array di oggetti messaggio.OPTIONS(Oggetto, opzionale) Se options.noarchive è true, il messaggio non verrà aggiunto all'archivio della chat. Se options.use3d è true, i lanci di dadi nel messaggio utilizzeranno la funzione dei dadi 3D. Le opzioni non sono applicabili se è specificato il callback.
Restituzioni
(Vuoto)
Esempi
sendChat('Esempio', 'Questo è un semplice esempio');
Può facilmente scrivere del codice per inviare un messaggio come lo stesso giocatore o personaggio che ha attivato un eventochat:message.
on('chat:message', function(msg) { var character = findObjs({ type: 'character', name: msg.who })[0], player = getObj('player', msg.playerid), message = ' ha detto qualcosa'; if (character) sendChat('character|'+character.id, character.get('nome')+messaggio); altrimenti sendChat('player|'+player.id, player.get('displayname')+messaggio); });
Il parametrocallback
è utile se deve sfruttare il motore di dadidi Roll20. Non è necessario un valorespeakingAs
quando utilizza il callback, poiché il messaggio non apparirà comunque nella chat.
sendChat('', '/r 2d20k1+'+strengthMod, function(ops) { var msg = ops[0]; // ... });
options.noarchive
è stato progettato principalmente per inviare ai giocatori i menu realizzati con i pulsanti di comando APIsenza intasare la cronologia della chat.
sendChat('System', '[Cancella modifiche](!clear)\n[Aggiungi piastrella](!add)\n[Visualizza campione](!view)\n[Salva layout](!save)', null, { noarchive: true });
inviarePing
Parametri
LEFT(Numero) La coordinata x in cui posizionare il ping.TOP(Numero) La coordinata y in cui posizionare il ping.PAGE_ID(Stringa) L'id dell'oggetto pagina Roll20 in cui posizionare il ping.PLAYER_ID(Stringa, opzionale) Il ping utilizzerà il colore del giocatore specificato. Se player_id è omesso, il ping sarà giallo.MOVEALL(booleano, opzionale) Se moveAll è vero, tutti i giocatori della pagina appropriata avranno la loro vista centrata sul ping.
Nota:In questo momento, solo i GM avranno le loro viste centrate semoveAll
èvero
. Questo comportamento è documentatoqui
Restituzioni
(Vuoto)
Esempi
on('chat:message', function(msg) { var obj; if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) { if (!msg.selected) return; obj = getObj(msg.selected[0]._type, msg.selected[0]._id); sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true); // centra tutti sul token selezionato } }; // centra tutti sul token selezionato. });
spawnFx
Parametri
LEFT(Numero) La coordinata x per posizionare l'emettitore di particelle.TOP(Numero) La coordinata y per posizionare l'emettitore di particelle.TYPE(Stringa) Il tipo di emettitore di particelle da posizionare. Per gli effetti incorporati, questo dovrebbe essere "tipo-colore", dove il tipo è uno dei seguenti: bomba, gorgogliare, bruciare, scoppiare, esplodere, brillare, missile o nova e il colore è uno dei seguenti: acido, sangue, fascino, morte, fuoco, gelo, santo, magia, melma, fumo o acqua. Per gli effetti personalizzati, questo deve essere l'id dell'oggetto FX Roll20. Nota: i tipi beam, breath e splatter non possono essere utilizzati con spawnFx. Vedere invece spawnFxBetweenPoints.PAGE_ID(String, opzionale) L'id dell'oggetto pagina Roll20 su cui posizionare l'emettitore di particelle. Se omesso, verrà invece utilizzato Campaign().get('playerpageid').
Restituzioni
(Vuoto)
Esempi
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxTraPunti
Parametri
START(Oggetto) Il punto di partenza dell'emettitore di particelle. Il punto deve essere nel formato { x: numero, y: numero }.END(Oggetto) Il punto finale dell'emettitore di particelle. Il punto deve essere nel formato { x: numero, y: numero }.TYPE(String) Il tipo di emettitore di particelle da posizionare. Per gli effetti incorporati, questo dovrebbe essere "tipo-colore", dove il tipo è uno dei seguenti: raggio, bomba, soffio, gorgogliare, bruciare, scoppiare, esplodere, brillare, missile, nova o schizzare e il colore è uno dei seguenti: acido, sangue, fascino, morte, fuoco, gelo, santo, magia, melma, fumo o acqua. Per gli effetti personalizzati, questo dovrebbe essere l'id dell'oggetto FX Roll20.PAGE_ID(String, opzionale) L'id della pagina dell'oggetto Roll20 su cui posizionare l'emettitore di particelle. Se omesso, verrà invece utilizzato Campaign().get('playerpageid').
Restituzioni
(Vuoto)
Esempi
spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');
spawnFxConDefinizione
Parametri
SINISTRA(Numero) La coordinata x per posizionare l'emettitore di particelle.TOP(Numero) La coordinata y per posizionare l'emettitore di particelle.DEFINIZIONE(Oggetto) Le caratteristiche dell'emettitore di particelle da posizionare. Per un elenco di proprietà possibili e per le proprietà dei tipi di emettitori di particelle e dei colori predefiniti, consulti la sezione FX personalizzati. Vedere la Libreria FX per alcuni effetti personalizzati che gli utenti di Roll20 hanno ideato.PAGE_ID(String, opzionale) L'id della pagina dell'oggetto Roll20 su cui posizionare l'emettitore di particelle. Se omesso, verrà invece utilizzato Campaign().get('playerpageid').
Restituzioni
(Vuoto)
Esempi
// questi due sono equivalenti spawnFx(1400, 1400, 'bubbling-acid'); spawnFxWithDefinition(1400, 1400, { maxParticles: 200, size: 15, sizeRandom: 3, lifeSpan: 20, lifeSpanRandom: 5, velocità: 7, velocitàRandom: 2, gravità: { x: 0.01, y: 0.65 }, angolo: 270, angoloRandom: 35, emissionRate: 1, startColour: [0, 35, 10, 1], startColourRandom: [0, 10, 10, 0.25], endColour: [0, 75, 30, 0], endColourRandom: [0, 20, 20, 0] });
stopJukeboxPlaylist
Parametri
Nessun parametro
Restituzioni
(Vuoto)
Esempi
stopJukeboxPlaylist();
toBack
Parametri
OBJ(oggetto Roll20) L'oggetto Roll20 da inviare al retro del suo livello.
Restituzioni
(Vuoto)
Esempi
on('chat:message', function(msg) { if (msg.type === 'api' && msg.content === '!toback' && msg.selected) { _.each(msg.selected, (s) => { toBack(getObj(s._type, s._id)); }); }. });
toFront
Parametri
OBJ(oggetto Roll20) L'oggetto Roll20 da portare davanti al suo livello.
Restituzioni
(Vuoto)
Esempi
on('ready', function() { on('add:graphic', function(obj) { toFront(obj); }); });