シートワーカー・スクリプト

2024年11月06日 11:06

シートワーカー・スクリプトの追加

キャラクター・シートにシートワーカー・スクリプトを追加するには、シートの "HTML "セクションに以下のフォーマットでスクリプトを追加するだけです：

<script type="text/worker">

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

});

// ... etc

</script>

スクリプト・タグは、システムによって適切に処理されるために、タイプが「text/worker」でなければならないことに注意。ゲームがロードされると、すべてのスクリプトタグは、セキュリティのために、シートのテンプレートから削除されます。しかし、"text/worker "というタイプのスクリプトタグは、各プレイヤーのコンピュータ上でバックグラウンドワーカーを立ち上げるために使われます。すべてのシートワーカースクリプトは、1つのスクリプトタグに含める必要があります。

ノンプログラマーを対象とした、より包括的な基本例

グローバル "変数のスコープに関する警告:<script type="text/worker">` の内部で宣言された変数のスコープで、関数の外部で宣言された変数のスコープは、現在のところ、キャラクターごとではなく、プレイヤーごとになります。この値を変更すると、プレイヤーのセッションのすべてのキャラクターに対して変更されます。

ベストプラクティスとして、非同期カスケードは可能な限り避けるべきである。一般的には、getAttrs -> 計算 -> setAttrs -> getAttrs -> 計算 -> setAttrs…を実行するよりも、getAttrs で計算に必要なすべての属性を取得する方が良い方法です。

シートワーカー vs 自動計算フィールド：どちらを使うべきか？

これについては厳密なルールはない。これらのツールはどちらも同じことを実現できる。例えば、"Strength "属性を使って、"Strength Mod "属性を更新し続けたい場合を考えてみよう。このユースケースにおける2つのツールの違いは以下の通りだ：

自動計算フィールドは、シートを初めて開くたびにすべて再計算されます。一方、Sheet Workerフィールドは、従属値が変更されたときのみ再計算される。つまり、シート・ワーカー・オプションを利用したシートは、プレーヤーが開いて操作するのがずっとずっと速くなるということだ。

さらに、Sheet Workerの計算はバックグラウンドプロセスで実行されるため、計算の実行中にユーザーインターフェイスにタイムラグが生じることはない。一方、無効化フィールドはメインプロセスで実行されるため、一度に大量の無効化フィールドが計算される場合（例えば、何千もの無効化フィールドを使用する非常に複雑なシートの場合）、「ロックアップ」や「スタッタリング」を引き起こす可能性があります。

自動計算されるStrength Modフィールドは、プレイヤーには無効になっているように見える。一方、シート・ワーカーによって更新されるストレングス変更フィールドは、計算実行後に変更可能である（ただし、ストレングス値が変更されると、入力された値は上書きされる）。つまり、シート・ワーカーを使えば、戦力が変化した後にMODの値を修正するだけでよいので、自作ルールに対応しやすくなる。一方、自動計算フィールドはそのような変更を許さないので、ルールはより厳格に「強制」されることになる。

一般的に、自動計算フィールドは控えめに使用することをお勧めします。自動計算フィールドの予算は、せいぜい500から1,000程度にしておきましょう。私たちは、ほとんどの計算、特にめったに実行する必要のない計算（例えば、体力の値（したがって体力Mod）は、おそらくキャラクターのレベルアップ時に1セッションにつきせいぜい1回しか変更されないでしょう）には、新しいSheet Worker機能を使用することを推奨します。シートを開くたびに同じ計算を何度もやり直す必要はない。

シートワーカーAPI

イベント

eventInfo オブジェクト

多くのイベントには、そのイベントの状況についての追加情報を提供するeventInfoオブジェクトが渡される。

プロパティ	説明
`ソース属性`	イベントをトリガーした元の属性。これは、このイベントを最初にトリガーした属性の完全な名前（リピーティング・セクションの場合はRowIDを含む）です。注意: 文字列全体が小文字に変換されるため、getAttrs()に直接入力するには適さないかもしれません。
`ソースタイプ`	イベントをトリガーしたエージェント（`選手`または`シートワーカー`
`前の値`	属性が変更される前の、`on:change`イベントにおける属性の元の値。
`新しい値`	`on:change`イベントの属性が変更された値。
`削除情報`	`remove:repeating_groupname`イベントで削除されたすべての属性の値を含むオブジェクト。

変更:<属性名>

特定のアトリビュートの変化、またはリピート・セクションの場合はセクション全体の変化を聞くことができる。とても簡単なことだ：

on("change:Strength change:StrengthMod change:StrengthOtherThing",function(eventInfo) {
   //ここで何かを行う
   // eventInfo.previousValue は、このイベントをトリガーした属性の、変更される前の元の値です。
   // eventInfo.newValueは、このイベントをトリガーした属性の、変更された現在の値です。
});

on("change:repeating_spells:spellname",function(eventInfo) {
   //ここで何かを行う
   // eventInfo.sourceAttributeは、  元々このイベントをトリガーした  属性 
   // の完全な名前（リピーティングIDを含む）です  。 
   // しかし、文字列全体が小文字に変換されているため、 
   //  最初に破壊されることなく、 直接
   // getAttrs()または他の用途に 投入するには適して いないかもしれません  。
});

on("change:repeating_spells",function(eventInfo) {
   //repeating_spellsセクションのいずれかの属性が変更されたときにトリガーされる
   // eventInfo.sourceAttributeは、 このイベントを最初にトリガーした属性の完全な名前（小文字）（リピートIDを含む） 
   // です。 
});

注：イベントでは、属性名はすべて小文字になります。そのため、通常は属性を「Strength（強さ）」と呼ぶ場合でも、イベント・リスナーでは「change:strength」を使用する。

注：これは"_max "接尾辞をサポートしており、"change:strength "または "change:strength_max "のどちらかがイベントを発生させるが、これら2つのバリエーションは、どちらか、または両方が、"strength "または "strength_max "が変化したときに発生するという点で、互換性があるようだ。

繰り返しフィールドの属性の場合、"repeating_spells_SpellName "属性が更新されると、以下のすべてがトリガーされます："change:repeating_spells:spellname"、"change:repeating_spells"、"change:spellname"、"change:spellname_max"。これにより、どの「レベル」の変更イベントに関数をバインドするかを柔軟に選択することができる。

シートワーカーは、リピーター・セクションが並び替えられるたびに変更される特別な属性の変更イベントをリッスンすることもできる。

on("change:_reporder:<sectionname>",function(eventInfo) {
   // ここで <sectionname> 上記は、スキルや呪文のような繰り返しのセクション名
})；

remove:repeating_<グループ名>

これは、リピーティング・フィールド・セクションから行が削除されるたびに発生するイベントです。 IDがわかっていれば、on("remove:repeating_inventory:-ABC123")のように、特定の行が削除されるのを待つこともできます。

on("remove:repeating_inventory",function(eventInfo) {
     //repeating_inventoryから行が削除されるたびに発生
     //eventInfo.sourceAttributeは、イベントをトリガーした最初の属性の完全な名前（IDを含む）です（これを使用して、削除された行のIDを決定できます）
}）；

removed:repeating_<groupname> 関数のeventinfoには、現在削除されているリピーティング・セクションのすべての属性を表示する特別なプロパティremovedInfoが含まれています。

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

シート：オープン

このイベントは、ゲームセッションでプレイヤーがシートを開くたびに発生します。必要なシートのアップグレードのチェックなどに役立つはずだ。

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

// セッションでプレイヤーが初めてシートを開いた時に何かをする

})；

clicked:<ボタン名>

このイベントは、アクションボタンがクリックされたときにトリガーされます。ボタンの名前は "act_"で始まる必要がある。例えば、こうだ：

<button type="action" name="act_activate">アクティブ化する！</ボタン>

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

機能

getAttrs(attributeNameArray,コールバック) 非同期

getAttrs関数を使用すると、シートから一連の属性の値を取得することができます。接尾辞"_max "がサポートされているので、getAttrs( ["Strength", "Strength_max"], func)は、"Strength "の現在値と最大値の両方を取得する。この関数は非同期式である。つまり、複数のgetAttrs呼び出しが行われた順番が、結果が返される順番であるという保証はない。そうではなく、値が計算されたときに実行されるコールバック関数を渡します。コールバック関数は、リクエストされた属性ごとに1つずつ、キーと値のペアのリストを持つシンプルなJavascriptオブジェクトを受け取ります。

例を挙げよう：

on("change:strength",function( {
   getAttrs(["Strength","Level"],function(values) {
      //values.Strengthおよび/またはvalues["Level" ]で何かをする
   });
})；

繰り返しセクションの値は、少し特別な扱いが必要である。もし、あなたが今いるイベントがすでにリピーティング・セクションの中にある場合、リピーティング・グループ名の前に変数名を付けてリクエストするだけで、イベントがトリガーされたのと同じリピーティング・セクションで値を受け取ることができます。例えば、SpellName、SpellLevel、SpellDamageの両方を持つrepeating_spellsセクションがあるとする：

on("change:repeating_spells:spelllevel",function() {
   getAttrs([
      "repeating_spells_SpellDamage",
      "repeating_spells_SpellName"
    ],function(values) {
      //values.repeating_spells_SpellDamageとvalues.repeating_spells_SpellName 
//両方とも、変更されたSpellLevelと同じリピーティングセクションの行になります。
   });
})；

一方、現在リピーティング・セクションにいない場合は、リピーティング・セクションの行にあるフィールドのIDを手動で指定して、その値を要求することができる：

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

また、"_reporder_repeating_<sectionname>" 属性をgetAttrs()でリクエストすることで、オーダーされたセクションのすべてのIDのリストを取得することができます。ただし、セクション内のすべてのIDのリストが含まれるとは限らないことに注意。セクション内にあるリストにないIDは、辞書順に並べられたIDの後に来るものとみなされる。

setAttrs(values,options,callback) 非同期

values（値） -- このオブジェクトのプロパティは属性名（attr_接頭辞なし）で、値はその属性に設定したい値です。

options-- （オプション）関数のオプションの動作を指定するオブジェクトです。現在のところ、唯一のオプションは "silent "であり、指定された属性を設定することによる変更イベントの伝播を防ぎます。

callback-- （オプション）設定された属性が更新されたときに実行されるコールバック関数です。

setAttrs関数を使うと、キャラクターシートの属性を設定することができます。属性の最大値を設定するには、接尾辞"_max "を使用します。例えば "Strength_max"。

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

注：この方法で無効な入力フィールドを更新しようとすると、問題が発生する可能性があります。一つの方法として、この `setAttrs` メソッドを使って非表示の入力を設定し、その非表示の要素に無効な入力を設定することができる。この例では、willという名前の属性があり、willのスタッツの1/2に基づいて判定を計算したいが、90を超えないようにしたい。下記参照。

<ラベル>判定</ラベル>
<入力タイプ="hidden"  name="attr_foo_judgment"  value="0"/>
<input type="number"  name="attr_judgment"  value="@{foo_judgment}"  disabled="true"title="1/2切り捨て、最大90"/ラベル>

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

setAttrsは非同期関数であり、複数のsetAttrs()を呼び出した場合にどの順番で実際の属性が設定されるかは保証されていないことに注意してください。

リピーティング・セクションでは、元のイベントがリピーティング・セクションにある場合、単純な変数名を使用するか、任意のイベントでIDを含む完全なリピーティング・セクション変数名を指定することができます。

on("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)非同期

この関数は、指定されたリピーター・セクションに現在存在するIDのリストを取得することができる。これは、在庫の計算など、行数が変動する場合に便利である。

on("change:repeating_inventory",function() {
   getSectionIDs("inventory",function(idarray) {
      for(var i=0; i <idarray.length; i++) {
         //IDで何かをする
      }.
   });
})；

GetAttrs()（前述）を使用して、"_reporder_repeating_<sectionname>" 属性をリクエストし、順序付けられたセクション内のすべてのIDのリストを取得することができることに注意してください。ただし、これにはセクション内のすべてのIDのリストが含まれるわけではないことに注意。
つまり、getSectionIDs()はすべてのIDを取得しますが、ユーザーに表示される順番ではありません。 getAttrs( "_reporder_repeating_<sectionname>", ... ) は、通常の辞書順から移動したすべてのIDのリストを返す。 getSectionIDsの代わりに以下の関数を使用すると、IDを表示順に取得することができます。

vargetSectionIDsOrdered= function(sectionName, callback) {
  'use strict';
  getAttrs([`_reporder_${sectionName}`],function(v) {
    getSectionIDs(sectionName,function(idArray) {
      let reporderArray=v[`_reporder_${sectionName}`] ? v[`_reporder_${sectionName}`].toLowerCase().split(',') ：[],
        ids=[...new Set(reporderArray.filter(x => idArray.includes(x)).concat(idArray))];
      callback(ids);
    });
  });
}；

generateRowID()

新しいリピーティング・セクションの行を作成するために使用できる、新しいランダムなIDを即座に返す同期関数。 setAttrs() を使用して、存在しないリピーティング・セクション行の ID を渡すと、その ID を持つ行が作成されます。

以下は、繰り返しセクションに新しい行を作成する例です：

varnewrowid= generateRowID();
varnewrowattrs={};
newrowattrs["repeating_inventory_" +newrowid+ "_weight"]= "testnewrow";
setAttrs(newrowattrs)；

removeRepeatingRow( RowID )

指定されたRowIDに関連付けられたすべての属性を直ちに削除し、文字シートから行を削除する同期関数。 RowIDは、"repeating_<sectionname>_<rowid>" という形式でなければならない。例えば、"repeating_skills_-KbjuRmBRiJNeAJBJeh2"。

以下は、元のリストが変更されたときに、要約リストを消去する例である：

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

getTranslationByKey([キー])

与えられたキーに関連する翻訳文字列を即座に返す同期関数。キーが存在しない場合、falseが返され、コンソールに翻訳JSONで見つからなかった特定のキーをリストしたメッセージが投げられます。

翻訳JSONから翻訳文字列を取得する例を以下に示します。

{
    "str"："Strength",
    "dex"："Dexterity"
}.

varstrTranslation= getTranslationByKey('str');// "Strength"
vardexTranslation= getTranslationByKey('dex');// "Dexterity"
varintTranslation= getTranslationByKey('int');// false

getTranslationLanguage()

ユーザーが選択した言語の2文字の言語コードを即座に返す同期関数。

以下は、翻訳言語を取得するために使用できる例です：

vartranslationLang= getTranslationLanguage();// "en" , 英語を使用するアカウント用

setDefaultToken(値)

シート作成者が、大要からドロップされた文字にどのような属性が設定されるかを決定できるようにする関数。コンペンディウム・ドロップ後にデフォルト・トークンを設定するとき、この関数はデフォルト・トークンに任意の属性を設定し、attr_hit_pointsのような、そのキャラクター・シートに固有の重要な属性を結びつけることができます。

setDefaultTokenで設定できるトークン属性のリストは以下のとおりです：

["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"].

この属性とその役割の詳細については、MOD（API）オブジェクトのページを参照してください。

例を挙げよう：

on("sheet:compendium-drop",function() {
    vardefault_attr={};
    default_attr["width"]= 70;
    default_attr["height"]= 70;
    default_attr["bar1_value"]= 10;
    default_attr["bar1_max"]= 15;
    setDefaultToken(default_attr);
})；