Modスクリプト：イベント

2026年09月28日 14:51

on(event, callback) を使用して対応できるイベントには、いくつかの種類があります。イベントの種類は、「ready」、「change」、「add」、「destroy」、「チャット」の5つがあります。 「ready」を除き、名前にはオブジェクト型（チャットの場合はメッセージ）が含まれ、「change」にはプロパティが含まれる場合があります。各イベントは、変更されるオブジェクトごとに1回ずつ発生します。オブジェクト上の複数のプロパティが同時に変更された場合、1つの「グローバル」イベント（たとえばchange:graphic）のみがトリガーされ、さらにバインドされたプロパティ固有のイベントもトリガーされます。

コールバックパラメータ

イベントを監視する場合、そのイベントが発生するたびに実行される「コールバック」と呼ばれる関数を定義します。コールバック関数には、何が変更されたかを示すパラメータが渡されるため、それに基づいてどう対応するかを判断できます。

イベント	引数
`準備完了`	無し
`変更`	`obj`（変更後のRoll20オブジェクト）、`prev`（以前のプロパティを持つプレーンオブジェクト）
`追加`	`obj`（新しいオブジェクト）
`破壊する`	`obj`（削除されたオブジェクト。キャンペーン内にまだ存在していると想定しないでください）
`チャット`	`msg`— 「Modスクリプト：チャット」を参照

obj

変更されたオブジェクト。このオブジェクトに加えた変更は、ゲームにも保存されます。したがって、Graphicオブジェクトを左に移動させたい場合は、set を使ってobjのleftプロパティを変更します。

obj.get("property")は、そのプロパティの現在の値を返します。
obj.set("property", "newvalue")は、プロパティに新しい値を設定します。複数のプロパティを一度に変更する場合は、オブジェクトを渡すことができます：obj.set({left: 10, top: 20})。

これは、このイベントによって変更が行われる前の、objのプロパティを表すオブジェクトです。物件が「どの程度」変化したかを判断するのに役立ちます。

注： prev はRoll20 のオブジェクトではありません。角括弧表記またはドット表記を使用してプロパティにアクセスします：prev["bar1_value"]またはprev._id。このフィールドに対してgetやset を呼び出すことはできません。また、読み取り専用キーではアンダースコアを省略することはできません（prev.id は prev._id ではありません）。

キャラクターやハンドアウトについてですが、前の投稿にある「bio」、「notes」、「gmnotes」といったフィールドは、テキストそのものではなく、内部識別子です。 _defaulttokenという文字列も BLOB です。「graphicgmnotes」は単なる文字列です。必要に応じて、以前のBLOBの値を自分でキャッシュしておいてください。

イベント順序付け

イベントは、最初にバインドされたものから最後にバインドされたものへと順に、また特定のプロパティから一般的なオブジェクトへと順に、同期的に（前の関数が終了するまで次の関数は開始されない）発生します。では、以下の条件を前提として：

on("change:graphic", function1);
on("change:graphic", function2);
on("change:graphic:left", function3);

オブジェクトの「left」プロパティが変更された場合、順序は「function3」、「function1」、「function2」の順になります。

キャンペーンに複数のスクリプトが含まれている場合、それらのスクリプトは「Mod Scripts」設定ページに表示される順序（左から右）で読み込まれます。

注：スクリプトのset()メソッドは、そのプロパティに対して変更イベントを発生させません。プレイヤーがコマを移動させると、change:graphic が表示されます。その後、スクリプトがset() を使ってleft の値を変更しても、その変更によってchange:graphic は発火しません。スクリプトからグラフィックを作成すると、change:graphic イベントが発生します。 sendChat() は、!で始まるメッセージを含め、チャット:message を発火させます。. Virtualstatus_*プロパティは独自のイベントを発火しません。change:graphic:statusmarkers を監視してください。

準備完了

このイベントは、サンドボックスが起動するたびに、キャンペーンデータが読み込まれた後に1回ずつ発生します。準備が整ってから、既存のオブジェクトを検索してください。 readyイベントが発生する前にaddイベント（add:graphicなど）をバインドすると、キャンペーンにすでに存在していたオブジェクトに関するaddイベントも受信することになります。スクリプトは「Mod Scripts」の設定順（左から右）で読み込まれ、readyハンドラはバインドされた順に実行されます。

コールバックパラメータ：なし

on("ready", function() {
  var tokenThatAlreadyExisted = getObj("graphic", "-ABc123");
});

チャットイベント

`チャット:メッセージ`

sendChat() で送信されたメッセージを含め、新しいチャットメッセージを受信するたびにトリガーされます。コールバックには、msgオブジェクトが渡されます。メッセージの種類には、general、rollresult、gmrollresult、secretrollresult(/sr)、supersecretrollresult(/ssr)、emote、秘話、desc、direct、およびapiがあります。 !で始まるメッセージ type === "api"であり、チャットには表示されません。

コールバックパラメータ：msg

msgプロパティの完全な一覧およびダイス結果の処理については、「Mod Scripts: チャット」を参照してください。

キャンペーンイベント

キャンペーンオブジェクトは、任意のキャンペーンプロパティに対して、change:campaignおよびchange:campaign:PROPERTYをサポートしています。ほとんどのスクリプトが監視対象としているのは、以下のものです：

`変更:キャンペーン:プレイヤーページID`

プレイヤーが現在表示しているページが変更されるたびに発火する。

`変更:キャンペーン:ターン順序`

キャンペーンのターン順番リストが変更されるたびに発動する。

`変更:キャンペーン:イニシアチブページ`

ページごとにターン順番が非表示または表示されるたびに発火する。これは現在アクティブなページのIDとは異なる可能性があります。これがfalseに設定されている場合（Mod スクリプトによってfalse に設定された場合も含む）、すべての GM およびプレイヤーのターン順番が閉じられます。有効なページIDを設定すると、すべてのGM/プレイヤーに公開されます。

オブジェクトイベント

各オブジェクト型は以下をサポートしています：

add:TYPE
変更：TYPE
変更:タイプ:プロパティ
destroy:TYPE

特定のオブジェクトIDにバインドすることも可能です：change:TYPE:ID、change:TYPE:ID:PROPERTY、およびdestroy:TYPE:ID。

各タイプのプロパティについては、「Modスクリプト：オブジェクト」を参照してください。

`変更:グラフィック`

グラフィックオブジェクト（コマ、マップ、カードなど、卓上にあるほぼすべてのオブジェクト）が変更されるたびにトリガーされます。

注：スクリプトによって作成されたグラフィックオブジェクトは、作成時にこのイベントをトリガーします。

コールバックの引数：obj、prev

on("change:graphic", function(obj, prev) {
  //ここで「obj」を使って何か処理を行う。 "prev" は過去の値のリストです。
  // 注意：「obj」と「prev」は異なるタイプのオブジェクトです。
  // obj を操作するには obj.get("name"); を使用する必要があります。
  // prev を操作するには prev["name"]; を使用できます。
});

`変更:グラフィック:(プロパティ)`

オブジェクト上の各特定プロパティに対してイベントをバインドすることもできます。したがって、ローテーションが変更されたときのみ実行したいスクリプトがある場合は、次のようにします：

on("change:graphic:rotation", function(obj, prev) {
  //回転角度を常に0に戻すように設定し、オブジェクトを回転できないようにする。
  obj.set("rotation", 0);
});

`add:graphic`

グラフィックオブジェクトが卓上に初めて追加されるたびにトリガーされる。「ready」イベント以外でこのイベントにバインドしている場合、卓上の起動時に既存のオブジェクトに対してもこのイベントが呼び出されます。

コールバックの引数：obj

var started = false;
on("add:graphic", function(obj) {
  if (!started) return;
  // ready後に追加されたグラフィックのみ。
});
on("ready", function() {
  started = true;
});

`破壊:グラフィック`

グラフィックオブジェクトが卓上から削除されるたびにトリガーされる。

コールバックの引数：obj

グラフィックのサブタイプ

グラフィックスも、_subtype を使用してイベントを発火します。マップでは「token」サブタイプが使用されます。

サブタイプ	イベント	メモ
`置く`	`add:token` `変更:token` `変更:token:PROPERTY` `destroy:token`	コマとマップのグラフィック。
`カード`	`add:card` `変更:card` `変更:カード:プロパティ` `削除:カード`	卓上に置かれたカード（グラフィック）。以下の注記をご覧ください。
`dicetoken`	`add:dicetoken` `変更:dicetoken` `変更:dicetoken:PROPERTY` `削除:dicetoken`	卓上にあるダイスシンボル。

「card」はRoll20 のオブジェクトタイプであると同時にグラフィックのサブタイプでもあるため、「change:card」などのイベントのハンドラーでは、オブジェクトタイプを明確に区別する必要があります（例：obj.get("_type"））。そうすることで、正しい種類のオブジェクトに対してイベントが確実に発火するようにします。

すべてのオブジェクトタイプ

以下の各型は、add:TYPE、change:TYPE、change:TYPE:PROPERTY、およびdestroy:TYPEをサポートしています。

種類	イベントの例	メモ
`技能`	`add:技能` `変更:技能` `destroy:技能`
`ステータス`	`add:attribute` `変更:能力値` `削除:能力値`
`キャンペーン`	`変更:キャンペーン` `change:campaign:playerpageid`	キャンペーンオブジェクトは1つだけです。スクリプトは通常、`追加や破棄`ではなく、`変更`を監視します。
`カード`	`add:card` `変更:カード` `カードを削除`	デッキカードオブジェクト。また、グラフィックサブタイプでもあります —`_type` で曖昧さを解消してください。
`キャラクター`	`add:キャラクター` `変更:キャラクター` `キャラクターを削除する`
`custfx`	`add:custfx` `変更:custfx` `削除:custfx`	カスタムFX。
`デッキ`	`add:deck` `変更:デッキ` `破棄:デッキ`
`ドア`	`追加：ドア` `変更:ドア` `削除:ドア`	最新のVTTエンジン。
`グラフィック`	`add:graphic` `変更:グラフィック` `グラフィックの削除`	また、サブタイプのイベント（`コマ`、`カード`、`ダイストークン`）も発生させます。
`手`	`add:hand` `変更:hand` `削除:hand`
`ﾊﾝﾄﾞｱｳﾄ`	`add:ハンドアウト` `変更: ハンドアウト` `削除:ハンドアウト`
`ジュークボックスの曲`	`add:jukeboxtrack` `変更:jukeboxtrack` `削除:jukeboxtrack`
`マクロ`	`add:マクロ` `変更:マクロ` `削除:マクロ`
`ページ`	`add:page` `変更:ページ` `ページを削除`	階層の変更により、`change:page:_placement`および`change:page:_path` もトリガーされます。
`pageFolder`	`add:pageFolder` `変更:pageFolder` `削除:pageFolder`	Mod Script サンドボックス v1.5 専用です。
`パス：`	`add:path` `変更:パス` `削除:パス`	昔ながらの卓上のスケッチ。
`pathv2`	`add:pathv2` `変更:pathv2` `削除:pathv2`	最新のVTTエンジン。
`ピン`	`add:pin` `変更:ピン` `destroy:pin`	最新のVTTエンジン。
`プレイヤー`	`add:player` `change:player` `プレイヤーを削除`
`rollabletable`	`add:rollabletable` `変更:rollabletable` `削除:rollabletable`
`tableitem`	`add:tableitem` `変更:tableitem` `削除:テーブル項目`
`テキスト`	`add:text` `変更:text` `削除:text`
`窓`	`add:window` `変更:ウィンドウ` `destroy:window`	最新のVTTエンジン。

Mod Script サンドボックス v1.5 専用です。 pageFolderオブジェクトには、add:pageFolder、change:pageFolder、destroy:pageFolder といったイベントや、change:pageFolder:name のようなプロパティイベントがあります。また、ページのメニュー階層が変更されると、ページは `change:page:_placement` および`change:page:_path` も発火します。

Jumpgate / 最新のVTTエンジンオブジェクトタイプ（pathv2、pin、window、door）は、VTTエンジンの機能であり、サンドボックス版の機能ではありません。最新のVTTエンジンで動作するv1.0のゲームには、依然としてそれらのオブジェクトタイプとそのイベントが残っています。