API: 関数ドキュメント

2025年11月07日 18:31

グローバル変数

変数	Descriptionq
`_`	これはアンダースコア・ジャイスの名前空間オブジェクトです Underscore.js ライブラリ用の名前空間オブジェクトです。
`都道府県`	状態オブジェクトのプロパティはゲームセッション間で保持されます。

_ (アンダースコア)

これはアンダースコア・ジャイスの名前空間オブジェクトです Underscore.js ライブラリ用の名前空間オブジェクトです。アンダースコアにはコレクション操作のための多くの関数が用意されています。

都道府県

状態オブジェクトのプロパティはゲームセッション間で保持されます。同じ状態オブジェクトはキャンペーン内のすべてのMod（API）スクリプト間で共有されるため、状態に値を書き込む際には名前衝突を避けるため、可能な限り使用量を最小限に抑えることを強く推奨します。 注：状態はJSONでシリアライズされるため、関数や循環参照を持つオブジェクトを保存することはできません。

グローバル関数

戻り値の型	関数	Descriptionq
Roll20オブジェクト	`キャンペーン`	シングルトンの Campaign Roll20 オブジェクトを取得します。
Roll20オブジェクト	`オブジェクト作成`	新しいRoll20オブジェクトを作成します。
配列のロール20オブジェクトの配列	`フィルターオブジェクト`	述語テストに合格するすべてのRoll20オブジェクトを取得します。
配列のロール20オブジェクトの配列	`オブジェクトを検索`	指定された能力値のセットに一致するプロパティを持つすべてのRoll20オブジェクトを取得します。
配列ロール20オブジェクトの配列	`getAllObjs`	キャンペーン内のすべてのRoll20オブジェクトを取得します。
異なる	`getAttrByName`	Roll20オブジェクトの能力値の現在の値または最大値を取得します。
Roll20オブジェクト	`getObj`	特定のRoll20オブジェクトを取得します。
	`u`	メッセージを Mod (API) コンソールに記録します。
	`オン`	イベントハンドラを登録します。
	`onSheetWorkerCompleted`	スタック全体の実行後に一度だけ実行されるイベントハンドラを登録しますシート開発者スクリプトが完了した後に実行されるワンタイムのイベントハンドラを登録します。
ブール値	`プレイヤーはGMです`	プレイヤーが現在GM権限を持っているかどうかを確認します。
	`プレイジュークボックスプレイリスト`	音楽プレーヤーのプレイリストを再生開始。
番号	`乱数`	乱数整数値を生成します。
	`sendChat`	チャットメッセージを送信します。
	`sendPing`	左マウスボタンを押し続けるのと同様のピングを送信します。
	`スポーンエフェクト`	パーティクルエミッターを生成します。
	`ポイント間でエフェクトを生成`	ある点から別の点へ移動するパーティクルエミッターを生成します。
	`定義付きエフェクト生成`	FX Roll20オブジェクトで表現されていないパーティクルエミッターを生成します。
	`stopJukeboxPlaylist`	現在再生中のすべての音楽プレーヤープレイリストを停止します。
	`戻る`	グラフィックのRoll20オブジェクトを、同じ卓上レイヤー上の他のすべてのグラフィックの下に移動します。
	`toFront`	グラフィックRoll20オブジェクトを、同じ卓上レイヤー上の他のすべてのグラフィックより上に移動します。

キャンペーン

パラメータ

パラメータなし

返品

シングルトンキャンペーンのRoll20オブジェクト。

例

var currentPageID = Campaign().get('playerpageid'),
    currentPage = getObj('ページ', currentPageID);

オブジェクト作成

パラメータ

TYPE(String) 作成するRoll20オブジェクトのタイプ。作成可能なのは「グラフィック」、「テキスト」、「パス」、「キャラクター」、「能力」、「属性」、「配布物」、「ロールアブルテーブル」、「テーブルアイテム」、「マクロ」のみです。ATTRIBUTES(Object)Roll20オブジェクトのプロパティに使用する初期値。

返品

作成されたRoll20オブジェクト。

例

親オブジェクトを持つRoll20オブジェクトを作成する場合（例：キャラクターRoll20オブジェクトの子となる属性Roll20オブジェクトを作成する場合）、能力値内で親オブジェクトのIDを指定する必要があります。

on('add:character', function(obj) {
    createObj('attribute', {
        name: 'Strength',
        current: 0,
        max: 30,
        characterid: obj.id
    });
});

パスRoll20オブジェクトを作成する際には、読み取り専用プロパティ_pathの値を必ず指定する必要があります。これは、Roll20オブジェクト作成時に読み取り専用プロパティの値を設定できないという規則に対する例外です。

createObj('path', {
    left: 7000,
    top: 140,
    width: 140,
    height: 140,
    layer: 'objects',
    path: JSON.stringify([['M', 0, 0], ['L', 70, 0], ['L', 0, 70], ['L', 0, 0]])
});

ハンドアウトのRoll20オブジェクトを作成する際、作成時にテキストやGMノートを設定することはできません。

var handout = createObj('handout', {
    name: 'A Letter Addressed to You',
    inplayerjournals: 'all',
    archived: false
});
handout.set({
    notes: 'Notes can only be set after the handout is created',
    gmnotes: 'GM Notes can only be set after the handout is created'
});

フィルターオブジェクト

パラメータ

CALLBACK(関数)すべてのRoll20オブジェクトに対してテストを行う述語関数。コールバック関数はパラメータとしてRoll20オブジェクトを受け取り、filterObjsの戻り値に含まれるRoll20オブジェクトに対してはtrueを、それ以外のすべてのRoll20オブジェクトに対してはfalseを返す必要があります。

返品

述語テストを通過したRoll20オブジェクトの配列。

例

var tokenName = getMyTokenName(),
    duplicateTokens = filterObjs(function(obj) {
        if (obj.get('type') !== 'graphic' || obj.get('subtype') !== 'token' || obj.get('name') === tokenName) return false;
        return obj.get('name').indexOf(tokenName) === 0 && /\d+$/.text(obj.get('name'));
});

オブジェクトを検索

パラメータ

ATTRIBUTES(オブジェクト) キャンペーン内のRoll20オブジェクトと照合するキー:値ペアの集合。OPTIONS(オブジェクト、オプション) options.caseInsensitiveがtrueの場合、Roll20オブジェクトと属性の文字列比較は大文字小文字を区別しません。

返品

能力値と一致するプロパティを持つRoll20オブジェクトの配列。

例

var npcs = findObjs({ type: 'character', controlledby: '' });

getAllObjs

パラメータ

パラメータなし

返品

キャンペーン内のすべてのRoll20オブジェクトの配列。

例

var everything = getAllObjs();

getAttrByName

パラメータ

CHARACTER_ID(文字列) 値を取得したい属性ロール20オブジェクトの親となる、キャラクターロール20オブジェクトのID。ATTRIBUTE_NAME(String) 値を取得したい属性ロール20オブジェクトの名前。VALUE_TYPE(String, optional) "current" または "max"（省略時はデフォルトで "current"）。

返品

該当する属性の電流または最大値プロパティ。指定されたプロパティが設定されていない場合、キャラクターシートで指定されたデフォルト値（デフォルト値が存在する場合）が代わりに使用されます。

例

var character = getMyCharacter(),
    strength = getAttrByName(character.id, 'strength'),
    strength_max = getAttrByName(character.id, 'strength', 'max');

getObj

パラメータ

TYPE(String) 取得するRoll20オブジェクトのタイプ。ID(String) 取得するRoll20オブジェクトの一意のID。

返品

指定されたRoll20オブジェクト。

例

on('chat:message', function(msg) {
    var sendingPlayer = getObj('player', msg.playerid);
});

ログ

パラメータ

MESSAGE(可変) Mod (API) コンソールに投稿するメッセージ。メッセージパラメータは、JSON.stringify を使用して文字列に変換されます。

返品

(無効)

例

on('chat:message', function(msg) {
    log('メッセージ受信元:');
    log(getObj('player', msg.playerid));
});

"メッセージ送信元:"
{"_d20userid":"123456","_displayname":"John Doe","speakingas":"","_online":true,"color":"#885b68","_macrobar":"-J16Z-dRU5tleKiKOg0X|-K3F_4q_b1p-Vdiwgn1t","showmacrobar":true,"_id":"-J16Z-dRU5tleKiKOc0X","_type":"player","_lastpage":""}

オン

パラメータ

イベント(文字列)イベントには5種類あります：readychangeadddestroychatreadyを除くすべてのイベントタイプは、オブジェクトタイプとペアで指定する必要があります。チャットでは、これは常にメッセージです。その他すべてのものについては、これはRoll20オブジェクトのタイププロパティです。オブジェクトタイプに加えて、changeevents はオプションで監視対象の Roll20 オブジェクトのプロパティを指定することもできます。イベントの 2～3 つの部分（タイプ、オブジェクト、およびオプションのプロパティ）はコロンで区切られます。したがって、有効なイベント文字列には「ready」、「chat:message」、「change:graphic」、「change:campaign:playerpageid」、「add:character」、「destroy:handout」などが含まれますが、これらに限定されません。CALLBACK(Function)指定されたイベントが発生した際に呼び出される関数。渡されるパラメータはイベントタイプによって異なります：readyイベントにはコールバックパラメータがありません。changeイベントには、変更後のRoll20オブジェクトを参照するobjパラメータと、変更前のRoll20オブジェクトのプロパティと一致するプロパティを持つプレーンなJavaScriptオブジェクトであるprevパラメータがあります。addイベントにはobjパラメータがあり、これは新しいRoll20オブジェクトへの参照です。destroyイベントにはobjパラメータがあり、これは存在しなくなったRoll20オブジェクトへの参照です。chatイベントにはmsgパラメータがあり、チャットに送信されたメッセージの詳細が含まれます。

返品

(無効)

例

イベントは登録された順序で発生し、最も特異なイベントから最も特異でないイベントへと処理されます。この例では、グラフィックRoll20オブジェクトのleftプロパティを変更すると、function3が呼び出され、続いてfunction1、そしてfunction2が呼び出されます。

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

イベントの追加は、新しいセッションが開始された際に、既にキャンペーン内にあるRoll20オブジェクトに対して発火を試みます。この動作を防ぐには、readyイベントが発生するまでaddイベントの登録を待機できます。

on('add:graphic', function(obj) {
    // セッション開始時、キャンペーン内の全グラフィックに対してこの関数が呼び出される
    // 新しいグラフィック Roll20 オブジェクトが作成されるたびにこの関数も呼び出される
});

on('ready', function() {
    on('add:graphic', function(obj) {
        // この関数は、既存のグラフィックではなく、新しいグラフィックRoll20オブジェクトが作成された場合にのみ呼び出されます
    });
});

変更イベントのプレパラメータは、Roll20オブジェクトではなく、単純なJavaScriptオブジェクトです。したがって、getまたはset関数を使用することはできず、読み取り専用プロパティの先頭アンダースコアを省略することもできません。

on('change:graphic', function(obj, prev) {
    var id1 = obj.id,         // 3つとも同等
        id2 = obj.get('id'),
        id3 = obj.get('_id'),

        id4 = prev.id,        // undefined
        id5 = prev.get('id'), // undefined is not a function
        id6 = prev._id;       // 正しい

    // どちらも同等
    obj.set('left', 70);
    obj.set({
        left: 70
    });

    prev.set('left', 70); // undefined is not a function
    prev.set({            // undefined is not a function
        left: 70
    });
    prev.left = 70;       // 正しいが、卓上では何も変更されない
});

Roll20オブジェクト（ノート、GMノート、バイオ）の非同期フィールド（キャラクターおよびハンドアウト）において、prevパラメータには必要なデータが保持されません。（代わりにシステムで使用される数値識別子が付与されます。）これらのフィールドのいずれかの以前の値にアクセスする必要がある場合は、自身でその値を追跡する必要があります：

on('ready', function() {
    if (!state.example) state.example = { bioCache: {} };
});

on('change:character:bio', function(obj, prev) {
    obj.get('bio', function(text) {
        state.example.bioCache[obj.id] = text;

        // do stuff...

        if (shouldRevertBio()) {
            obj.set('bio', state.example.bioCache[obj.id]);
        }
    );
);

onSheetWorkerCompleted

パラメータ

CALLBACK(関数) 現在のシート開発者スクリプトの「スタック」が完了したときに呼び出される関数。

返品

(無効)

例

この関数は setWithWorker の前に呼び出すことを意図しています。 コールバック関数は一度だけ呼び出されます。

var myCharacter = ...,
    mySourceAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'mySourceAttribute' })[0];

onSheetWorkerCompleted(function() {
    var calculatedAttr = findObjs({ type: 'attribute', characterid: myCharacter.id, name: 'myCalculatedAttribute' })[0];
    // calculatedAttr.get('current') を使って何か処理を行う
});
mySourceAttr.setWithWorker({ current: 5 });

プレイヤーはGMです

パラメータ

PLAYER_ID(String) 確認対象のプレイヤーのRoll20オブジェクトのID。

返品

プレイヤーが現在GM権限を持っている場合はtrue、そうでない場合はfalse。

例

この機能は特に、Mod（API）コマンドをGM専用に制限するのに有用です。

on('chat:message', function(msg) {
    if (msg.type !== 'api') return;

    if (msg.content.indexOf('!playercommand') === 0) {
        // ...
    } else if (msg.content.indexOf('!gmcommand') === 0) {
        if (!playerIsGM(msg.playerid)) return;
        // ...
    
});

プレイジュークボックスプレイリスト

パラメータ

PLAYLIST_ID(String) 再生を開始するプレイリストのID。

返品

(無効)

例

var playlists = JSON.parse(Campaign().get('jukeboxfolder')),
    myPlaylist = _.find(playlists, (folder) => _.isObject(folder) && folder.n === myPlaylistName);
playJukeboxPlaylist(myPlaylist.id);

ランダムな整数

パラメータ

MAX(数値) 返す最大数値（端数を含む）。

返品

1（含む）からmax（含む）までの間のランダムな整数。この関数はMath.random() よりも優れた分布を持ち、それよりも推奨されます。この関数は Quantum Roll 機能を使用しませんが、ダイスエンジンがThe Quantum Rollが利用できない場合にフォールバックする擬似乱数アルゴリズムは同じものを使用します。

例

この関数は1から最大値までの整数を返すため、Roll20のダイスエンジンをフル活用する必要がない場合に、素早くダイスロールの結果を生成するのに最適です。ダイスエンジンの全機能が必要ない場合に、素早くダイスロールの結果を生成するのに最適ですの全機能が必要ない場合に、素早くダイスロールの結果を生成するのに最適です。

var d20Result = randomInteger(20); // おおよそ20面ダイスを振ることに相当する

sendChat 非同期

パラメータ

SPEAKINGAS(String) 送信されるメッセージに添付する名前。 speakAsがplayer|player_idまたはcharacter|character_idの形式の場合、そのプレイヤーまたはキャラクターとしてメッセージが送信されます。そうでない場合、メッセージはGMが/asコマンドを使用したかのように指定された名前を使用します。MESSAGE(String)チャットに送信するメッセージ。CALLBACK(Function, optional)コールバックが指定されている場合、チャットメッセージの結果はチャットに表示される代わりに、この関数に渡されます。コールバックメソッドのパラメータはメッセージオブジェクトの配列です。OPTIONS(Object, optional)options.noarchive が true の場合、メッセージはチャットアーカイブに追加されません。 options.use3d が true の場合、メッセージ内のダイスロールは3Dダイス機能を使用します。コールバックが指定されている場合、オプションは適用されません。

返品

(無効)

例

sendChat('例', 'これは簡単な例です。');

チャット:メッセージイベントをトリガーしたプレイヤーまたはキャラクターとして、メッセージを送信するコードを簡単に記述できます。

on('チャット:メッセージ', function(msg) {
    var キャラクター = findObjs({ type: 'character', name: msg.who }) [0],
        player = getObj('player', msg.playerid),
        message = ' said something';

    if (character) sendChat('character|'+character.id, character.get('name')+message);
    else sendChat('player|'+player.id, player.get('displayname')+message);
});

コールバックパラメータは、Roll20のダイスエンジンを活用する必要がある場合に有用です。ダイスエンジンを活用する必要がある場合に便利です。 コールバックを使用する際、メッセージがチャットに表示されないため、特にspeakingAs値は必要ありません。

sendChat('', '/r 2d20k1+'+strengthMod, function(ops) {
    var msg = ops[0];
    // ...
});

options.noarchiveは主に、 APIコマンドボタンをプレイヤーに送信する際、チャット履歴を詰まらせないようにするためのものです。

sendChat('System', '[変更をクリア](!clear)\n[タイルを追加](!add)\n[サンプルを表示](!view)\n[レイアウトを保存](!save)', null, { noarchive: true });

sendPing

パラメータ

LEFT(数値) ピンを配置するx座標。TOP(数値) ピンを配置するy座標。PAGE_ID(文字列) ピンを配置するRoll20ページのID。PLAYER_ID(文字列, オプション) ピンは指定されたプレイヤーの色を使用します。 player_id を省略した場合、ping は黄色になります。MOVEALL(Boolean, optional)moveAll が true の場合、該当ページ上の全プレイヤーの視点を ping を中心に移動します。

注：現時点では、moveAllがtrueの場合、GMのみがビューを中央に配置します。この動作はこちらに記載されています

返品

(無効)

例

on('chat:message', function(msg) {
    var obj;
    if (msg.type === 'api' && msg.content.indexOf('!ping') === 0) {
        if (!msg.selected) return;
        obj = getObj(msg.selected[0]._type, msg.selected[0]._id);
        sendPing(obj.get('left'), obj.get('top'), obj.get('pageid'), msg.playerid, true); // 選択されたトークンを中心に全員を配置
    }
);

スポーンエフェクト

パラメータ

LEFT(数値) パーティクルエミッターを配置するx座標。TOP(数値) パーティクルエミッターを配置するy座標。TYPE(文字列) 配置するパーティクルエミッターの種類。組み込みエフェクトの場合、これは「タイプ-カラー」であるべきです。ここでタイプは爆弾、泡立ち、燃焼、爆発、輝き、ミサイル、新星のいずれかであり、カラーは酸、血、魅惑、死、炎、霜、聖、魔法、スライム、煙、 waterのいずれかです。カスタムエフェクトの場合、これはFX Roll20オブジェクトのIDである必要があります。注：ビーム、ブレス、スプラッタータイプはspawnFxでは使用できません。代わりにspawnFxBetweenPointsを参照してください。PAGE_ID(String, optional)パーティクルエミッターを配置するRoll20オブジェクトのページID。省略された場合、代わりに Campaign().get('playerpageid') が使用されます。

返品

(無効)

例

spawnFx(1400, 1400, '泡立つ酸');

ポイント間でエフェクトを生成

パラメータ

START(オブジェクト) パーティクルエミッターの開始点。ポイントは { x: number, y: number } の形式である必要があります。END(Object)パーティクルエミッターの終了点。ポイントは { x: number, y: number } の形式である必要があります。TYPE(String)配置するパーティクルエミッターのタイプ。内蔵エフェクトの場合、これは「タイプ-カラー」であるべきであり、タイプはビーム、爆弾、ブレス、泡立ち、燃焼、爆発、輝き、ミサイル、ノヴァ、 splatter のいずれかです。color は acid、blood、charm、death、fire、frost、holy、magic、slime、smoke、water のいずれかです。カスタムエフェクトの場合、これはFX Roll20オブジェクトのIDである必要があります。PAGE_ID(String, optional)パーティクルエミッターを配置するページRoll20オブジェクトのID。省略された場合、代わりに Campaign().get('playerpageid') が使用されます。

返品

(無効)

例

spawnFxBetweenPoints({ x: 1400, y: 1400 }, { x: 2100, y: 2100 }, 'beam-acid');

定義付きエフェクト生成

パラメータ

LEFT(数値) パーティクルエミッターを配置するx座標。TOP(数値) パーティクルエミッターを配置するy座標。DEFINITION(オブジェクト) 配置するパーティクルエミッターの特性。カスタムエフェクトを参照すると、利用可能なプロパティの一覧と、デフォルトのパーティクルエミッタータイプおよびカラーのプロパティを確認できます。 FXライブラリで、Roll20ユーザーが考案したカスタムエフェクトをいくつかご覧ください。PAGE_ID(String, optional)パーティクルエミッターを配置するRoll20オブジェクトのページID。省略された場合、代わりに Campaign().get('playerpageid') が使用されます。

返品

(無効)

例

// これら2つは同等です
spawnFx(1400, 1400, 'bubbling-acid');
spawnFxWithDefinition(1400, 1400, {
    maxParticles: 200,
    size: 15,
    sizeRandom: 3,
    lifeSpan: 20,
    lifeSpanRandom: 5,
    speed: 7,
    speedRandom: 2,
    gravity: { x: 0.01, y: 0.65 },
    angle: 270,
    angleRandom: 35,
    emissionRate: 1,
    startColour:       [0, 35, 10, 1],
    startColourRandom: [0, 10, 10, 0.25],
    endColour:         [0, 75, 30, 0],
    endColourRandom:   [0, 20, 20, 0]
});

stopJukeboxPlaylist

パラメータ

パラメータなし

返品

(無効)

例

stopJukeboxPlaylist();

戻る

パラメータ

OBJ(Roll20オブジェクト) そのレイヤーの奥に送るRoll20オブジェクト。

返品

(無効)

例

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!toback' && msg.selected) {
        _.each(msg.selected, (s) => {
            toBack(getObj(s._type, s._id));
        });
    }
});

toFront

パラメータ

OBJ(Roll20オブジェクト) そのレイヤーの最前面に表示するRoll20オブジェクト。

返品

(無効)

例

on('ready', function() {
    on('add:graphic', function(obj) {
        toFront(obj);
    });
});