API: Documentazione delle funzioni

Variabili globali

_ (Trattino basso)

Questo è l'oggetto namespace per Underscore.js . Underscore offre numerose funzioni per la manipolazione delle raccolte.

stato/Provincia

Le proprietà dell'oggetto di stato rimarranno invariate tra una sessione di gioco e l'altra. Lo stesso oggetto di stato è condiviso anche tra tutti gli script Mod (API) di una campagna, pertanto si raccomanda vivamente, quando si scrivono valori nello stato, di ridurre al minimo l'impronta per evitare conflitti di nomi. Nota: lo stato viene serializzato con JSON, pertanto non è possibile memorizzare funzioni o oggetti con riferimenti ciclici.

Funzioni globali

Campagna

Parametri

Nessun parametro

Resi

L'oggetto Roll20 della campagna singleton.

Esempi

var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('pagina', currentPageID);

creaOggetto

Parametri

TIPO(Stringa) Il tipo di oggetto Roll20 da creare. È possibile creare solo "grafica", "testo", "percorso", "carattere", "abilità", "attributo", "dispensa", "tabella a scorrimento", "voce di tabella" e "macro". ATTRIBUTI (Oggetto) I valori iniziali da utilizzare per le proprietà dell'oggetto Roll20.

Resi

L'oggetto Roll20 che è stato creato.

Esempi

Quando si crea un oggetto Roll20 che ha un oggetto padre (ad esempio, quando si crea un oggetto Roll20 attributo, che è un figlio di un oggetto Roll20 personaggio), è necessario fornire l'ID del padre negliattributi.

on('add:personaggio', function(obj) {
    createObj('attributo', {
        name: 'Strength',
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

Quando si crea un oggetto Roll20 percorso, è necessario fornire un valore per la proprietà di sola lettura_path. Si tratta di un'eccezione alla regola che impedisce di impostare il valore delle proprietà di sola lettura durante la creazione di oggetti Roll20.

createObj('path', {
    left: 7000,
    top: 140,
    width: 140,
    height: 140,
    livello: 'oggetti',
    percorso: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

Quando si crea un oggetto Roll20 da distribuire, non è possibile impostare il testo o le note del GM al momento della 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'
});

filtraObj

Parametri

CALLBACK (Funzione) Una funzione predicato per verificare tutti gli oggetti Roll20. La funzione di callback riceve un oggetto Roll20 come parametro e dovrebbe restituire true (per gli oggetti Roll20 che saranno inclusi nel valore restituito da filterObjs) o false (per tutti gli altri oggetti Roll20).

Resi

Una serie di oggetti Roll20 che hanno superato il test del predicato.

Esempi

var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));
});

trovaOggetti

Parametri

ATTRIBUTI (Oggetto) Una raccolta di coppie chiave:valore da abbinare agli oggetti Roll20 nella campagna. OPZIONI (Oggetto, opzionale) Se options.caseInsensitive è vero, i confronti tra stringhe degli oggetti Roll20 e gli attributi non terranno conto delle maiuscole/minuscole.

Resi

Una serie di oggetti Roll20 con proprietà che corrispondonoagli attributi.

Esempi

var npcs = findObjs({ type: 'character', controlledby: '' });

recuperaTuttiGliOggetti

Parametri

Nessun parametro

Resi

Una serie di tutti gli oggetti Roll20 presenti nella campagna.

Esempi

var tutto = getAllObjs();

getAttrByName

Parametri

CHARACTER_ID(Stringa) L'ID dell'oggetto Roll20 del personaggio che è il genitore dell'oggetto Roll20 dell'attributo di cui si desidera il valore. ATTRIBUTE_NAME(Stringa) Il nome dell'oggetto Roll20 dell'attributo di cui si desidera ottenere il valore. VALUE_TYPE(Stringa, opzionale) "current" o "max" (il valore predefinito è "current" se omesso).

Resi

La proprietàcurrentomaxdell'attributo appropriato. Se la proprietà desiderata non è impostata, verrà utilizzato il valore predefinito specificato nella scheda dei personaggi (se esiste un valore predefinito).

Esempi

var personaggio = getMyPersonaggio(),
    forza = getAttrByName(personaggio.id, 'forza'),
    forza_max = getAttrByName(personaggio.id, 'forza', 'max');

getObj

Parametri

TIPO (Stringa) Il tipo di oggetto Roll20 da ottenere. ID (Stringa) L'ID univoco dell'oggetto Roll20 da ottenere.

Resi

L'oggetto Roll20 specificato.

Esempi

on('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

registro

Parametri

MESSAGGIO (varia) Il messaggio da inviare alla console Mod (API). Il parametro del messaggio verrà convertito in una stringa con JSON.stringify.

Resi

(Nullo)

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":""}

il

Parametri

EVENT(String) Esistono cinque tipi di eventi: readychangeadddestroychat. Ad eccezione di ready, tutti i tipi di evento devono essere associati a un tipo di oggetto. Per la chat, si tratta sempre di messaggi. Per tutto il resto, questa è la proprietà di tipo di un oggetto Roll20. Oltre al tipo di oggetto, gli eventi di modifica possono anche specificare facoltativamente una proprietà dell'oggetto Roll20 specificato da monitorare. Le 2-3 parti dell'evento (tipo, oggetto e, facoltativamente, proprietà) sono separate da due punti. Pertanto, le stringhe di evento valide includono, ma non sono limitate a, "ready", "chat:message", "change:graphic", "change:campaign:playerpageid", "add:character" e "destroy:handout". CALLBACK(Funzione) La funzione che verrà richiamata quando si verifica l'evento specificato. I parametri trasmessi 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 semplice oggetto JavaScript 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 non più esistente. Gli eventi chat hanno un parametro msg, che contiene i dettagli del messaggio inviato alla chat.

Resi

(Nullo)

Esempi

Gli eventi vengono attivati nell'ordine in cui sono stati registrati, dal più specifico al meno specifico. In questo esempio, una modifica alla proprietàsinistradi un oggetto grafico Roll20 comporterà la chiamatadella funzione3, seguita dallafunzione1e poidalla funzione2.

on('change:graphic', function1);
on('change:graphic', function2);
on('change:graphic:left', function3);

Gli eventi aggiuntitenteranno di attivarsi per gli oggetti Roll20 già presenti nella campagna all'avvio di una nuova sessione. Per evitare questo comportamento, è possibile attendere che l'eventoreadyvenga attivato prima di registrare l'eventoadd.

on('add:graphic', function(obj) {
    // All'avvio della sessione, questa funzione verrà richiamata per ogni elemento grafico della campagna
    // Questa funzione verrà richiamata anche ogni volta che viene creato un nuovo oggetto grafico Roll20
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // Questa funzione verrà richiamata *solo* quando viene creato un nuovo oggetto grafico Roll20, non per quelli già esistenti
    });
});

Il parametropreper gli eventidi modificanon è un oggetto Roll20, ma un semplice oggetto JavaScript tradizionale. Pertanto, non è possibile utilizzare le funzionigetoset, né 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,        // undefined
        id5 = prev.get('id'), // undefined 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 relativi ai personaggi e aimateriali di gioco, il parametroprevnon conterrà i dati richiesti. (Verrà invece utilizzato un identificatore numerico dal sistema.) Se è necessario accedere al valore precedente di uno di questi campi, sarà necessario tenerne traccia autonomamente:

on('ready', function() {
    if (!state.example) state.example = { bioCache: {} };
});

on('change:personaggio:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text;

        // eseguire operazioni...

        if (shouldRevertBio()) {
            obj.set('bio', state.example.bioCache[obj.id]);
        }
    });
});

onSheetWorkerCompleted

Parametri

CALLBACK(Funzione) La funzione che verrà richiamata al completamento dell'attuale "stack" di script di sviluppatori di schede.

Resi

(Nullo)

Esempi

Questa funzione deve essere richiamata prima di setWithWorker. La funzionedi callbackverrà richiamata una sola volta.

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];
    // eseguire un'operazione con calculatedAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

giocatoreÈGM

Parametri

PLAYER_ID(Stringa) L'ID dell'oggetto Roll20 del giocatore da controllare.

Resi

verose il giocatore dispone attualmente dei permessi GM, altrimentifalso.

Esempi

Questa funzione è particolarmente utile per limitare i comandi Mod (API) all'uso da parte dei GM.

on('chat:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } altrimenti se (msg.content.indexOf('!gmcommand') === 0) {
        se (!playerIsGM(msg.playerid)) restituisci;
        // ...
    
);

playJukeboxPlaylist

Parametri

PLAYLIST_ID(Stringa) L'ID della playlist da riprodurre.

Resi

(Nullo)

Esempi

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);

numero intero casuale

Parametri

MAX(Numero) Il numero massimo da restituire, compreso.

Resi

Un numero intero casuale compreso tra 1 (incluso) emax(incluso). Questa funzione presenta una distribuzione migliore rispetto aMath.random() ed è consigliabile utilizzarla al suo posto. Questa funzione non utilizza il Quantum Roll utilizzata dal motore dei dadi, ma impiega lo stesso algoritmo pseudocasuale a cui ricorre il motore dei dadi quando Quantum Roll non è disponibile.

Esempi

Poiché questa funzione restituisce un numero intero compreso tra 1 emax, è ideale per generare rapidamente il risultato di un lancio di dadi se non è necessaria la piena potenza del motore di lancio di dadi di Roll20. ..

var d20Result = randomInteger(20); // approssimativamente equivalente al lancio di un dado a 20 facce

sendChat Asincrono

Parametri

SPEAKINGAS(Stringa) Il nome da allegare al messaggio inviato. Se parlando come è nel formato player|player_id o personaggio|character_id, il messaggio verrà inviato come quel giocatore o personaggio. In caso contrario, il messaggio utilizzerà il nome specificato come se un GM avesse utilizzato il comando /as. MESSAGGIO (Stringa) Il messaggio da inviare alla chat. CALLBACK (Funzione, opzionale) Se viene specificato callback, il risultato del messaggio di chat verrà trasmesso a esso invece di apparire nella chat. Il parametro del metodo di callback è un array di oggetti messaggio. OPTIONS (Oggetto, opzionale) Se options.noarchive è vero, il messaggio non verrà aggiunto all'archivio della chat. Se options.use3d è impostato su true, i lanci di dadi nel messaggio utilizzeranno la funzione dei dadi 3D. Le opzioni non sono applicabili se è specificato il callback.

Resi

(Nullo)

Esempi

sendChat('Esempio', 'Questo è un semplice esempio.');

È possibile scrivere facilmente del codice per inviare un messaggio come lo stesso giocatore o personaggio che ha attivato un eventochat:message.

on('chat:message', function(msg) {
    var personaggio = findObjs({ type: 'character', name: msg.who })[0],
        player = getObj('player', msg.playerid),
        message = 'ha detto qualcosa';

    if (personaggio) sendChat('personaggio|'+personaggio.id, personaggio.get('nome')+messaggio);
    else sendChat('giocatore|'+giocatore.id, giocatore.get('nome visualizzato')+messaggio);
});

Il parametrocallbackè utile se si desidera sfruttare il motore di dadi di Roll20. motore dei dadi. Non è necessario specificare un valorespeakingAsquando si utilizza ilcallback, poiché il messaggio non apparirà comunque nella chat.

sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});

options.noarchiveè progettato principalmente per inviare ai giocatori menu creati da pulsanti di comando API senza intasare la cronologia della chat.

sendChat('Sistema', '[Cancella modifiche](!clear)\n[Aggiungi riquadro](!add)\n[Visualizza esempio](!view)\n[Salva layout](!save)', null, { noarchive: true });

inviaPing

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 Roll20 della pagina su cui posizionare il ping. PLAYER_ID(Stringa, facoltativo) Il ping utilizzerà il colore del giocatore specificato. Se player_id viene omesso, il ping sarà di colore giallo. MOVEALL (Boolean, opzionale) Se moveAll è vero, tutti i giocatori nella pagina appropriata avranno la visualizzazione centrata sul ping.

Nota:al momento, solo i GM avranno le loro visualizzazioni centrate semoveAllèvero. Questo comportamento è documentato qui

Resi

(Nullo)

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 segnalino 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, dovrebbe essere "tipo-colore", dove il tipo è uno tra bomba, bolle, bruciatura, scoppio, esplosione, bagliore, missile o nova e il colore è uno tra acido, sangue, incantesimo, morte, fuoco, gelo, sacro, magia, melma, fumo o acqua. o acqua. Per gli effetti personalizzati, questo dovrebbe essere l'ID dell'oggetto FX Roll20. Nota: i tipi beam, breath e splatter non possono essere utilizzati con spawnFx. Si prega di consultare spawnFxBetweenPoints. PAGE_ID(Stringa, facoltativo) L'ID dell'oggetto Roll20 della pagina su cui posizionare l'emettitore di particelle. Se omesso, verrà utilizzato invece Campaign().get('playerpageid').

Resi

(Nullo)

Esempi

spawnFx(1400, 1400, 'acido ribollente');

generazione di effetti tra punti

Parametri

START(Oggetto) Il punto di partenza per l'emettitore di particelle. Il punto deve essere nel formato { x: numero, y: numero }.END(Oggetto) Il punto finale per l'emettitore di particelle. Il punto deve essere nel formato { x: numero, y: numero }.TIPO(Stringa) Il tipo di emettitore di particelle da posizionare. Per gli effetti integrati, dovrebbe essere "tipo-colore", dove il tipo è uno tra raggio, bomba, alito, bolla, bruciatura, scoppio, esplosione, bagliore, missile, nova, o schizzo e il colore è uno tra acido, sangue, incantesimo, morte, fuoco, gelo, sacro, magia, melma, fumo o acqua. Per gli effetti personalizzati, questo dovrebbe essere l'ID dell'oggetto FX Roll20. PAGE_ID(String, opzionale) L'ID dell'oggetto Roll20 della pagina su cui posizionare l'emettitore di particelle. Se omesso, verrà utilizzato invece Campaign().get('playerpageid').

Resi

(Nullo)

Esempi

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

spawnFxWithDefinition

Parametri

LEFT(Numero) La coordinata x per posizionare l'emettitore di particelle.TOP(Numero) La coordinata y per posizionare l'emettitore di particelle.DEFINITION(Oggetto) Le caratteristiche dell'emettitore di particelle da posizionare. Si prega di consultare Custom FX per un elenco delle proprietà disponibili e delle proprietà dei tipi e dei colori predefiniti dell'emettitore di particelle. Si prega di consultare la Libreria FX per alcuni effetti personalizzati ideati dagli utenti di Roll20. PAGE_ID(Stringa, opzionale) L'ID dell'oggetto Roll20 della pagina su cui posizionare l'emettitore di particelle. Se omesso, verrà utilizzato invece Campaign().get('playerpageid').

Resi

(Nullo)

Esempi

// Questi due sono equivalenti
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxWithDefinition(1400, 1400, {
    maxParticles: 200,
    size: 15,
    sizeRandom: 3,
    lifeSpan: 20,
    lifeSpanRandom: 5,
    speed: 7,
    speedRandom: 2,
    gravity: { x: 0.01, y: 0.65 },
    angle: 270,
    angleRandom: 35,
    emissionRate: 1,
    startColour:       [0, 35, 10, 1],
    startColourRandom: [0, 10, 10, 0.25],
    endColour:         [0, 75, 30, 0],
    endColourRandom:   [0, 20, 20, 0]
});

Interrompere la riproduzione della playlist del jukebox

Parametri

Nessun parametro

Resi

(Nullo)

Esempi

interrompereJukeboxPlaylist();

Indietro

Parametri

OBJ(Oggetto Roll20) L'oggetto Roll20 da inviare sullo sfondo del proprio livello.

Resi

(Nullo)

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));
        });
    }
});

al fronte

Parametri

OBJ(Oggetto Roll20) L'oggetto Roll20 da portare in primo piano nel proprio livello.

Resi

(Nullo)

Esempi

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});