Sheet Worker-Skripte

19. September 2023 14:24

Hinzufügen eines Sheet Worker-Skripts

Um ein Sheet-Worker-Skript zu einem Charakterblatt hinzuzufügen, fügen Sie das Skript einfach im folgenden Format in den Abschnitt „HTML“ des Blattes ein:

<script type="text/worker">

on("change:strength", function() {

});

// ... usw.

</Skript>

Beachten Sie, dass das Skript-Tag den Typ „text/worker“ haben muss, damit es vom System ordnungsgemäß verarbeitet werden kann. Wenn das Spiel geladen wird, werden aus Sicherheitsgründen alle Skript-Tags aus der Vorlage des Blatts entfernt. Allerdings werden Skript-Tags mit dem Typ „Text/Worker“ verwendet, um auf dem Computer jedes Spielers einen Hintergrund-Worker zu starten, der auf sich ändernde Werte in seinen Blättern reagieren und bei Bedarf Maßnahmen ergreifen kann. Alle Sheetworker-Skripte müssen in einem einzigen Skript-Tag enthalten sein.

Umfangreichere Beispiele zu den Grundlagenfür Nicht-Programmierer

Warnung zum „globalen“ Variablenbereich:der Bereich einer deklarierten Variableninnerhalbdie „<script type="text/worker">` aberaußerhalbeine Funktion gilt derzeit proSpieler, nicht pro Charakter. Wenn Sie seinen Wert ändern, wird er für alle Charaktere in der Sitzung Ihres Spielers geändert.

Als Best Practice sollten asynchrone Kaskaden nach Möglichkeit vermieden werden. Im Allgemeinen ist es besser, alle für Berechnungen erforderlichen Attribute in einem getAttrs abzurufen, anstatt getAttrs -> Berechnungen -> setAttrs -> getAttrs -> Berechnungen -> setAttrs…durchzuführen

Sheet Worker vs. automatisch berechnende Felder: Welche soll ich verwenden?

Hierzu gibt es keine feste Regel. Beide Tools sind in der Lage, dasselbe zu erreichen. Nehmen wir einen hypothetischen Anwendungsfall eines „Stärke“-Attributs, den wir verwenden möchten, um ein „Stärke-Mod“-Attribut auf dem neuesten Stand zu halten. Hier wären die Unterschiede zwischen den beiden Tools für diesen Anwendungsfall:

Die automatisch berechnenden Felder werden jedes Mal neu berechnet, wenn ein Blatt zum ersten Mal geöffnet wird. Die Sheet Worker-Felder hingegen werden nur dann neu berechnet, wenn sich ihre abhängigen Werte ändern. Das bedeutet, dass Blätter, die die Sheet Worker-Option nutzen, für Spieler viel, viel schneller geöffnet und mit ihnen interagiert werden können.

Darüber hinaus werden die Sheet Worker-Berechnungen in einem Hintergrundprozess ausgeführt, was bedeutet, dass während der Ausführung der Berechnungen keine Verzögerung auf der Benutzeroberfläche entsteht. Deaktivierte Felder hingegen werden im Hauptprozess ausgeführt und können daher zu „Abstürzen“ oder „Stottern“ führen, wenn eine große Anzahl davon auf einmal berechnet wird (z. B. wenn Sie ein sehr kompliziertes Blatt mit Tausenden von Feldern haben). deaktivierte Felder).

Das Feld „Stärke-Mod“ zur automatischen Berechnung erscheint für den Spieler deaktiviert. Ein Stärke-Mod-Feld, das von einem Blattarbeiter aktualisiert wird, wäre hingegen nach der Ausführung der Berechnung änderbar (allerdings würde jeder eingegebene Wert überschrieben, wenn sich der Stärkewert ändert). Ein Sheet Worker würde also Homebrew-Regeln besser unterstützen, da der Spieler einfach den Mod-Wert ändern könnte, nachdem sich die Stärke geändert hat. Andererseits würde das automatisch berechnende Feld eine solche Änderung nicht zulassen, sodass die Regeln strenger „durchgesetzt“ würden.

Generell empfehlen wir Ihnen, mit automatisch berechnenden Feldern sparsam umzugehen.Planen Sie ein Budget von höchstens 500 bis 1.000 automatisch berechnenden Feldern ein. Wir empfehlen die Verwendung der neuen Sheet Worker-Funktionalität für die meisten Berechnungen, insbesondere für Berechnungen, die nur selten durchgeführt werden müssen (z. B. ändert sich Ihr Stärkewert (und damit Ihr Stärke-Mod) wahrscheinlich höchstens einmal pro Sitzung, wenn der Charakter aufsteigt). Es ist nicht erforderlich, dieselbe Berechnung jedes Mal erneut durchzuführen, wenn das Blatt geöffnet wird.

Sheet Worker-API

Veranstaltungen

eventInfo-Objekt

Vielen Ereignissen wird eineventInfo-Objekt übergeben, das Ihnen zusätzliche Details zu den Umständen des Ereignisses liefert.

Eigentum	Descripción
`Quellenattribut`	Das ursprüngliche Attribut, das das Ereignis ausgelöst hat. Es ist der vollständige Name (einschließlich RowID, falls in einem sich wiederholenden Abschnitt) des Attributs, das dieses Ereignis ursprünglich ausgelöst hat. Hinweis: Die gesamte Zeichenfolge wurde in Kleinbuchstaben übersetzt und ist daher möglicherweise nicht für die direkte Eingabe in getAttrs() geeignet.
`Quelle Typ`	Der Agent, der das Ereignis ausgelöst hat, entweder`Spieler`oder`Blattarbeiter`
`vorheriger Wert`	Der ursprüngliche Wert des Attributs in einem`on:change`Ereignis, bevor das Attribut geändert wurde.
`neuer Wert`	Der Wert, auf den sich das Attribut in einem`on:change`Ereignis geändert hat.
`entferntInfo`	Ein Objekt, das die Werte aller Attribute enthält, die in einem`-repeating_groupname-`Ereignis entfernt wurden.

Änderung:<attribute_name>

Ermöglicht Ihnen, die Änderungen bestimmter Attribute oder im Falle eines sich wiederholenden Abschnitts alle Änderungen im gesamten Abschnitt anzuhören. Es ist ganz einfach:

auf("change:strength change:StrengthMod change:StrengthOtherThing", function(eventInfo) {
   //Hier etwas tun
   // eventInfo. previousValue ist der ursprüngliche Wert des Attributs, das dies ausgelöst hat Ereignis, bevor es geändert wurde.
   // eventInfo.newValue ist der aktuelle Wert des Attributs, das dieses Ereignis ausgelöst hat, da es geändert wurde.
});

on("change:repeating_spells:spellname", function(eventInfo) {
   //Hier etwas tun
   // eventInfo.sourceAttribute ist der vollständige Name (einschließlich sich wiederholender ID) des Attributs 
   // das ursprünglich dieses Ereignis ausgelöst hat, 
   // jedoch wurde die gesamte Zeichenfolge in Kleinbuchstaben übersetzt und ist daher möglicherweise nicht 
   // für die direkte Eingabe
   // in getAttrs() oder geeignet andere Verwendungen ohne vorherige Zerstörung.
});

on("change:repeating_spells", function(eventInfo) {
   //Würde ausgelöst, wenn ein Attribut im Abschnitt „repeating_spells“ geändert wird
   // eventInfo.sourceAttribute ist der vollständige Name (in Kleinbuchstaben). )(einschließlich sich wiederholender ID) 
   // des Attributs, das dieses Ereignis ursprünglich ausgelöst hat. 
});

Hinweis: Alle Attributnamen werden in Ereignissen in Kleinbuchstaben geschrieben. Auch wenn Sie ein Attribut normalerweise als „Stärke“ bezeichnen, verwenden Sie im Ereignis-Listener „change:strength“.

Hinweis: Dies unterstützt das Suffix „_max“, da Ether „change:strength“ oder „change:strength_max“ ein Ereignis auslöst. Diese beiden Varianten scheinen jedoch austauschbar zu sein, da Ether oder beide ausgelöst werden, wenn Ether „strength“ oder „strength_max“ ändert sich.

Für Attribute in sich wiederholenden Feldern würden alle folgenden Aktionen ausgelöst, wenn das Attribut „repeating_spells_SpellName“ aktualisiert wird: „change:repeating_spells:spellname“, „change:repeating_spells“, „change:spellname“, „change:spellname_max“. Dies gibt Ihnen maximale Flexibilität bei der Auswahl der „Ebene“ des Änderungsereignisses, an die Sie Ihre Funktion binden möchten.

Sheetworker können auch auf ein Änderungsereignis eines speziellen Attributs warten, das immer dann geändert wird, wenn ein sich wiederholender Abschnitt neu angeordnet wird.

auf("change:_reporder:<sectionname>", function(eventInfo) {
   // Wobei <sectionname> oben ein sich wiederholender Abschnittsname sein sollte, z. B. Fertigkeiten oder Zaubersprüche
});

entfernen:repeating_<groupname>

Dies ist ein Ereignis, das immer dann ausgelöst wird, wenn eine Zeile aus einem sich wiederholenden Feldabschnitt gelöscht wird. Sie können auch darauf warten, dass eine bestimmte Zeile gelöscht wird, wenn Sie deren ID kennen, z. B. on("remove:repeating_inventory:-ABC123")

auf("remove:repeating_inventory", function(eventInfo) {
     //Wird immer dann ausgelöst, wenn eine Zeile aus Repeating_inventory entfernt wird
     // eventInfo.sourceAttribute ist der vollständige Name (einschließlich ID) der ersten Attribut, das das Ereignis ausgelöst hat (Sie können damit die ID der gelöschten Zeile ermitteln)
});

Die Eventinfo der Funktion „remote:<groupname> enthält eine spezielle Eigenschaft „removedInfo“, die alle Attribute des nun entfernten Wiederholungsabschnitts anzeigt.

auf("remove:repeating_inventory", function(eventinfo) {
   console.log(eventinfo.removedInfo);
});

Blatt:geöffnet

Dieses Ereignis wird jedes Mal ausgelöst, wenn ein Spieler in einer Spielsitzung ein Blatt öffnet. Es sollte nützlich sein, um beispielsweise nach benötigten Blattaktualisierungen zu suchen.

auf('sheet:opened',function(){

// Etwas tun, wenn das Blatt zum ersten Mal von einem Spieler in einer Sitzung geöffnet wird

});

angeklickt:<button_name>

Dieses Ereignis wird ausgelöst, wenn auf eine Aktionsschaltfläche geklickt wird. Der Name der Schaltfläche muss mit „act_“ beginnen. Zum Beispiel:

<button type="action" name="act_activate">Aktivieren!</button>

on("clicked:activate", function() {
  console.log("Activate button angeklickt");
});

Functionsq

getAttrs(attributeNameArray, callback) Asynchron

Mit der Funktion getAttrs können Sie die Werte einer Reihe von Attributen aus dem Blatt abrufen. Das Suffix „_max“ wird unterstützt, sodassgetAttrs( [„Strength“, „Strength_max“], func)sowohl den aktuellen als auch den maximalen Wert von „Strength“ erhält. Beachten Sie, dass die Funktion asynchron ist, was bedeutet, dass es keine Garantie dafür gibt, dass die Reihenfolge, in der mehrere getAttrs-Aufrufe durchgeführt werden, auch die Reihenfolge ist, in der die Ergebnisse zurückgegeben werden. Stattdessen übergeben Sie eine Callback-Funktion, die ausgeführt wird, wenn die Werte berechnet wurden. Die Rückruffunktion empfängt ein einfaches Javascript-Objekt mit einer Liste von Schlüssel-Wert-Paaren, eines für jedes von Ihnen angeforderte Attribut.

Hier ist ein Beispiel:

on("change:strength", function() {
   getAttrs(["Strength", "Level"], function(values) {
      //Etwas tun mit Werten.Stärke und/oder Werte[ "Level" ]
   });
});

Werte in sich wiederholenden Abschnitten erfordern eine besondere Behandlung. Wenn sich das Ereignis, in dem Sie sich befinden, bereits in einem sich wiederholenden Abschnitt befindet, können Sie die Variable einfach mit ihrem Namen und dem vorangestellten Namen der sich wiederholenden Gruppe anfordern. Sie erhalten dann den Wert im selben sich wiederholenden Abschnitt, in dem das Ereignis ausgelöst wurde. Wenn wir beispielsweise einen Abschnitt „repeating_spells“ haben, der sowohl SpellName, SpellLevel als auch SpellDamage enthält, dann:

auf("change:repeating_spells:spelllevel", function() {
   getAttrs([
      "repeating_spells_SpellDamage",
      "repeating_spells_SpellName"
    ], function(values) {
      //values.repeating_spells_SpellDamage und Values.repeating_spells_SpellName 
//werden beide aus derselben Wiederholungsabschnittszeile stammen, in der sich der geänderte SpellLevel befindet.
   });
});

Wenn Sie sich jedoch gerade nicht in einem sich wiederholenden Abschnitt befinden, können Sie diesen Wert eines Felds in einer sich wiederholenden Abschnittszeile gezielt anfordern, indem Sie dessen ID manuell angeben:

getAttrs(["repeating_spells_-ABC123_SpellDamage"]...

Sie können auch das Attribut „_reporder_repeating_<sectionname>“ mit getAttrs() anfordern, um eine Liste aller IDs im Abschnitt zu erhalten, die bestellt wurden. Beachten Sie jedoch, dass dies möglicherweise nicht die vollständige Auflistung aller IDs in einem Abschnitt umfasst. Es wird davon ausgegangen, dass alle IDs, die nicht in der Liste enthalten sind und sich im Abschnitt befinden, in lexografischer Reihenfolge nach den geordneten IDs stehen.

setAttrs(values,options,callback) Asynchron

Werte– Dies ist ein Objekt, dessen Eigenschaften die Namen von Attributen sind (ohne das Präfix attr_) und dessen Werte die Werte sind, auf die Sie dieses Attribut festlegen möchten.

Optionen– (Optional) Dies ist ein Objekt, das optionales Verhalten für die Funktion angibt. Derzeit ist die einzige Option „silent“, die verhindert, dass die Weitergabe von Änderungsereignissen die bereitgestellten Attribute festlegt.

Rückruf– (Optional) Dies ist eine Rückruffunktion, die ausgeführt wird, wenn die festgelegten Attribute aktualisiert wurden.

Mit der Funktion setAttrs können Sie die Attribute des Zeichenblatts festlegen. Verwenden Sie das Suffix „_max“, um den Maximalwert eines Attributs festzulegen. Zum Beispiel „Strength_max“.

on("change:strength", function() {
   getAttrs(["Strength", "Level"], function(values) {
      setAttrs({
          StrengthMod: Math.floor(values.Strength / 2)
      });
   });
});

Hinweis: Wenn Sie versuchen, ein deaktiviertes Eingabefeld mit dieser Methode zu aktualisieren, können Probleme auftreten. Eine Möglichkeit besteht darin, diese „setAttrs“-Methode zu verwenden, um eine ausgeblendete Eingabe festzulegen und dann die deaktivierte Eingabe auf das ausgeblendete Element festzulegen. In diesem Beispiel haben wir ein Attribut mit dem Namen „will“ und möchten die Beurteilung basierend auf der Hälfte des Willensstats berechnen, dürfen jedoch nicht zulassen, dass dieser 90 überschreitet. Siehe unten.

<label>Beurteilung</label>
<Eingabetyp=„versteckt“ Name=„attr_foo_judgment“ Wert=„0“ />
<=„Nummer“ Name=„attr_judgment“ Wert=„@{foo_judgment}“ deaktiviert=„wahr“ Titel=„ 1/2 des Testaments abgerundet, maximal 90" />

on("change:will", function() {
  getAttrs(["will"], function(values) {
    setAttrs({ foo_judgment: Math.Min(90, (values.will/2)) });
  });
});

Beachten Sie, dass setAttrs zwar eine asynchrone Funktion ist und es keine Garantie dafür gibt, in welcher Reihenfolge die tatsächlichen Attribute für mehrere setAttrs()-Aufrufe festgelegt werden.

Für sich wiederholende Abschnitte haben Sie die Möglichkeit, den einfachen Variablennamen zu verwenden, wenn sich das ursprüngliche Ereignis in einem sich wiederholenden Abschnitt befindet, oder Sie können den vollständigen Variablennamen des sich wiederholenden Abschnitts einschließlich der ID in jedem Ereignis angeben.

auf("change:repeating_spells:spelllevel", function() {
   getAttrs(["repeating_spells_SpellLevel", "repeating_spells_SpellName"], function(values) {
      setAttrs({
         repeating_spells_SpellDamage: Math.floor(values.repeating_spells_SpellLevel / 2) + 10
      });
   });
});

getSectionIDs(section_name,callback) Asynchron

Mit dieser Funktion können Sie eine Liste der IDs abrufen, die derzeit für einen bestimmten Wiederholungsabschnitt vorhanden sind. Dies ist nützlich für die Berechnung von Dingen wie dem Inventar, bei dem es eine variable Anzahl von Zeilen geben kann.

auf("change:repeating_inventory", function() {
   getSectionIDs("inventory", function(idarray) {
      for(var i=0; i < idarray.length; i++) {
         //Mache etwas mit den IDs
      }
   });
});

Beachten Sie, dass Sie GetAttrs() (oben beschrieben) verwenden können, um das Attribut „_reporder_repeating_<sectionname>“ anzufordern, um eine Liste aller IDs im Abschnitt zu erhalten, die bestellt wurden. Beachten Sie jedoch, dass dies möglicherweise nicht die vollständige Auflistung aller IDs in einem Abschnitt umfasst. Es wird davon ausgegangen, dass alle IDs, die nicht in der Liste enthalten sind und sich im Abschnitt befinden, in lexografischer Reihenfolge nach den geordneten IDs stehen.
Das bedeutet, dass getSectionIDs() alle IDs abruft – jedoch nicht in der Reihenfolge, in der sie dem Benutzer angezeigt werden. getAttrs( "_reporder_repeating_<sectionname>", ... ) gibt eine Liste aller IDs zurück, die aus ihrer normalen lexografischen Reihenfolge verschoben wurden. Sie können die folgende Funktion als Ersatz für getSectionIDs verwenden, um stattdessen die IDs in der Reihenfolge abzurufen, in der sie angezeigt werden.

var getSectionIDsOrdered = function (sectionName, callback) {
  'use strict';
  getAttrs([`_reporder_${sectionName}`], function (v) {
    getSectionIDs(sectionName, function (idArray) {
      let reporderArray = v[`_reporder_${sectionName}`] ? v[`_reporder_${sectionName}`].zu LowerCase().split(','): [],
        ids = [...new Set(reporderArray.filter(x => idArray.includes(x)).concat(idArray)) ];
      Rückruf(IDs);
    });
  });
};

generierenRowID()

Eine synchrone Funktion, die sofort eine neue Zufalls-ID zurückgibt, die Sie zum Erstellen einer neuen Zeile mit sich wiederholenden Abschnitten verwenden können. Wenn Sie setAttrs() verwenden und die ID einer nicht vorhandenen wiederkehrenden Abschnittszeile übergeben, wird eine Zeile mit dieser ID erstellt.

Hier ist ein Beispiel, mit dem Sie eine neue Zeile in einem sich wiederholenden Abschnitt erstellen können:

var newrowid = genericRowID();
var newrowattrs = {};
newrowattrs["repeating_inventory_" + newrowid + "_weight"] = "testnewrow";
setAttrs(newrowattrs);

removeRepeatingRow( RowID )

Eine synchrone Funktion, die sofort alle mit einer bestimmten RowID verknüpften Attribute entfernt und dann die Zeile aus dem Zeichenblatt entfernt. Die RowID sollte das Format „repeating_<sectionname>_<rowid>“ haben. Beispiel: „repeating_skills_-KbjuRmBRiJNeAJBJeh2“.

Hier ist ein Beispiel für das Löschen einer Übersichtsliste, wenn sich die ursprüngliche Liste ändert:

auf("change:repeating_inventory", function() {
   getSectionIDs("repeating_inventorysummary", function(idarray) {
      for(var i=0; i < idarray.length; i++) {
        removeRepeatingRow("repeating_inventorysummary_" + idarray[i]);
      }
   });
});

getTranslationByKey([key])

Eine synchrone Funktion, die sofort die Übersetzungszeichenfolge für den angegebenen Schlüssel zurückgibt. Wenn kein Schlüssel vorhanden ist, wird „false“ zurückgegeben und eine Meldung in der Konsole ausgegeben, die den spezifischen Schlüssel auflistet, der im Übersetzungs-JSON nicht gefunden wurde.

Hier ist ein Beispiel, mit dem Sie eine Übersetzungszeichenfolge aus dem Übersetzungs-JSON abrufen können: Mit dem folgenden Übersetzungs-JSON

{
    „Str“: „Stärke“,
    „Geschick“: „Geschicklichkeit“
}

var strTranslation = getTranslationByKey('str'); // „Stärke“
var dexTranslation = getTranslationByKey('dex'); // „Geschicklichkeit“
var intTranslation = getTranslationByKey('int'); // falsch

getTranslationLanguage()

Eine synchrone Funktion, die sofort den zweistelligen Sprachcode für die vom Benutzer ausgewählte Sprache zurückgibt.

Hier ist ein Beispiel, das Sie zum Abrufen der Übersetzungssprache verwenden können:

var translationLang = getTranslationLanguage(); // „en“ , für ein Konto mit Englisch

setDefaultToken(values)

Eine Funktion, die es dem Blattautor ermöglicht, zu bestimmen, welche Attribute für aus dem Kompendium entfernte Zeichen festgelegt werden. Beim Festlegen des Standard-Tokens nach einem Kompendium-Drop kann diese Funktion beliebige Attribute auf dem Standard-Token festlegen, um wichtige Attribute zu verknüpfen, die für dieses Charakterblatt spezifisch sind, wie z. B. attr_hit_points.

Die Liste der Token-Attribute, die von setDefaultToken festgelegt werden können, ist:

["bar1_value", "bar1_max", "bar2_value", "bar2_max", "bar3_value", "bar3_max", "aura1_square", "aura1_radius", "aura1_color", "aura2_square", "aura2_radius", "aura2_color",
„tint_color“, „showname“, „showplayers_name“, „playersedit_name“, „showplayers_bar1“, „playersedit_bar1“, „showplayers_bar2“, „playersedit_bar2“, „showplayers_bar3“,
„playersedit_bar3“, „showplayers_aura1“, „playersedit_aura1“, showplayers_aura2“, „playersedit_aura2“, „light_radius“, „light_dimradius“, „light_angle“, „light_otherplayers“,
„light_hassight“, „light_losangle“, „light_multiplier“]

Weitere Informationen zu diesen Attributen und ihrer Funktion finden Sie auf der SeiteAPI-Objekte.

Hier ist ein Beispiel:

auf("sheet:compendium-drop", function() {
    var default_attr = {};
    default_attr["width"] = 70;
    default_attr[„height“] = 70;
    default_attr[„bar1_value“] = 10;
    default_attr[„bar1_max“] = 15;
    setDefaultToken( default_attr);
});