D&D 2024/Beacon用MOD（API）スクリプトの更新方法

2025年03月05日 15:57

多くのスクリプトでは、2024年シートと互換性を持たせるためのアップデートは、属性の取得・設定方法とロール・テンプレート／チャット・メッセージの解析方法の2つを変更することに尽きる。この文書では、D&D2014 シートと D&D2024 シートの両方に対応するようにスクリプトを更新できるように、両方の手順を説明し、よくある問題のトラブルシューティングも行います。

この方法でスクリプトが更新された場合、D&D2024のようなBeaconシートを使用するゲームでは、GMはすべての最新機能を使用するためにExperimental APIサーバーを使用する必要があります。 Experimentalサーバーは、Defaultサーバーと同じ機能をすべて備えているので、この切り替えを行っても他のスクリプトが壊れることはありませんが、ユーザーにわかるようにスクリプトの説明でその旨を伝えておくとよいでしょう。 Beaconシートがない場合、Defaultサーバーは、レガシーな属性取得・設定関数にフォールバックするため、これらの関数でも動作します。

設定／取得の更新

2014年シートと2024年シートのデータへのアクセスで、コード的に大きく変わったのは、属性の取得と設定方法だ。 getSheetItemと setSheetItemという新しい非同期関数が追加された。新しい関数の使用例を挙げよう：

const getDeathSaveSuccess = async (id) => {
 const firstSuccess = await getSheetItem(characterId, "deathsave_succ1");
 log(`First success is ${firstSuccess}`)
}.

属性の最大値を取得したい場合（最大値が存在する場合）、getSheetItem(characterId, "deathsave_succ1","max");のように、プロパティmaxを渡すことができます。

上のコードで、getDeathSaveSuccessが非同期とマークされていることに気づくだろう。 getSheetItemを使うすべての関数は、この非同期／待機パターンを使うか、プロミスを使わなければならない。上記と同じ関数をプロミスに書き換えたものがこちら：

const getDeathSaveSuccess = (id) => {
 getSheetItem(characterId, "deathsave_succ1").then((firstSuccess) => {
 log(`最初の成功は ${firstSuccess}`);
 });
}.

複数の値を一度に、あるいは次々に取得しようとしていて、コードの残りの部分がそのデータを持っていることに依存している場合、それぞれの値を個別に待ち受けるか、Promise.allを使ってすべてのプロミスを一度に解決し、最終的な値を取得することができます。そうしないと、返される値は保留中の約束に過ぎず、属性の実際の値にはなりません。

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(`First success is ${results[0]}, second success is ${results[1]}, third success is ${results[2]}`);
 }
}.

非同期コードは、スクリプトをどのように構成するかによって、スクリプトの書き方にさまざまな影響を及ぼす可能性がある。例えば、現在replaceや mapの中でgetAttrByNameを使用しているスクリプトがある場合、これらの関数は値が戻ってくるのを待たずに処理を続行するため、より非同期に近いループに分割する必要があります。

複数の値を一度に、あるいは次々に取得しようとしていて、残りのコードがそのデータを持っていることに依存している場合」と書いたところまで巻き戻そう。あなたのコードの残りの部分は、常にその値を持っていることに依存しているわけではない。ほとんどの場合、getSheetItemを使用している場合、その値に依存する。しかし、その逆のsetSheetItemでは、終了を待つ必要がないことも多い。その場合、これらの関数が非同期であることの影響を無視して、普通に呼び出すことができる。この属性は、スクリプトの実行中にバックグラウンドで更新される。

setSheetItem関数は、getSheetItemと同じように動作しますが、属性を何に設定するかを決定するための追加引数を含んでいます。

setSheetItem(characterId, "hp", 10);
setSheetItem(characterId, "hp", 20, "max")；

ロール解析の更新

その他に、5eのスクリプトの多くで更新が必要なのは、ロールの解析だ。チャットに送信されるロールは、まったく異なるフォーマットになっており、結果を得たり、内容の詳細を知るためには、異なる解析を行う必要がある。開発チームはHTMLにいくつかのデータ属性を追加し、HTMLを解析する必要性を最小限に抑えましたが、より複雑なデータが必要な場合は、チャットに送信されたメッセージから解析する必要があるかもしれません。一般的なニーズを以下にまとめましたので、参考にしてください。

標準的なロール・テンプレートでロールの結果を得る：

const rollResultMatch = msg.content.match(/data-result="(.+?)"/)；

タイトルからどんなロールなのかを確認する：

const deathSaveMatch = msgContent.match(/header__title">ここにヘッダーを挿入<\/div>/)；

呪文のレベルやダメージの種類などを知るために、ロールのサブタイトルをチェックすること：

const spellLevelMatch = msgContent.match(/header__subtitle">レベル（.+?） /);

2024年版シートはまだ開発中なので、ロール・テンプレートが変更され、スクリプトの更新が必要になる可能性があります。 HTMLをパースする文字列がいつまでも安定していることを約束することはできませんが、シートをさらに発展させながら、より標準化されたテンプレートを目指しています。上記の例は、単純化のために正規表現がやや固くなっているが、ロールテンプレートがまだ流動的である間は、ファジーマッチやワイルドカードを使用して、マッチングをより強固にすることをお勧めする。

よくある問題

「エラー：character_id (ここにあなたのID) の名前 (ここにあなたの属性) に対応する属性またはシートフィールドが見つかりません。

考えられる原因おそらくExperimental APIではなくDefault APIを使用していて、Beaconが計算したプロパティにアクセスしようとしているのでしょう。 Restart Server（サーバーの再起動）」をクリックする際、APIの再起動メッセージに「DEFAULT（デフォルト）」ではなく「EXPERIMENTAL（実験的）」という単語が含まれていることを確認してください。ドロップダウンがExperimentalに設定されているにもかかわらず、再起動のログにDEFAULTと表示されている場合は、Defaultに切り替えて再起動し、Experimentalに切り替えて再起動してください。これはDefaultとExperimentalの入れ替えに関する既知の問題で、現在調査中です。

getSheetItemの結果が値ではなく空のオブジェクトをロギングしている。

原因として考えられるのは、getSheetItem関数を待っていないか、.thenを使用していないこと。値が戻るのを待ってからコードを進めなければならない。