API: ユーティリティ関数

2025年11月07日 18:32

アンダースコア・ジェイエス

アンダースコア.jsライブラリ（_グローバルオブジェクト経由）を利用でき、作業を容易にします。アンダースコアは、_.each（オブジェクトの配列を反復処理する）などのためのヘルパー関数を提供します。以下のドキュメントを確認してくださいアンダースコアのドキュメントをご覧ください。

伐採

log(メッセージ)

この関数を使用すると、スクリプトエディタページのMod（API）コンソールに出力を記録できます。スクリプトのデバッグや、Mod（API）サンドボックス内部の動作状況を把握するのに役立ちます。

on("change:graphic", function(obj) {    
  log("オブジェクトID: " + obj.id + " の変更を検知しました");
});

オブジェクトの順序付け

toFront(obj)とtoBack(obj)

これらの2つの機能は、卓上上のオブジェクトを、現在配置されているレイヤーの前面（または背面）に移動します。実際のオブジェクト（イベントコールバックで受け取ったものや、`getObj`または`findObjs`を呼び出して取得したものなど）を渡す必要があることに注意してください。

乱数

ランダムな整数(最大値)

この機能はサイコロ用です！ この関数はモジュロバイアスを考慮しており、これにより生成される乱数も1からMAXの間で均等に分布します。

1から最大値max までの範囲で、ランダムな整数を返します。これはRoll20がダイスロールに採用しているのと同じ機能であり、これらの数値は統計的かつ厳密にランダムであることが証明されています。

Math.random()

Mod（API）スクリプト内で通常通り Math.random() を呼び出せます。その結果がランダムであると信頼できるのは、JavaScript の「デフォルト」Math.random() が、Roll20 を支える暗号学的に安全な乱数生成器（PRNG）に置き換えられているためです。したがって、Math.random() を使用する既存のスクリプトは、その結果がコンピュータ上で可能な限り真にランダムに近いものであることを認識した上で使用できます。

範囲内の数値を均等に分布させたい場合は、Math.random() を使用しないでください。 Math.random()はRoll20が処理可能な範囲で十分な乱数を生成しますが、その乱数を均等分布の範囲（サイコロの振りのような）に変換する計算は、モジュロ演算やフロア関数を用いた乗算ほど単純ではありません。それらのケースにはrandomInteger(max)を使用してください。

プレイヤーはGMです

playerIsGM(プレイヤーID)

「プレイヤーはGMか」機能は、ゲーム内のプレイヤーがGMであるか否かについてブール値の応答を返します。この関数は常に現在の状況に応じて正しい結果を返すため、GMがプレイヤーとして再参加を選択した場合や、ゲーム中にプレイヤーがGMに昇格した場合でも、playerIsGM()はキャッシュのクリアやMod（API）サンドボックスの再起動を必要とせず、適切に応答します。

キャラクター

setDefaultTokenForキャラクター( キャラクター, コマ )

指定されたキャラクターオブジェクトのデフォルトのコマを、指定されたコマオブジェクトの詳細に設定します。両方のオブジェクトは既に存在している必要があります。これにより、キャラクターに現在関連付けられているデフォルトのコマは上書きされます。

特殊エフェクト (FX)

spawnFx(x, y, タイプ, ページID)

指定された位置（x,y）に、指定されたタイプの短い効果を生成する。ページIDを省略するか、または「undefined」を渡した場合、プレイヤーが現在いるページ（Campaignオブジェクト内の「playerpageid」）がデフォルトで使用されます。

組み込みエフェクトのタイプは文字列で、以下のいずれかである必要があります：beam-color,bomb-color,breath-color,bubbling-color,burn-color,burst-color,explode-color,glow-color,missile-color,nova-color,splatter-color

上記における「色」は次のいずれかである：酸、血、魅惑、死、炎、霜、聖、魔法、スライム、煙、水

カスタムエフェクトの場合、type はカスタムエフェクトの custfx オブジェクトの ID である必要があります。

spawnFxBetweenPoints(点1, 点2, タイプ, ページID)

spawnFxと同じように動作しますが、単一の点ではなく、 {x: 100, y: 100}形式で2つの点を渡します。例: spawnFxBetweenPoints({x: 100, y: 100}, {x: 400, y: 400}, "beam-acid");このエフェクトは、クライアント側で操作可能なもの（クライアント側での操作を許可するエフェクト）において、2点間を「移動」します。

以下のエフェクトタイプは、spawnFx の代わりに必ず spawnFxBetweenPoints を使用する必要があります：ビームカラー、ブレスカラー、スプラッターカラー

spawnFxWithDefinition(x, y, 定義JSON, ページID)

指定された位置 x,y で、効果定義の JSON を使用してアドホックなカスタム効果を生成します。ページIDを省略するか、または「undefined」を渡した場合、プレイヤーが現在いるページ（Campaignオブジェクト内の「playerpageid」）がデフォルトで使用されます。

definitionJSONは、定義用JSON仕様に準拠したJavaScriptオブジェクトです。カスタムFX。

音楽プレーヤーのプレイリスト

playJukeboxPlaylist(プレイリストID)

プレイ機能はプレイリストのフォルダID（キャンペーンオブジェクトの「_jukeboxfolder」プロパティから取得）を受け取り、ゲーム内の全員に対してそのプレイリストの再生を開始します。

stopJukeboxPlaylist()

停止機能は引数を必要とせず、現在再生中のプレイリストを停止します。

その他

sendPing(left, top, pageid, (オプション) playerid, (オプション) moveAll, (オプション) visibleTo)

卓上へ「ピング」を送信します（プレイヤーがマウスボタンを押し続けるのと同じ動作です）ピンを送信するページの左上座標とページIDを指定する必要があります。オプションで、pingを実行したプレイヤーのIDを指定できます。指定しない場合、「api」が仮定され、pingは黄色になります。

moveAllオプションに「true」を渡すと、プレイヤーの視点をその位置へ移動させることができます。

pingを視認できる、または移動させられるプレイヤーのプレイヤーIDをvisibleToで設定できます。これは単一のプレイヤーID、配列、またはカンマ区切り文字列として提示されます。

on("chat:message", function(msg) {
  // テスト実行にはチャットに「!pingtest」と入力してください
  if(msg.type == "api" && msg.content.indexOf("!pingtest") !== -1) {
 
    // 特定のプレイヤーを取得するには、findObjs({_type: "player"})[i].id を使用し、3番目のパラメータに null を指定しないでください。
    players = findObjs({_type: "player"});
    player1 = players[1].id;
    player2 = players[2].id;
 
    // すべてのプレイヤーの ID の配列を作成します。
    var allPlayerIDs = players.map(function(player) {
      return player['id'];
    });
 
    // このページの全員に、同じ場所への Ping を送信します。
    sendPing(300, 300, Campaign().get('playerpageid'), null, true);
    setTimeout(function() {
        // このページの全員に同じ位置へPingを送信
        sendPing(1500, 500, Campaign().get('playerpageid'), msg.playerid, true, "");
    }, 1000);
    setTimeout(function() {
        // 指定したプレイヤーのみをこの位置に通知
        sendPing(1200, 500, Campaign().get('playerpageid'), null, true, player1);
    }, 2000);
    setTimeout(function() {
        // プレイヤーIDの配列（プレイヤー1と2）をこの位置に送信
        sendPing(900, 100, Campaign().get('playerpageid'), player2, true, [player1, player2]);
    }, 3000);
    setTimeout(function() {
        // 文字列で渡されたカンマ区切りのリストをこの位置に送信
        sendPing(300, 300, Campaign().get('playerpageid'), player1, true, allPlayerIDs.join());
    }, 4000);
 
  }
})

Roll20における距離とグリッドに関する補足

Roll20では、「ユニット」は画面上で常に70ピクセルです。「ユニット」は、距離とグリッドが構築される基盤となる構成要素である。デフォルトでは：

1単位 = 5フィート
1単位 = 1グリッドマス
したがって、5フィート = 1単位 = 1平方

ただし、GMはグリッドのサイズと距離のスケールの両方を変更できる。 1ユニットは常に70ピクセルですが、GMは設定を変更して1ユニットを10フィート（つまり70ピクセル＝10フィート）にしたり、各グリッドスペースを2ユニット（つまり各グリッドスペースが140ピクセル）にしたりできます。