1. Roll20 Hilfezentrum
  2. Automatisierungen
  3. Mod-Skripte (API)

Mod-Skripte: Funktionsdokumentation

Roll20 stellt eine Reihe von Funktionen zur Verfügung, die nicht Teil des Kern-JavaScripts oder einer anderen Bibliothek sind.

Spiele können Mod-Skript-Sandkasten v1.0 (Campaign().sandboxVersion === "1.0") oder v1.5 ("1.5") ausführen. Funktionen, die mit Nur für Mod-Skript-Sandkasten v1.5. gekennzeichnet sind funktionieren nicht mit v1.0.

Globale Variablen

Variable Beschreibung
_ Dies ist das Namespace-Objekt für die Underscore.js-Bibliothek.
state Die Eigenschaften des State-Objekts bleiben zwischen Spielsitzungen bestehen.

_ (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. Das gleiche Statusobjekt wird außerdem von allen Mod-Skripten einer Kampagne gemeinsam genutzt. Es wird daher dringend empfohlen, beim Schreiben von Werten in den Status den Speicherbedarf so gering wie möglich zu halten, um Namenskonflikte zu vermeiden. Hinweis: Der State wird mit JSON serialisiert, also kannst du keine Funktionen oder Objekte mit zyklischen Referenzen speichern.

Globale Funktionen

Typ der Rückgabe Funktion Beschreibung
Roll20-Objekt Kampagne Ruft das Singleton-Campaign-Roll20-Objekt ab.
Roll20-Objekt createObj Erstellt ein neues Roll20-Objekt.
Array von Roll20-Objekten filterObjs Ruft alle Roll20-Objekte ab, die ein Prädikatstest bestehen.
Array von Roll20-Objekten findObjs Ruft alle Roll20-Objekte mit Eigenschaften ab, die einem bestimmten Satz von Attributen entsprechen.
Array von Roll20-Objekten getAllObjs Ruft alle Roll20-Objekte in der Kampagne ab.
variiert getAttrByName Ruft den aktuellen oder maximalen Wert eines Attribut-Roll20-Objekts ab.
variiert getComputed Nur Mod-Skript-Sandkasten v1.5. Ruft eine berechnete Beacon-Eigenschaft ab.
variiert getSheetDefaultValue Ruft den Standardwert eines Charakterbogens für einen Attributnamen ab.
variiert getSheetItem Ruft ein Bogenelement ab (Attribut; ab Version 1.5 auch Beacon / user.*).
Roll20-Objekt getObj Ruft ein bestimmtes Roll20-Objekt ab.
log Protokolliert eine Meldung in der Mod-Ausgabekonsole.
an Registriert einen Ereignishandler.
onSheetWorkerCompleted Registriert einen einmaligen Ereignishandler, der ausgeführt wird, nachdem ein vollständiger Stapel von Charakterbogen-Entwickler-Skripten abgeschlossen ist.
performAction Nur Mod-Skript-Sandkasten v1.5. Führt eine Beacon-Bogenaktion aus.
Boolescher Wert SpielerIstSL Überprüft, ob ein Spieler derzeit über GM-Rechte verfügt.
PlayJukeboxPlaylist Beginne mit der Wiedergabe einer Musikbox-Wiedergabeliste.
Nummer randomInteger Erzeugt einen zufälligen ganzzahligen Wert.
sendChat Sendet eine Chat-Nachricht.
sendPing Sendet einen Ping, so als würdest du die linke Maustaste gedrückt halten.
setAttrs Legt ein oder mehrere Attribute für einen Charakter fest.
setComputed Nur Mod-Skript-Sandkasten v1.5. Legt eine beschreibbare berechnete Beacon-Eigenschaft fest.
setSheetItem Legt ein Bogenelement fest (Attribut; ab Version 1.5 auch Beacon / user.*).
spawnFx Erzeugt einen Partikelemitter.
spawnFxBetweenPoints Erzeugt einen Partikelemitter, der sich von einem Punkt zum anderen bewegt.
spawnFxWithDefinition Erzeugt einen Partikelemitter, der nicht durch ein FX Roll20-Objekt dargestellt wird.
stopJukeboxPlaylist Stoppt alle aktuell abgespielten Musikbox-Wiedergabelisten.
toAbove Nur Mod-Skript-Sandkasten v1.5. Platziert ein Objekt direkt über einem anderen auf derselben Ebene.
toBack Verschiebt eine Grafik, einen Text, einen Pfad oder ein pathv2-Objekt unter die anderen Objekte auf seiner Ebene.
toBelow Nur Mod-Skript-Sandkasten v1.5. Platziert ein Objekt direkt unter einem anderen auf derselben Ebene.
nach vorne Verschiebt eine Grafik, einen Text, einen Pfad oder ein pathv2-Objekt über die anderen Objekte auf seiner Ebene. Übergebe das Objekt, nicht eine ID.
Kartenhelfer shuffleDeck, cardInfo, recallCards, dealCardsToTurn, drawCard, pickUpCard, takeCardFromPlayer, playCardToTable, giveCardToPlayer – siehe Objekte: Kartenspiel.

Kampagne

Parameter

Keine Parameter

Gibt zurück

Das Roll20-Objekt der Singleton-Kampagne.

Beispiele

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

Campaign().sandboxVersion ist "1.0" oder "1.5". Campaign().nodeVersion ist die Zeichenfolge für die Node.js-Version. Nur Mod-Skript-Sandkasten v1.5. sheetName, computedSummary und actionSummary. Siehe Objekte: Kampagne.

createObj

Parameter

TYPE (Zeichenkette) Der Typ des Roll20-Objekts, das erstellt werden soll. Du kannst 'graphic', 'text', 'path', 'pathv2', 'character', 'ability', 'attribute', 'handout', 'rollabletable', 'tableitem', 'macro', 'card', 'deck', 'custfx', 'window', 'door' und 'pin' erstellen. Nur Mod-Skript-Sandkasten v1.5. 'pageFolder'.

ATTRIBUTES (Objekt) 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 (z. B. ein Roll20-Attributobjekt, das ein untergeordnetes Objekt eines Roll20-Charakterobjekts ist), musst du die ID des übergeordneten Objekts in attributes angeben.

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

Wenn du einen Pfad erstellst, gib path (gespeichert als _path) und pageid an. path ohne Unterstrich ist der Name zum Zeitpunkt der Erstellung. Danach ist es schreibgeschützt.

createObj('path', {
  pageid: Campaign().get('playerpageid'),
  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]])
});

Wenn du ein Roll20-Objekt für eine Notiz erstellst, kannst du den Text oder gmnotes zum Zeitpunkt der Erstellung nicht 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.');
handout.set('gmnotes', 'Set gmnotes in a separate call from notes.');

filterObjs

Parameter

CALLBACK (Funktion) Eine Prädikatfunktion, mit der alle Roll20-Objekte geprüft werden. Die Callback-Funktion 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.

findObjs

Parameter

ATTRIBUTES (Objekt) Eine Sammlung von Schlüssel-Wert-Paaren, die mit Roll20-Objekten in der Kampagne abgeglichen werden.

OPTIONS (Objekt, optional)

  • caseInsensitive – Wenn „true“, werden bei Zeichenfolgenvergleichen Groß- und Kleinschreibung nicht berücksichtigt.
  • startsWith – wenn true, stimmen Zeichenfolgenwerte als Präfix überein.
  • tagMatch – beim Abgleichen von tags: 'all' (Standard; das Objekt hat jedes aufgeführte Stichwort), 'any' (mindestens eines), 'only' (genau die aufgeführte Menge).

Gibt zurück

Ein Array von Roll20-Objekten mit Eigenschaften, die mit attributes übereinstimmen. Bei Schlüsseln kann der führende Unterstrich weggelassen werden: type und _type stimmen beide überein.

Beispiele

var npcs = findObjs({ type: 'character', controlledby: '' });
var knights = findObjs({ type: 'character', name: 'Sir' }, { startsWith: true });

getAllObjs

Parameter

Keine Parameter

Gibt zurück

Ein Array aller Roll20-Objekte in der Kampagne.

getAttrByName

Parameter

CHARACTER_ID (Zeichenkette) Die ID des Charakters. ATTRIBUTE_NAME (Zeichenkette) Der Name des Attributs. VALUE_TYPE (Zeichenkette, optional) "current" oder "max" (standardmäßig "current").

Gibt zurück

Die Eigenschaft current oder max. Wenn nichts festgelegt ist, wird der Standardwert des Charakterbogens verwendet (sofern vorhanden).

getComputed

Nur Mod-Skript-Sandkasten v1.5. (In Version 1.0 ist dieser Name ein No-Op-Stub.)

Parameter

Ein Objekt: { characterId, property, args?, playerId? }.

Wenn du einen Beacon-Charakterbogen verwendest, wird der Wert einer berechneten Eigenschaft abgerufen. Liste die Namen mit Campaign().computedSummary auf. playerId ist optional; einige Beacon-Funktionen (zum Beispiel Wurfabfragen) benötigen sie jedoch.

getSheetDefaultValue

Parameter

ATTRIBUTE_NAME (Zeichenkette), VALUE_TYPE (Zeichenkette, optional) "current" oder "max".

Das angegebene Roll20-Objekt.

Der Standardwert des Bogens für dieses Feld, nicht der aktuelle Charakterwert.

getSheetItem

Parameter

getSheetItem(characterId, property, valtype?, options?) — asynchron (Promise).

In Version 1.0 umschließt dies getAttrByName. Nur Mod-Skript-Sandkasten v1.5. Auf Beacon-Bögen liest es außerdem berechnete Eigenschaften und benutzerdefinierte Attribute namens user.*.

getObj

Parameter

TYPE (Zeichenkette), ID (Zeichenkette)

Gibt zurück

Das angegebene Roll20-Objekt.

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

log

Parameter

MELDUNG (variiert) Wird in die Mod-Ausgabekonsole geschrieben. Mit JSON.stringify umgewandelt.

Nur Mod-Skript-Sandkasten v1.5. Fehlermeldungen enthalten oft ein Kontextobjekt wie beispielsweise [Roll20-Charakter -id].

an

Parameter

EVENT (Zeichenkette) Es gibt fünf Arten von Ereignissen: ready, change, add, destroy, chat. Mit Ausnahme von ready musst du das Ereignis mit einem Objekttyp verknüpfen. Für chat ist dieser Typ immer message. Änderungsereignisse können auch eine Eigenschaft, eine Objekt-ID oder beides benennen: change:graphic:left, change:graphic:ID, change:graphic:ID:left. Grafiken lösen außerdem Untertyp-Ereignisse wie change:token und change:dicetoken aus. Siehe Ereignisse.

CALLBACK (Funktion) ready-Ereignisse haben keine Callback-Parameter. change-Ereignisse haben einen obj-Parameter (das Roll20-Objekt nach der Änderung) und einen prev-Parameter (ein einfaches JavaScript-Objekt mit Eigenschaften vor der Änderung). add-Ereignisse haben einen obj-Parameter (das neue Objekt). destroy-Ereignisse haben einen obj-Parameter (das nicht mehr existierende Objekt). chat-Ereignisse haben einen msg-Parameter (Details zur Nachricht).

Gibt zurück

(Void)

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 Eigenschaft left eines grafischen Roll20-Objekts dazu, dass function3 aufgerufen wird, gefolgt von function1 und dann function2.

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

add-Ereignisse versuchen, für Roll20-Objekte ausgelöst zu werden, die sich bereits in der Kampagne befinden, wenn eine neue Sitzung beginnt. Um dieses Verhalten zu verhindern, kannst du mit der Registrierung deines add-Ereignisses warten, bis das ready-Ereignis ausgelöst wird.

on('add:graphic', function(obj) {
  // Zu Beginn der Sitzung wird diese Funktion für jede Grafik in der Kampagne aufgerufen
});
on('ready', function() {
  on('add:graphic', function(obj) {
    // Diese Funktion wird *nur* aufgerufen, wenn ein neues Roll20-Objekt für eine Grafik erstellt wird
  });
});

Der prev-Parameter für change-Events ist kein Roll20-Objekt. Du kannst get oder set nicht verwenden, und du kannst die führenden Unterstriche bei schreibgeschützten Eigenschaften nicht weglassen. Verwende prev._id, nicht prev.id.

Bei Blob-Feldern von Charakteren und Notizen (bio, notes, gmnotes) sowie bei _defaulttoken des Charakters ist prev nicht der Text. Grafik-gmnotes ist eine gewöhnliche Zeichenfolge. Speichere frühere Blob-Werte selbst im Cache, falls du sie brauchst.

onSheetWorkerCompleted

Parameter

CALLBACK (Funktion) Wird aufgerufen, wenn der aktuelle Stapel von Sheet Worker-Skripten abgeschlossen ist. Soll vor setWithWorker aufgerufen werden. Wird nur einmal ausgeführt. Der Callback kann { workersExecuted: boolean } erhalten.

performAction

Nur für Mod-Skript-Sandkasten v1.5. (In Version 1.0 ist dieser Name ein No-Op-Stub.)

Parameter

{ characterId, action, args?, playerId? }

Führt eine Beacon-Bogenaktion aus. Liste die Namen mit Campaign().actionSummary auf. playerId ist optional; einige Beacon-Funktionen benötigen sie jedoch. Wenn der Name keine Beacon-Aktion ist, greift v1.5 möglicherweise über sendChat auf eine Charakter-Fähigkeit mit diesem Namen zurück.

SpielerIstGM

Parameter

PLAYER_ID (Zeichenkette)

Kehrt zurück

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

Besonders nützlich, um Mod-Skript-Befehle auf die Verwendung durch den SL zu beschränken. Behalte msg.type !== 'api' so bei, wie es geschrieben steht – das ist der Typ der Befehlsnachricht.

PlayJukeboxPlaylist

Parameter

PLAYLIST_ID (Zeichenkette) Die ID der Wiedergabeliste, deren Wiedergabe gestartet werden soll.

randomInteger

Parameter

MAX (Zahl) Maximalwert inklusive.

Kehrt zurück

Eine zufällige ganze Zahl zwischen 1 und max. Verwende das lieber als Math.random(), wenn du würfelähnliche Wertebereiche brauchst.

sendChat Asynchron

Parameter

SPEAKINGAS (Zeichenkette) Ein Name oder player|player_id / character|character_id. MESSAGE (Zeichenkette). CALLBACK (Funktion, optional) – Die Ergebnisse werden an den Callback übergeben, anstatt im Chat angezeigt zu werden. OPTIONEN (Objekt, optional) noarchive, use3d.

Siehe Mod-Skripte: Chat für Befehlsknöpfe ([label](!command)).

sendPing

Parameter

LEFT, TOP, PAGE_ID, PLAYER_ID (optional), MOVEALL (optional), VISIBLETO (optional). Wenn player_id weggelassen wird, ist der Ping gelb. Wenn moveAll true ist, werden die Ansichten auf den Ping zentriert. visibleTo kann eine Spieler-ID, ein Array von IDs oder eine durch Kommas getrennte Zeichenkette sein.

setAttrs

Parameter

CHARACTER_ID (Zeichenkette), ATTRIBUTE_OBJ (Objekt vom Typ „Name → Wert“). Namen, die auf _max enden, legen den Maximalwert fest. Wiederholende $n-Namen werden unterstützt. options.silent verwendet set anstelle von setWithWorker.

setComputed

Nur für Mod-Skript-Sandkasten v1.5.

{ characterId, property, args?, playerId? } — legt eine beschreibbare, berechnete Beacon-Eigenschaft fest. Siehe Campaign().computedSummary.

setSheetItem

setSheetItem(characterId, property, value, valtype?, options?) — asynchron. In Version 1.0 werden Attribute festgelegt. Nur für Mod-Skript-Sandkasten v1.5. Außerdem berechnete Beacon-Eigenschaften und benutzerdefinierte user.*-Attribute. Zu den Optionen gehören createAttr, withWorker und allowThrow.

spawnFx

Parameter

LEFT (Zahl) Die x-Koordinate, an der der Partikelemitter platziert werden soll. TOP (Zahl) Die y-Koordinate. TYPE (Zeichenkette) Für integrierte Effekte: "type-color", wobei type einer der folgenden Werte ist: bomb, bubbling, burn, burst, explode, glow, missile oder nova und color einer der folgenden Werte ist: acid, blood, charm, death, fire, frost, holy, magic, slime, smoke oder water. Für benutzerdefinierte Effekte die ID eines custfx-Objekts. Hinweis: beam, breath und splatter können nicht mit spawnFx verwendet werden – siehe spawnFxBetweenPoints. PAGE_ID (Zeichenkette, optional) ist standardmäßig auf Campaign().get('playerpageid') gesetzt.

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

spawnFxBetweenPoints

Parameter

START (Objekt) { x, y }. END (Objekt) { x, y }. TYPE (Zeichenkette) wie bei spawnFx, plus beam, breath und splatter. PAGE_ID (Zeichenkette, optional).

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

Nur für Mod-Skript-Sandkasten v1.5. Effekte vom Typ beam zeigen direkt auf den Endpunkt (ein Fehler bei der Winkelberechnung wurde behoben).

spawnFxWithDefinition

Parameter

LEFT, TOP, DEFINITION (Objekt, das den Emitter beschreibt), PAGE_ID (optional). Die Eigenschaftsnamen findest du unter „Custom FX“ im Artikel „Objects“.

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

stopJukeboxPlaylist

Stoppt alle aktuell abgespielten Musikbox-Wiedergabelisten.

stopJukeboxPlaylist();

Kartenhelfer

In beiden Sandkasten-Versionen verfügbar. Alle Details findest du unter Mod-Skripte: Objects (Deck).

  • shuffleDeck(deckid, discard, newOrder)
  • cardInfo(settings)
  • recallCards(deckid, type)
  • dealCardsToTurn(deckid)
  • drawCard(deckid, cardid)
  • pickUpCard(cardid, fromDiscard)
  • takeCardFromPlayer(playerid, options)
  • playCardToTable(cardid, settings)
  • giveCardToPlayer(cardid, playerid)

setDefaultTokenForCharacter

CHARACTER (Charakterobjekt), TOKEN (Grafikobjekt). Beides muss bereits vorhanden sein. Schreibt den _defaulttoken-Blob des Charakters aus dem Spielmarker. So setzt du dieses Feld; mit set() geht das nicht.

toAbove

Nur für Mod-Skript-Sandkasten v1.5.

Parameter

OBJ (graphic, text, path oder pathv2), TARGET (Objekt oder ID).

Platziert obj direkt über target auf derselben Ebene.

toBack / toFront

OBJ muss ein graphic-, text-, path- oder pathv2-Objekt sein. Übergebe das Objekt, nicht eine ID. In Version 1.5 sind diese deutlich schneller, und diese Typen verfügen außerdem über die Instanzmethoden toFront() / toBack().

toBelow

Nur für Mod-Skript-Sandkasten v1.5.

Platziert obj direkt unter target (Objekt oder ID) auf derselben Ebene.

War dieser Beitrag hilfreich?
8 von 14 fanden dies hilfreich