API: イベント

2025年11月07日 18:31

コールバックパラメータ

イベントを監視する際、そのイベントが発生するたびに実行されるコールバックと呼ばれる関数を作成します。コールバック関数は複数のパラメータを受け取ります。これらはイベントに関する知りたい情報を伝えるオブジェクトであり、それに基づいて何をすべきかを判断できます。

各イベントのコールバックパラメータは異なりますが、以下を含みます：

obj

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

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

イベント順序付け

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

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

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

さらに、キャンペーンに複数のスクリプトがある場合、それらのスクリプトはキャンペーンスクリプトページに表示される順序（左から右へ）と同じ順序で読み込まれます。

注：イベントは、プレイヤー／ゲームを進行するGMによる変更によってのみ発生します。 APIの変更によってイベントはトリガーされません。プレイヤーが卓上上で駒を動かすと、「change:graphic」イベントを受け取ることになります。 Mod（API）スクリプト内で同一グラフィックのプロパティを変更した場合、「change:graphic」イベントは発生しません。

キャンペーンイベント

準備完了

このイベントは、キャンペーンの現在のデータがすべて読み込まれた後に発生します。したがって、キャンペーン内の全オブジェクトのリストや、既にキャンペーン内にある特定のオブジェクトを検索したい場合は、必ずreadyイベントが発火した後に検索するようにしてください。さらに、readyイベントが発生する前にaddイベント（例：add:graphic）をバインドすると、キャンペーンに既に存在していたオブジェクトに対するaddイベントを受信することになります。

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

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

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

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

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

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

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

オブジェクトイベント

変更:グラフィック

グラフィックオブジェクト（卓上のほぼあらゆる種類のオブジェクト、トークン、マップ、カードを含む）が変更されるたびに発動する。

注記: APIで作成されたグラフィックオブジェクトは、作成時にこのイベントをトリガーします。

コールバックパラメータ: 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

on("add:graphic", function(obj) {
  //プレイセッション開始時に既に存在していたものも含め、すべての新しいグラフィックに対して呼び出されます。
});

var started = false;

on("ready", function() {
  on("add:graphic", function(obj) {
    //既存オブジェクトはreadyイベント発火前に既に読み込まれているため、新規追加オブジェクトに対してのみ呼び出される。
  });
  //変数を設定し、それが真になるまでaddイベントを無視することもできます。
  started = true;
});

破壊:グラフィック

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

コールバックパラメータ: obj

その他のオブジェクトタイプ

その他のオブジェクトタイプやサブタイプにもイベントが存在します。例えば：

変更:パス, 追加:パス, 削除:パス, 変更:テキスト, 追加:テキスト, 削除:テキスト, 変更:コマ, 追加:コマ, 削除:コマ, 変更:カード, 追加:カード, 削除:カード

参照オブジェクトリファレンスを参照してくださいすべてのオブジェクトタイプとサブタイプの完全なリストについては、オブジェクトリファレンスを参照してください。