API: Documentazione delle funzioni

Roll20 mette a disposizione una serie di funzioni che non fanno parte del core JavaScript o di altre librerie.


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 è inoltre condiviso tra tutti gli script API in una campagna, quindi è vivamente consigliato minimizzare il numero di valori scritti nello stato per 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 alla console 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àattualeomaxdell'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(varies) Il messaggio da inviare alla console API. Il parametro message 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àleftdi un oggetto grafico Roll20 comporterà la chiamata della funzionefunction3, seguita dalla funzionefunction1e 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 parametropreper gli eventichangenon è un oggetto Roll20, ma un semplice oggetto JavaScript. Pertanto, non può utilizzare le funzionigetosete 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 parametroprevnon 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

truese il giocatore ha attualmente i permessi di GM, ofalsealtrimenti.

Esempi

Questa funzione è particolarmente utile per limitare i comandi API all'uso di 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 valorespeakingAsquando 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);
    });
});
 
Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 6 su 11