API: Funktionsdokumentation

Globale Variablen

_ (Unterstrich)

Dies ist das Namespace-Objekt für die Underscore.js-Bibliothek. Underscore verfügt über viele Funktionen zur Sammlungsmanipulation.

state

Die Eigenschaften des State-Objekts bleiben zwischen Spielsitzungen bestehen. Dasselbe Zustandsobjekt wird auch zwischen allen Mod (API)-Skripten in einer Kampagne geteilt, daher wird dringend empfohlen, deinen Fußabdruck beim Schreiben von Werten in den Zustand so weit wie möglich zu minimieren, um Namenskonflikte zu vermeiden. Hinweis: Der State wird mit JSON serialisiert, also kannst du keine Funktionen oder Objekte mit zyklischen Referenzen speichern.

Globale Funktionen

Kampagne

Parameter

Keine Parameter

Gibt zurück

Das Roll20-Objekt der Singleton-Kampagne.

Beispiele

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

createObj

Parameter

TYPE(String) Der Typ des Roll20-Objekts, das erstellt werden soll. Es dürfen nur ‚Grafik‘, ‚Text‘, ‚Pfad‘, ‚Charakter‘, ‚Fähigkeit‘, ‚Attribut‘, ‚Handout‘, ‚Rolltable‘, ‚Tableitem‘ und ‚Makro‘ erstellt werden.ATTRIBUTES(Object) Die Anfangswerte, die für die Eigenschaften des Roll20-Objekts verwendet werden sollen.

Kehrt zurück

Das erstellte Roll20-Objekt.

Beispiele

Wenn du ein Roll20-Objekt erstellst, das ein übergeordnetes Objekt hat (zum Beispiel ein Attribut-Roll20-Objekt, das zu einem Roll20-Charakterobjekt gehört), musst du die ID des übergeordneten Objekts in attributes angeben.

on('add:character', function(obj) {
 createObj('attribut', {
 name: 'Stärke',
 current: 0,
 max: 30,
 characterid: obj.id
 });
});

Beim Erstellen eines Pfad-Roll20-Objekts musst du einen Wert für die schreibgeschützte Eigenschaft _path angeben. Dies ist eine Ausnahme von der Regel, die verhindert, dass du beim Erstellen von Roll20-Objekten den Wert von schreibgeschützten Eigenschaften festlegst.

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

Beim Erstellen eines Notiz-Roll20-Objekts kannst du zum Zeitpunkt der Erstellung weder Text noch SL-Notizen festlegen.

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

Parameter

CALLBACK(Funktion) Eine Prädikatfunktion zum Testen aller Roll20-Objekte. Die Rückruffunktion erhält ein Roll20-Objekt als Parameter und sollte entweder true (für Roll20-Objekte, die im Rückgabewert von filterObjs enthalten sind) oder false (für alle anderen Roll20-Objekte) zurückgeben.

Gibt zurück

Ein Array von Roll20-Objekten, die den Prädikatstest bestanden haben.

Beispiele

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+$/.test(obj.get('name'));
});

findObjs

Parameter

EIGENSCHAFTEN(Object) Eine Sammlung von Schlüssel:Wert-Paaren zum Abgleichen mit Roll20-Objekten in der Kampagne.OPTIONEN(Object, optional) Wenn optionen.caseInsensitive wahr ist, wird bei Zeichenfolgenvergleichen zwischen Roll20-Objekten und Eigenschaften die Groß-/Kleinschreibung nicht beachtet.

Gibt zurück

Ein Array von Roll20-Objekten mit Eigenschaften, die mitAttributenübereinstimmen.

Beispiele

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

getAllObjs

Parameter

Keine Parameter

Gibt zurück

Ein Array aller Roll20-Objekte in der Kampagne.

Beispiele

var everything = getAllObjs();

getAttrByName

Parameter

CHARACTER_ID(String) Die ID des Roll20-Charakterobjekts, das dem Attribut-Roll20-Objekt übergeordnet ist, dessen Wert du festlegen möchtest.ATTRIBUTNAME(String) Der Name des Attribut-Roll20-Objekts, dessen Wert du festlegen möchtest.WERTTYP(String, optional) Entweder „current“ oder „max“ (standardmäßig „current“, wenn weggelassen).

Gibt zurück

DieaktuelleodermaxEigenschaft des entsprechenden Attributs. Wenn die gewünschte Eigenschaft nicht festgelegt ist, wird stattdessen der im Charakterbogen angegebene Standardwert (falls vorhanden) verwendet.

Beispiele

var charakter = getMyCharacter(),
 stärke = getAttrByName(character.id, 'strength'),
 stärke_max = getAttrByName(character.id, 'strength', 'max');

getObj

Parameter

TYP(String) Der Typ des Roll20-Objekts, der abgerufen werden soll.ID(String) Die eindeutige ID für das abzurufende Roll20-Objekt.

Das angegebene Roll20-Objekt.

Das angegebene Roll20-Objekt.

Beispiele

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

log

Parameter

NACHRICHT (variiert) Die Nachricht, die in die Mod (API)-Konsole gepostet werden soll. Der Nachrichten-Parameter wird in einen String mit JSON.stringify umgewandelt.

Gibt zurück

(Void)

Beispiele

on('chat:message', function(msg) {
    log('Nachricht empfangen von:');
    log(getObj('player', msg.playerid));
});

„Nachricht empfangen von:“
{"_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":""}

an

Parameter

EREIGNIS(String) Es gibt fünf Ereignistypen: ready, change, add, destroy, chat. Mit Ausnahme von ready müssen alle Ereignistypen auch mit einem Objekttyp gepaart werden. Im Chat ist dies immer Nachricht. Für alles andere ist dies die Type-Eigenschaft eines Roll20-Objekts. Zusätzlich zum Objekttyp können Changeevents optional auch eine Eigenschaft des angegebenen Roll20-Objekts angeben, das überwacht werden soll. Die 2-3 Teile des Ereignisses (Typ, Objekt und optional Eigenschaft) werden durch Doppelpunkte getrennt. Zu den gültigen Ereigniszeichenfolgen gehören unter anderem „ready“, „chat:message“, „change:graphic“, „change:campaign:playerpageid“, „add:character“ und „destroy:handout“.CALLBACK( Funktion) Die Funktion, die aufgerufen wird, wenn das angegebene Ereignis ausgelöst wird. Die übergebenen Parameter hängen vom Ereignistyp ab: Ready-Ereignisse haben keine Rückrufparameter. Change-Ereignisse haben einen obj-Parameter, der eine Referenz auf das Roll20-Objekt ist, wie es nach der Änderung existiert, und einen prev-Parameter, der ein einfaches altes JavaScript-Objekt ist mit Eigenschaften, die mit dem Roll20-Objekt vor dem Änderungsereignis übereinstimmen. Add-Ereignisse haben einen obj-Parameter, der eine Referenz auf das neue Roll20-Objekt ist. Destroy-Ereignisse haben einen obj-Parameter, der eine Referenz auf das nicht mehr vorhandene Roll20-Objekt ist.chat Ereignisse verfügen über einen msg-Parameter, der die Details der Nachricht enthält, die an den Chat gesendet wurde.

Gibt zurück

(Leere)

Beispiele

Ereignisse werden in der Reihenfolge ausgelöst, in der sie registriert wurden, und zwar von der höchsten zur unspezifischsten. In diesem Beispiel führt eine Änderung der Eigenschaftlefteines grafischen Roll20-Objekts dazu, dassfunction3aufgerufen wird, gefolgt vonfunction1und dannfunction2.

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

addEreignisse versuchen, für Roll20-Objekte auszulösen, die sich bereits in der Kampagne befinden, wenn eine neue Sitzung beginnt. Um dieses Verhalten zu verhindern, können Sie mit der Registrierung IhresaddEreignisses warten, bis dasready-Ereignis ausgelöst wird.

on('add:graphic', function(obj) {
    // Wenn die Sitzung beginnt, wird diese Funktion für jede Grafik in der Kampagne aufgerufen
    // Diese Funktion wird auch immer dann aufgerufen, wenn ein neues grafisches Roll20-Objekt erstellt wird
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // Diese Funktion wird *nur* aufgerufen, wenn ein neues grafisches Roll20-Objekt erstellt wird, nicht für solche, die bereits erstellt wurden existieren
    });
});

Der pre-Parameter für change-Events ist kein Roll20-Objekt, sondern ein einfaches JavaScript-Objekt. Daher kannst du die Funktionen get oder set nicht verwenden, und du kannst die führenden Unterstriche bei schreibgeschützten Eigenschaften nicht weglassen.

on('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // alle drei sind gleichwertig
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id,        // undefined
        id5 = prev.get('id'), // undefined ist keine Funktion
        id6 = prev._id;       // korrekt

    // beide sind gleichwertig
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined ist keine Funktion
    prev.set({            // undefined ist keine Funktion
        left: 70
    });
    prev.left = 70;       // korrekt, obwohl sich dadurch auf dem Spieltisch nichts ändert
});

Bei den asynchronen Feldern der Roll20-Objekte „Charakter“ und „Notiz“ (notes, gmnotes und bio) enthält der Parameter prev nicht die Daten, die du brauchst. (Stattdessen wird es eine vom System verwendete numerische Kennung haben.) Wenn du auf den vorherigen Wert eines dieser Felder zugreifen musst, musst du selbst den Überblick behalten:

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

Parameter

CALLBACK(Funktion) Die Funktion, die aufgerufen wird, wenn der aktuelle „Stapel“ von Sheet Worker-Skripten abgeschlossen ist.

Kehrt zurück

(Void)

Beispiele

Diese Funktion soll vor setWithWorker aufgerufen werden. Die Callback-Funktion wird nur einmal aufgerufen.

var berechnetesAttribut = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];

SpielerIstGM

Parameter

PLAYER_ID(String) Die ID des zu überprüfenden Spieler-Roll20-Objekts.

Kehrt zurück

true, wenn der Spieler derzeit über SL-Berechtigungen verfügt, oder false andernfalls.

Beispiele

Diese Funktion ist besonders nützlich, um Mod (API)-Befehle auf die Verwendung durch den SL zu beschränken.

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

Parameter

PLAYLIST_ID(String) Die ID der Playlist, deren Wiedergabe gestartet werden soll.

Kehrt zurück

(Void)

Beispiele

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    meineWiedergabeliste = _.find(playlists, (ordner) => _.isObject(ordner) && ordner.n === meineWiedergabelistenName);
playJukeboxPlaylist(meineWiedergabeliste.id);

randomInteger

Parameter

MAX(Number) Die maximale Anzahl, die zurückgegeben werden soll, einschließlich.

Kehrt zurück

Eine zufällige Ganzzahl zwischen 1 (einschließlich) und max (einschließlich). Diese Funktion hat eine bessere Verteilung als Math.random() und wird empfohlen. Diese Funktion nutzt nicht die FunktionQuantum Roll, die von der Würfel-Engine verwendet wird, sondern verwendet denselben pseudozufälligen Algorithmus, auf den die Würfel-Engine zurückgreift, wenn Quantum Roll nicht verfügbar ist.

Beispiele

Da diese Funktion eine Ganzzahl von 1 bis max zurückgibt, ist sie ideal für die schnelle Generierung eines Würfelergebnisses, wenn du nicht die volle Leistung der Würfel-Engine von Roll20 benötigst.

var d20Ergebnis = randomInteger(20); // entspricht in etwa dem Würfeln eines 20-seitigen Würfels

sendChat Asynchron

Parameter

SPEAKINGAS(String) Der Name, der der gesendeten Nachricht hinzugefügt werden soll. Wenn „speakingAs“ das Format „player|player_id“ oder „character|character_id“ hat, wird die Nachricht zu diesem Spieler oder Charakter gesendet. Sonst verwendet die Nachricht den gegebenen Namen, als ob ein SL den Befehl /as benutzt hätte.MESSAGE(String) Die Nachricht, die in den Chat gesendet wird.CALLBACK(Funktion, optional) Wenn callback angegeben ist, wird das Ergebnis der Chat-Nachricht verwendet und weitergegeben, anstatt im Chat anzuzeigen. Der Parameter der callback-Methode ist ein Array von Nachrichtenobjekten.OPTIONS(Objekt, optional) Wenn options.noarchive wahr ist, wird die Nachricht nicht zum Chatarchiv hinzugefügt. Wenn „options.use3d“ „true“ ist, benutzt die Nachricht die 3D-Würfel-Funktion für Würfe. Optionen sind nicht anwendbar, wenn callback angegeben ist.

Kehrt zurück

(Void)

Beispiele

sendChat('Example', 'Dies ist ein einfaches Beispiel.');

Du kannst ganz einfach Code schreiben, um eine Nachricht als derselbe Spieler oder Charakter zu senden, der ein Chat:Nachricht-Ereignis ausgelöst hat.

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

 if (character) sendChat('character|'+character.id, character.get('name')+message);
 else sendChat('player|'+player.id, player.get('displayname')+message);
});

Der callback-Parameter ist nützlich, wenn du die Würfel-Engine von Roll20 nutzen musst. Beim Verwenden des Rückrufs ist der speakingAs-Wert nicht notwendig, da die Nachricht sowieso nicht im Chat erscheint.

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

options.noarchive ist in erster Linie dafür gedacht, Spielern Menüs zu senden, die aus API-Befehlsschaltflächen bestehen, ohne ihren Chatverlauf zu verstopfen.

sendChat('System', '[Änderungen löschen](!clear)\n[Kachel hinzufügen](!add)\n[Beispiel anzeigen](!view)\n[Layout speichern](!save)', null, { noarchive: true });

sendPing

Parameter

LEFT(Number) Die X-Koordinate, an der der Ping platziert werden soll.TOP(Number) Die Y-Koordinate, an der der Ping platziert werden soll.PAGE_ID(String) Die ID des Roll20-Objekts der Seite, auf dem der Ping platziert werden soll.PLAYER_ID(String, optional ) Der Ping verwendet die Farbe des angegebenen Spielers. Wenn „player_id“ weggelassen wird, ist der Ping gelb.MOVEALL(Boolean, optional) Wenn „moveAll“ wahr ist, werden die Ansichten aller Spieler auf der entsprechenden Seite auf den Ping zentriert.

Hinweis: Derzeit werden nur die Anzeigen von SLs zentriert, wenn moveAll true ist. Dieses Verhalten ist hier dokumentiert.

Kehrt zurück

(Void)

Beispiele

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); // alle auf das ausgewählte Token zentrieren
    }
});

spawnFx

Parameter

LEFT(Number) Die x-Koordinate zum Platzieren des Partikelemitters.TOP(Number) Die y-Koordinate zum Platzieren des Partikelemitters.TYPE(String) Der Typ des zu platzierenden Partikelemitters. Für integrierte Effekte sollte dies „Typ-Farbe“ sein, wobei Typ einer der folgenden sein kann: Bombe, Sprudeln, Brennen, Bersten, Explodieren, Glühen, Rakete oder Nova, und Farbe eine der folgenden sein kann: Säure, Blut, Zauber, Tod, Feuer, Frost, heilig, Magie, Schleim, Rauch oder Wasser. Für benutzerdefinierte Effekte sollte dies die ID des FX Roll20-Objekts sein. Hinweis: Die Typen „Beam“, „Breath“ und „Splatter“ können nicht mit spawnFx verwendet werden. Siehe stattdessen spawnFxBetweenPoints.PAGE_ID(String, optional) Die ID des Roll20-Seitenobjekts, auf dem der Partikelemitter platziert werden soll. Wenn es weggelassen wird, wird stattdessen Campaign().get('playerpageid') verwendet.

Kehrt zurück

(Void)

Beispiele

spawnFx(1400, 1400, 'bubbling-acid');

spawnFxBetweenPoints

Parameter

START(Objekt) Der Startpunkt für den Partikelemitter. Der Punkt sollte das Format { x: Zahl, y: Zahl } haben.END(Object) Der Endpunkt für den Partikelemitter. Der Punkt sollte das Format { x: Zahl, y: Zahl } haben.TYPE(String) Der Typ des zu platzierenden Partikelemitters. Für integrierte Effekte sollte dies "Typ-Farbe" sein, wobei Typ einer der folgenden sein kann: Strahl, Bombe, Atem, Sprudeln, Brennen, Platzen, Explodieren, Leuchten, Rakete, Nova oder Spritzer, und Farbe eine der folgenden sein kann: Säure, Blut, Zauber, Tod, Feuer, Frost, heilig, Magie, Schleim, Rauch oder Wasser. Für benutzerdefinierte Effekte sollte dies die ID des FX-Roll20-Objekts sein. PAGE_ID(String, optional) Die ID des Seiten-Roll20-Objekts, auf dem der Partikelemitter platziert werden soll. Wenn es weggelassen wird, wird stattdessen Campaign().get('playerpageid') verwendet.

Kehrt zurück

(Void)

Beispiele

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

spawnFxWithDefinition

Parameter

LEFT(Number) Die x-Koordinate zum Platzieren des Partikelemitters.TOP(Number) Die y-Koordinate zum Platzieren des Partikelemitters.DEFINITION(Object) Die Eigenschaften des zu platzierenden Partikelemitters. Eine Liste möglicher Eigenschaften sowie die Eigenschaften der standardmäßigen Partikelemittertypen und -farben finden Sie unter „Benutzerdefinierte Effekte“. In der FX-Bibliothek finden Sie einige benutzerdefinierte Effekte, die Roll20-Benutzer erstellt haben. PAGE_ID(String, optional) Die ID des Roll20-Seitenobjekts, auf dem der Partikelemitter platziert werden soll. Wenn es weggelassen wird, wird stattdessen Campaign().get('playerpageid') verwendet.

Kehrt zurück

(Void)

Beispiele

// diese beiden sind äquivalent
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,
    emissionsRate: 1,
    startColor: [0, 35, 10, 1],
    startColorRandom: [0, 10, 10, 0,25],
    endColor: [0, 75, 30, 0 ],
    endColorRandom: [0, 20, 20, 0]
});

stopJukeboxPlaylist

Parameter

Keine Parameter

Kehrt zurück

(Void)

Beispiele

stopJukeboxPlaylist();

nach ganz hinten

Parameter

OBJ(Roll20-Objekt) Das Roll20-Objekt, das an die Rückseite seiner Ebene gesendet werden soll.

Kehrt zurück

(Void)

Beispiele

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg .selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});

nach vorne

Parameter

OBJ(Roll20-Objekt) Das Roll20-Objekt, das an den Anfang seiner Ebene gebracht werden soll.

Kehrt zurück

(Void)

Beispiele

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