Es stehen Werkzeugfunktionen zur Verfügung, die dir dabei helfen, konsistent mit dem Roll20-Spielraum zu arbeiten. Du kannst eine Werkzeugfunktion von überall in deinen Skripts aufrufen (z. B. innerhalb eines Event-Callbacks). Die vollständige Funktionsreferenz findest du unter Mod-Skripte: Funktionsdokumentation.
Underscore.js
Du hast Zugriff auf die Underscore.js-Bibliothek (über das globale Objekt _ ), was dir die Arbeit erleichtert. Underscore bietet Werkzeugfunktionen für Dinge wie _.each (um ein Array von Objekten zu durchlaufen). Schau dir die Underscore-Dokumentation an, um mehr zu erfahren.
Protokollierung
log(Nachricht)
Mit dieser Funktion kannst du die Ausgabe in der Mod-Ausgabekonsole auf der Seite „Skript-Editor“ protokollieren. Nützlich zum Debuggen deiner Skripte und um besser zu verstehen, was im Mod-Skript-Sandkasten vor sich geht.
on("change:graphic", function(obj) {
log("Änderung bei Objekt-ID: " + obj.id);
});Nur für Mod-Skript-Sandkasten v1.5. Wenn möglich, enthalten Fehlermeldungen ein Kontext-Objekt, das das betroffene Roll20-Objekt benennt, zum Beispiel:
FEHLER: toBelow() muss mit einem Roll20-Grafik-, Text- oder Pfadobjekt aufgerufen werden. Aufgerufen mit [Roll20 Charakter -NM0tVij02hIfnoTdihc].
Objektanordnung
toFront(obj) und toBack(obj)
Diese beiden Funktionen verschieben ein Objekt auf dem Spieltisch an die Vorderseite (oder Rückseite) der Ebene, auf der es sich gerade befindet. Beachte, dass du ein tatsächliches Objekt übergeben musst, z. B. eines, das du in einem Ereignis-Callback oder durch Aufruf von getObj oder findObjs erhältst.
toAbove(obj, target) und toBelow(obj, target)
Nur für Mod-Skript-Sandkasten v1.5. Platziere obj in der Stapelreihenfolge direkt über oder unter target. target kann ein Grafik-, Text-, Pfad- oder pathv2-Objekt sein oder die ID eines solchen Objekts. toFront und toBack nehmen das Objekt selbst entgegen. Diese Typen verfügen außerdem über die Instanzmethoden toFront(), toBack(), toAbove(target) und toBelow(target).
Zufällige Zahlen
randomInteger(max)
Gibt eine zufällige ganze Zahl von 1 bis max zurück und verwendet dabei denselben Zufallsgenerator wie die Würfel von Roll20. Das ist für Würfel gedacht. Math.floor(Math.random() * max) + 1 ist für die Würfelgrößen, mit denen tatsächlich gewürfelt wird, gleichmäßig verteilt; Modulo-Verzerrung ist ein anderes Problem (integer % n).
Math.random()
Du kannst Math.random() wie gewohnt in deinen Mod-Skripten aufrufen und darauf vertrauen, dass die Ergebnisse zufällig sind, weil das „Standard“-Math.random() in JavaScript durch den kryptografisch sicheren PRNG ersetzt wurde, der Roll20 antreibt. Man kann also bestehende Skripte, die Math.random() verwenden, bedenkenlos nutzen, da man weiß, dass die Ergebnisse wirklich so zufällig sind, wie es auf einem Computer nur möglich ist.
Für einen Würfelwurf solltest du randomInteger(max) bevorzugen. Es ist derselbe Generator, den auch die Würfel-Engine verwendet.
Spieler ist SL
spielerIstSL(playerid)
Gibt zurück, ob dieser Spieler gerade SL ist. Es berücksichtigt Beförderungen und „Als Spieler wieder beitreten“ ohne Neustart. playerIsGM("API") ist false: Per Skript gesendeter Chat verwendet die Spieler-ID "API", die kein Spieler im Spiel ist.
PC sheet
setDefaultTokenForCharacter(character, token)
Setzt den Standard-Spielmarker für das bereitgestellte Charakterobjekt auf die Details des bereitgestellten Spielmarker-Objekts. Beide Objekte müssen bereits vorhanden sein. Damit werden alle derzeit mit dem Charakter verknüpften Standard-Spielmarker überschrieben.
Effekte (FX)
spawnFx(x, y, typ, seitenid)
Erzeugt an der Position x,y einen kurzen Effekt vom Typ type. Wenn du pageid weglässt oder undefined übergibst, wird standardmäßig die Seite verwendet, auf der sich die Spieler gerade befinden (playerpageid im Campaign-Objekt).
Für integrierte Effekte sollte type eine Zeichenfolge sein und einer der folgenden Werte sein: beam-color, bomb-color, breath-color, bubbling-color, burn-color, burst-color, explode-color, glow-color, missile-color, nova-color, splatter-color
Wobei „color“ oben eines von Folgendem ist: acid, blood, charm, death, fire, frost, holy, magic, slime, smoke, water
Für benutzerdefinierte Effekte sollte type die ID des custfx-Objekts für den benutzerdefinierten Effekt sein.
spawnFxBetweenPoints(point1, point2, type, pageid)
Funktioniert genauso wie spawnFx, aber statt eines einzelnen Punkts übergibst du zwei Punkte im Format {x: 100, y: 100}. Zum Beispiel: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid"). Strahl-, Atem- und Spritz-Effekte bewegen sich zwischen den beiden Punkten. Die Koordinaten sind Seitenpixel, derselbe left/top-Bereich wie bei Grafiken. Fenster- und Tür-x/y verwenden die invertierte Achse und entsprechen nicht diesen Koordinaten.
Die folgenden Effekttypen müssen immer spawnFxBetweenPoints anstelle von spawnFx verwenden: beam-color, breath-color, splatter-color
Nur für Mod-Skript-Sandkasten v1.5. Effekte vom Typ beam zeigen direkt auf point2 (ein Fehler bei der Winkelberechnung wurde behoben).
spawnFxWithDefinition(x, y, definition, pageid)
Erzeugt einen benutzerdefinierten Ad-hoc-Effekt an den Koordinaten x, y. definition ist ein JavaScript-Objekt, kein JSON-String. Die Form entspricht der Definition eines Custom FX. Wenn du pageid weglässt oder undefined übergibst, wird die aktuelle Seite der Spieler (Campaign().get("playerpageid")) verwendet.
Musikbox-Wiedergabelisten
playJukeboxPlaylist(playlistid)
Nimmt die Ordner-ID (die du über die Eigenschaft _jukeboxfolder im Campaign-Objekt erhältst) der Wiedergabeliste und startet die Wiedergabe dieser Wiedergabeliste für alle im Spiel.
stopJukeboxPlaylist()
Benötigt keine Argumente und stoppt jede Wiedergabeliste, die gerade abgespielt wird.
Verschiedenes
sendPing(left, top, pageid, playerid, moveAll, visibleTo)
Sendet einen Ping an den Spieltisch (dasselbe wie das Gedrückthalten der Maustaste). left und top sind Seitenpixel. pageid ist erforderlich. playerid ist optional und ist das vierte Argument: der Spieler, dem der Ping zugeordnet wird. Lass es weg oder übergib einen falsy-Wert, dann wird der Ping "api" (gelb) zugeordnet.
Gib true für moveAll an, um die Spieler an diese Stelle zu scrollen. visibleTo beschränkt, wer den Ping sieht: eine Spieler-ID, ein Array von IDs oder eine durch Kommas getrennte Zeichenfolge. Lass es weg oder übergib "", um alle anzupingen.
setTimeout-Verzögerungen im folgenden Beispiel werden gelöscht, wenn der Sandkasten neu startet.
on("chat:message", function(msg) {
if (msg.type !== "api" || msg.content.indexOf("!pingtest") !== 0) return;
var players = findObjs({_type: "player"});
if (players.length < 1) return;
var player1 = players[0].id;
var player2 = players.length > 1 ? players[1].id : player1;
var allPlayerIDs = players.map(function(player) { return player.id; });
var pageid = Campaign().get("playerpageid");
// pageid ist das dritte Argument; playerid ist das vierte. null ordnet den Ping "api" zu.
sendPing(300, 300, pageid, null, true);
setTimeout(function() {
// „“ für „visibleTo“ sendet ebenfalls einen Ping an alle
sendPing(1500, 500, pageid, msg.playerid, true, "");
}, 1000);
setTimeout(function() {
sendPing(1200, 500, pageid, null, true, player1);
}, 2000);
setTimeout(function() {
sendPing(900, 100, pageid, player2, true, [player1, player2]);
}, 3000);
setTimeout(function() {
sendPing(300, 300, pageid, player1, true, allPlayerIDs.join());
}, 4000);
});Ein Hinweis zu Abständen und Rastern in Roll20
Auf einem quadratischen Raster entspricht eine Einheit 70 Pixeln. Das snapping_increment der Seite gibt an, wie viele Einheiten jedes Rasterfeld umfasst, scale_number ist die Entfernung einer Einheit, und scale_units ist der Einheitenname (oft ft). Standardmäßig gilt: 1 Einheit = 5 ft = 1 Quadrat = 70 Pixel. Ein SL kann 1 Einheit auf 10 ft festlegen oder jedes Feld auf 2 Einheiten (140 Pixel).
Bei Sechseckrastern wird dieses 70-Pixel-Quadrat nicht verwendet. Fenster- und Türpositionen verwenden eine invertierte y-Achse; Grafik-left/top tun das nicht.