API: Funktionsdokumentation

Globale Variablen

_ (Unterstrich)

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

Zustand

Die Eigenschaften des Statusobjekts bleiben zwischen Spielsitzungen bestehen. Der gleiche Zustandsobjekt wird auch zwischen allen Mod (API) Skripten in einer Kampagne geteilt, daher wird dringend empfohlen, dass du beim Schreiben von Werten in den Zustand deinen Fußabdruck so weit wie möglich minimierst, um Namenskonflikten zu vermeiden. Hinweis: Der Status wird mit JSON serialisiert, sodass Sie keine Funktionen oder Objekte mit zyklischen Referenzen speichern können.

Globale Funktionen

Kampagne

Parameter

Keine Parameter

Kehrt 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 zu erstellenden Roll20-Objekts. Es dürfen nur „Grafik“, „Text“, „Pfad“, „Charakter“, „Fähigkeit“, „Attribut“, „Handout“, „Rollabletable“, „Tableitem“ und „Makro“ erstellt werden.ATTRIBUTES(Object) Das Anfangswerte, die für die Eigenschaften des Roll20-Objekts verwendet werden sollen.

Kehrt zurück

Das erstellte Roll20-Objekt.

Beispiele

Wenn Sie ein Roll20-Objekt erstellen, das über ein übergeordnetes Objekt verfügt (z. B. ein Attribut-Roll20-Objekt erstellen, das ein untergeordnetes Objekt eines Roll20-Zeichenobjekts ist), müssen Sie die ID des übergeordneten Objekts inattributesangeben.

on('add:character', function(obj) {
    createObj('attribute', {
        name: 'Strength',
        current: 0,
        max: 30,
        Characterid: obj.id
    });
} );

Beim Erstellen eines Pfad-Roll20-Objekts müssen Sie einen Wert für die schreibgeschützte Eigenschaft_pathangeben. Dies ist eine Ausnahme von der Regel, die verhindert, dass Sie beim Erstellen von Roll20-Objekten den Wert von schreibgeschützten Eigenschaften festlegen.

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

Beim Erstellen eines Handout-Roll20-Objekts können Sie zum Zeitpunkt der Erstellung weder Text noch gmnotes 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 empfängt 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.

Kehrt zurück

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

Beispiele

var tokenName = getMyTokenName(),
    doubleTokens = 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'));
});

findObjs

Parameter

ATTRIBUTES(Object) Eine Sammlung von Schlüssel:Wert-Paaren zum Abgleich mit Roll20-Objekten in der Kampagne.OPTIONS(Object, optional) Wenn options.caseInsensitive true ist, wird bei Zeichenfolgenvergleichen zwischen Roll20-Objekten und Attributen die Groß-/Kleinschreibung nicht beachtet.

Kehrt zurück

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

Beispiele

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

getAllObjs

Parameter

Keine Parameter

Kehrt zurück

Ein Array aller Roll20-Objekte in der Kampagne.

Beispiele

var everything = getAllObjs();

getAttrByName

Parameter

CHARACTER_ID(String) Die ID des Roll20-Zeichenobjekts, das dem Attribut-Roll20-Objekt übergeordnet ist, dessen Wert Sie festlegen möchten.ATTRIBUTE_NAME(String) Der Name des Attribut-Roll20-Objekts, dessen Wert Sie festlegen möchten.VALUE_TYPE(String, optional) Entweder „current“ oder „max“ (standardmäßig „current“, wenn weggelassen).

Kehrt zurück

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

Beispiele

var Character = getMyCharacter(),
    Strength = getAttrByName(character.id, 'strength'),
    Strength_max = getAttrByName(character.id, 'strength', 'max');

getObj

Parameter

TYPE(String) Der Typ des abzurufenden Roll20-Objekts. ID(String) Die eindeutige ID für das abzurufende Roll20-Objekt.

Kehrt zurück

Das angegebene Roll20-Objekt.

Beispiele

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

log

Parameter

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

Kehrt zurück

(Leere)

Beispiele

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

„Nachricht empfangen von:“
{“_d20userid“: „123456“, „_displayname“: „John Doe“, „lookingas“: „“, „_online“:true, „color“: „#885b68“, „_macrobar“ :“-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t“,showmacrobar“:true,“_id“:-J16Z-dRU5tleKiKOc0X“,_type:player“,_lastpage“:“}

an

Parameter

EVENT(String) Es gibt fünf Ereignistypen:readychangeadddestroychatMit Ausnahme von ready müssen alle Ereignistypen auch mit einem Objekttyp gepaart werden. Im Chat ist dies immer eine 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.

Kehrt 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 ParameterprefürChangeEreignisse ist kein Roll20-Objekt, sondern ein einfaches altes JavaScript-Objekt. Daher können Sie die Funktionengetodersetnicht verwenden und Sie können die führenden Unterstriche bei schreibgeschützten Eigenschaften nicht weglassen.

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

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

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

    prev.set('left', 70); // undefiniert ist keine Funktion
    prev.set({ // undefiniert ist keine Funktion
        left: 70
    });
    prev.left = 70; // richtig, ändert aber nichts an der Tischplatte
});

Für die asynchronen Felder von Charakter- und Handout-Roll20-Objekten (Notes,GmnotesundBio) enthält der ParameterPrevnicht die benötigten Daten. (Stattdessen wird vom System eine numerische Kennung verwendet.) Wenn Sie auf den vorherigen Wert eines dieser Felder zugreifen müssen, müssen Sie 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;

        // Sachen machen...

        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

(Leere)

Beispiele

Diese Funktion soll vor setWithWorker aufgerufen werden. Die FunktionCallbackwird nur einmal aufgerufen.

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

onSheetWorkerCompleted(function() {
    var berechnetAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // etwas mit berechneterAttr.get('current');
});
mySourceAttr.setWithWorker({ current: 5 });

SpielerIstGM

Parameter

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

Kehrt zurück

wahr, wenn der Spieler derzeit über GM-Berechtigungen verfügt, oderfalschandernfalls.

Beispiele

Diese Funktion ist besonders nützlich, um Mod (API) Befehle auf die Verwendung durch den Spielleiter 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

(Leere)

Beispiele

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && Folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.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, maximal(einschließlich). Diese Funktion hat eine bessere Verteilung alsMath.random()und wird darüber 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(maximalzurückgibt, ist sie ideal für die schnelle Generierung eines Würfelwurfergebnisses, wenn Sie nicht die volle Stärke derWürfel-Enginevon Roll20 benötigen.

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

sendChat Asynchron

Parameter

SPEAKINGAS(String) Der Name, der an die gesendete Nachricht angehängt werden soll. Wenn „speakingAs“ das Format „player|player_id“ oder „character|character_id“ hat, wird die Nachricht als dieser Spieler oder Charakter gesendet. Andernfalls verwendet die Nachricht den angegebenen Namen, als ob ein GM den Befehl /as verwendet hätte.MESSAGE(String) Die Nachricht, die an den Chat gesendet werden soll.CALLBACK(Funktion, optional) Wenn Rückruf angegeben ist, wird das Ergebnis der Chat-Nachricht verwendet übergeben werden, anstatt im Chat zu erscheinen. Der Parameter der Rückrufmethode ist ein Array von Nachrichtenobjekten.OPTIONS(Objekt, optional) Wenn options.noarchive wahr ist, wird die Nachricht nicht zum Chat-Archiv hinzugefügt. Wenn „options.use3d“ „true“ ist, wird bei Würfelwürfen in der Nachricht die 3D-Würfelfunktion verwendet. Optionen sind nicht anwendbar, wenn Rückruf angegeben ist.

Kehrt zurück

(Leere)

Beispiele

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

Sie können ganz einfach Code schreiben, um eine Nachricht als derselbe Spieler oder Charakter zu senden, der einChat:NachrichtEreignis 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);
} );

DerCallback--Parameter ist nützlich, wenn SieWürfel-Enginevon Roll20 nutzen müssen. Bei Verwendung desRückrufsist der WertspeakAsnicht unbedingt erforderlich, da die Nachricht ohnehin nicht im Chat angezeigt wird.

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

options.noarchiveist in erster Linie dafür gedacht, Spielern Menüs zu senden, die ausAPI-Befehlsschaltflächenbestehen, 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 die Ansichten nur von GMs zentriert, wennmoveAlltrueist. Dieses Verhalten ist hier dokumentiert

Kehrt zurück

(Leere)

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. Bei integrierten Effekten sollte dies „Typ-Farbe“ sein, wobei der Typ „Bombe“, „Sprudeln“, „Brennen“, „Bersten“, „Explodieren“, „Glühen“, „Rakete“ oder „Nova“ ist und die Farbe „Säure“, „Blut“, „Zauber“, „Tod“ oder „Feuer“ ist , 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

(Leere)

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 „Typenfarbe“ sein, wobei der Typ Strahl, Bombe, Atem, Sprudeln, Brennen, Platzen, Explodieren, Leuchten, Rakete, Nova oder Spritzer ist und die Farbe Säure oder Blut ist , 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

(Leere)

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

(Leere)

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

(Leere)

Beispiele

stopJukeboxPlaylist();

unterstützen

Parameter

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

Kehrt zurück

(Leere)

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

(Leere)

Beispiele

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