Bei vielen Skripten müssen nur zwei Dinge geändert werden, damit sie mit dem Bogen 2024 kompatibel sind: wie du Attribute bekommst und setzt und wie du Chat-Vorlagen/Chat-Nachrichten analysierst. Dieses Dokument führt dich durch beides und behebt einige häufige Probleme, damit du jedes Skript so aktualisieren kannst, dass es sowohl mit dem Bogen D&D2014 als auch mit dem Bogen D&D2024 kompatibel ist.
Wenn dein Skript auf diese Weise aktualisiert wird, müssen die Spielleiter/innen in Spielen mit Beacon-Bögen wie D&D2024 den Experimental-API-Server verwenden, um alle neuesten Funktionen zu nutzen. Der Experimentalserver hat dieselben Funktionen wie der Standardserver, so dass diese Umstellung keine anderen Skripte beeinträchtigen sollte, aber du solltest es in der Beschreibung des Skripts erwähnen, damit deine Nutzer es wissen. Wenn kein Beacon-Bogen vorhanden ist, funktioniert der Standardserver trotzdem mit diesen Funktionen, da er auf die alten Funktionen zum Abrufen und Setzen von Attributen zurückgreift.
Aktualisieren von Einstellungen/Einstellungen
Die größte Änderung zwischen dem Zugriff auf die Daten des Bogens 2014 und des Bogens 2024 besteht darin, wie du die Attribute abrufst und festlegst. Es gibt jetzt eine neue Reihe von asynchronen Funktionen namens getSheetItem und setSheetItem. Hier ist ein Beispiel für die Verwendung der neuen Funktionen:
const getDeathSaveSuccess = async (id) => {
const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
log(`Erster Erfolg ist ${firstSuccess}`)
}
Wenn du den Maximalwert eines Attributs abfragen möchtest (falls ein Maximalwert existiert), kannst du die Eigenschaft max übergeben, z. B. getSheetItem(characterId, "deathsave_succ1",
" max");.
Wie du im obigen Code siehst, ist getDeathSaveSuccess als asynchron gekennzeichnet. Jede Funktion, die getSheetItem verwendet, muss entweder dieses async/await-Muster verwenden oder Promises nutzen. Hier ist die gleiche Funktion wie oben, umgeschrieben als Versprechen:
const getDeathSaveSuccess = (id) => {
getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
log(`Erster Erfolg ist ${firstSuccess}`);
});
}
Wenn du mehrere Werte auf einmal oder nacheinander abrufen willst und der Rest deines Codes auf diese Daten angewiesen ist, kannst du entweder jeden Wert einzeln abwarten oder Promise.all verwenden, um jedes Versprechen auf einmal aufzulösen und den endgültigen Wert zu erhalten. Wenn du das nicht tust, ist der Wert, den du zurückbekommst, nur ein ausstehendes Versprechen und nicht der tatsächliche Wert des Attributs.
const getSuccesses = (id) => {
const promises = [];
promises.push(getSheetItem(characterId, "deathsave_succ1"));
promises.push(getSheetItem(characterId, "deathsave_succ2"));
promises.push(getSheetItem(characterId, "deathsave_succ3"));
Promise.all(promises).then((results) => {
log(`Erster Erfolg ist ${results[0]}, zweiter Erfolg ist ${results[1]}, dritter Erfolg ist ${results[2]}`);
}
}
Asynchroner Code kann eine Menge Auswirkungen auf die Art und Weise haben, wie du ein Skript schreibst, je nachdem, wie du es strukturiert hast. Wenn zum Beispiel ein Skript getAttrByName in einem replace oder map verwendet, muss es in eine asynchrone Schleife umgewandelt werden, da diese Funktionen nicht auf die Rückgabe eines Wertes warten, bevor sie fortfahren.
Spulen wir zu dem Punkt zurück, an dem ich schrieb: "Wenn du versuchst, mehrere Werte auf einmal oder nacheinander zu erhalten , und der Rest deines Codes darauf angewiesen ist, diese Daten zu haben". Der Rest deines Codes ist nicht immer davon abhängig, dass du diesen Wert hast. In den meisten Fällen wird er sich auf diesen Wert verlassen, wenn du getSheetItem verwendest, weil du mit dem Attribut, das du bekommst, etwas machen willst. Bei der umgekehrten Methode, setSheetItem, musst du jedoch oft nicht warten, bis sie abgeschlossen ist. In diesem Fall kannst du die Auswirkungen der Asynchronität dieser Funktionen ignorieren und sie einfach normal aufrufen. Das Attribut wird im Hintergrund aktualisiert, während dein Skript weiterläuft.
Die Funktion setSheetItem funktioniert genauso wie getSheetItem, enthält aber ein zusätzliches Argument, um festzulegen, auf was das Attribut gesetzt werden soll.
setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max");
Aktualisierung des Roll-Parsing
Die andere Sache, die viele 5e-Skripte machen, die aktualisiert werden muss, ist das Parsen von Würfen. Die Rollen, die an den Chat gesendet werden, sind völlig anders formatiert und müssen anders geparst werden, um Ergebnisse zu erhalten oder Details über den Inhalt zu erfahren. Das Entwicklungsteam hat einige Datenattribute in den HTML-Code eingefügt, die den Bedarf an umfangreichem HTML-Parsing minimieren, aber wenn du komplexere Daten benötigst, musst du sie möglicherweise immer noch aus der an den Chat gesendeten Nachricht auslesen. Im Folgenden haben wir einige gängige Anforderungen aufgeführt, um dir den Einstieg zu erleichtern.
Um das Ergebnis eines Wurfs in unserer Standard-Wurfvorlage zu erhalten:
const rollResultMatch = msg.content.match(/data-result="(.+?)"/);
Überprüfe anhand des Titels, um welche Art von Rolle es sich handelt:
const deathSaveMatch = msgContent.match(/header__title">Insert Header Here<\/div>/);
Überprüfe den Untertitel der Rolle, um Dinge wie die Zauberstufe oder die Schadensart herauszufinden:
const spellLevelMatch = msgContent.match(/header__subtitle">Level (.+?) /);
Da sich der Bogen 2024 noch in der Entwicklung befindet, kann es sein, dass sich bei den Würfel-Vorlagen etwas ändert, was weitere Aktualisierungen deiner Skripte erfordert. Wir können nicht versprechen, dass das String-Parsing des HTML für immer stabil bleibt, aber wir arbeiten an standardisierten Vorlagen, während wir den Bogen weiter entwickeln. Die obigen Beispiele sind der Einfachheit halber etwas starr in ihrer Regex, aber wir empfehlen, Fuzzy Matching und Wildcards zu verwenden, um dein Matching robuster zu machen, solange die Würfel-Vorlagen noch im Fluss sind.
Häufige Probleme
"Fehler: Kein Attribut oder Bogenfeld für character_id (DEINE ID HIER) namens (DEIN ATTRIBUTE HIER) gefunden"
Wahrscheinliche Ursache: Du verwendest wahrscheinlich die Standard-API und nicht die experimentelle API und versuchst, auf eine von Beacon berechnete Eigenschaft zuzugreifen. Wenn du auf "Server neu starten" klickst, achte darauf, dass in der Meldung zum Neustart der API das Wort EXPERIMENTAL und nicht DEFAULT steht. Wenn das Dropdown-Menü auf Experimentell eingestellt ist, die Neustartprotokolle aber DEFAULT anzeigen, wechsle zurück zu Standard, starte neu, wechsle dann zurück zu Experimentell und starte erneut. Dies ist ein bekanntes Problem beim Wechsel zwischen Standard und Experimentell, das wir derzeit untersuchen.
Ergebnis von getSheetItem protokolliert ein leeres Objekt anstelle eines Wertes
Wahrscheinliche Ursache: Nicht abwarten oder .then auf die getSheetItem-Funktion anwenden. Du musst warten, bis der Wert zurückkommt, bevor du mit dem Code weitermachst.