API：オブジェクト

注：オブジェクトのidプロパティは、グローバルにユニークな ID です。異なるタイプのオブジェクトであっても、2 つのオブジェクトが同じ ID を持つことはありません。 さらに、オブジェクトのidは頻繁にアクセスされ、決して変更されないため、必要に応じてobj .get("_id")の代わりにobj.idを使用してアクセスできるショートカットが用意されています（どちらでも動作します）。

パス

パス・データのフォーマットの詳細については、パスのセクションを参照のこと。

窓

注： WindowとDoorは、他のタイプのオブジェクトと比較して、逆軸を使用します。 例えば、他のオブジェクトでは100となるトップ変数が、窓やドアではy -100となる。

例

on('chat:message', function(msg) {
    if (msg.type === 'api' && msg.content === '!cw') {
        const currentPageID = Campaign().get('playerpageid');
        const win = createObj('window', {
            x: 70,
            y. -70：-70,
            pageid: currentPageID,
            path：{
		        handle0: {
        			x: -70,
        			y: 0,
        		},
        		handle1： {
        			x: 35,
        			y: 0,
        		}
        	},
            color: '#000000'
        });
    }

    if (msg.type === 'api' && msg.content === '!mw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.set({
           x: 240,
           y: -139
        });
    }

    if (msg.type === 'api' && msg.content === '!dw') {
        const win = getObj('window', '-NG38yUgghBBoV8YR0y1');
        win.remove();
    }.
});

ドア

注： WindowとDoorは、他のタイプのオブジェクトと比較して逆軸を使用します。 例えば、他のオブジェクトでは100となるトップ変数が、窓やドアではy -100となる。

テキスト

グラフィック（トークン／地図／カード／その他）

トークン・マーカーの例

{
          "id":59, //
          "name": "Bane", // マーカーの名前（一意ではない）
          "tag": "Bane::59", // トークンが実際にどのように参照されるか
          // これにはカスタムマーカーの id が含まれるが、デフォルトマーカーの id は含まれない
          // 。
          "url": "https://s3.amazonaws.com/files.d20.io/images/59/yFnKXmhLTtbMtaq-Did1Yg/icon.png?1575153187"

          // トークン・マーカーの画像のURL
}.

リンクされたキャラクター＋トークンに関する重要な注意事項

キャラクターにリンクされたトークンの場合、トークンのcontrolledbyフィールドはキャラクターのcontrolledbyフィールドによってオーバーライドされることに注意してください。

トークンがアトリビュートにリンクされている（例えば、bar1_ linkが設定されている）トークンバー（例えば、bar1_valueや bar1_max）については、バーに値を設定すると、基礎となるアトリビュートの現在値や最大値も自動的に更新されるので、手動で両方を設定する必要はありません。

さらに、ゲーム内でアトリビュート（またはトークンバー）が変更されると、change:attribute（およびプロパティ固有、たとえばchange:attribute:current）イベントと、それに続くchange:graphic（およびchange:graphic:bar1_value）イベントが聞こえます。 どちらのイベントにも応答することができますが、属性イベントが先に発生するため、属性イベントが発生しても、基礎となるバーの値はまだ更新されません。

ステータス・マーカーに関する重要な注意事項

2013年8月6日より、トークンのステータス・マーカーの取り扱い方法が変更されました。 Graphicオブジェクトの "statusmarkers "プロパティが、トークン上で有効なすべてのステータス・マーカーの色/アイコンのカンマ区切りリストになりました。 形式は以下の通り：

//カンマ区切り（joinで作成、splitで配列化）。 
// ステータスアイコン/カラーに"@"シンボルが続く場合、
//"@"の後の数字がアイコンのバッジとして表示される
statusmarkers = "red,blue,skull,dead,brown@2,green@6"

既存のスクリプトとの後方互換性を維持し、文字列の分割と解析を自分で処理するコードを書く必要なくステータス・マーカーを扱う簡単な方法を提供するために、statusmarkersプロパティに直接アクセスすることができますが、ステータス・マーカーを扱うために設定/取得できるオブジェクトの「仮想」プロパティのセットを提供します。 各ステータス・マーカーは、"status_<markername>" プロパティを持つ。 例えば、こうだ：

obj.get("status_red"); //Will return false if the marker is not active, true if it is, and a string (e.g. "2" or "5") if there is currently a badge set on the marker
obj.get('status_bluemarker'); //Is still supported for backwards compatability, and is equivalent to doing obj.get("status_blue");
obj.set("status_red", false); //マーカーを削除する
obj.set("status_skull", "2"); //ドクロのアイコンに "2 "のバッジをセットし、まだアクティブでなければトークンに追加する。

これらの仮想プロパティはイベントを持たないので、トークンのステータス・マーカーの変更をリッスンするにはchange: graphic :statusmarkersを使わなければならない。

使用可能なステータスマーカーの全リスト（マーカートレイに表示される順番と同じ）：

「赤」、「青」、「緑」、「茶」、「紫」、「ピンク」、「黄」、「死」、「髑髏」、「眠」、「半心」、「半霞」、「阻止」、「カタツムリ」、「稲妻」、「スパナ」、「chained-heart"、"chemical-bolt"、"death-zone"、"drink-me"、"edge-crack"、"ninja-mask"、"stopwatch"、"fishing-net"、"overdrive"、"strong"、"fist"、"padlock"、"three-leaves"、"ふわふわの翼"、"叩かれた"、"踏ん張った"、"矢を受けた"、"オーラ"、"背中の痛み"、"黒い旗"、"出血した目"、"ボルトシールド"、"壊れた心"、"クモの巣"、"壊れた盾"、"飛ぶ旗""放射能", "トロフィー", "ブロークンスカル", "フローズンオーブ", "ローリングボム", "ホワイトタワー", "グラブ", "スクリーム", "グレネード", "セントリーガン", "オールフォーワン", "エンジェルアウトフィット", "アーチェリーターゲット"

ページ

キャンペーン

 ターンオーダー

ターンオーダーは、現在のターンオーダーリストを表すJSON文字列である。 これはオブジェクトの配列である。 現在のところ、ターン・オーダーは一度に1つのページのオブジェクトしか含むことができません -- 現在のターン・オーダーのページIDは "initiativepage "属性です。 両者を同期させておかないと、おかしな結果になってしまうかもしれない。

ターン・オーダーを操作するには、JSON.parse()を使って、現在のターン・オーダーの状態を表すオブジェクトを取得します（注意：最初に空文字列「"」でないことを確認してください。） 以下はターンオーダーオブジェクトの例である：

[
    {
     "id": "36CA8D77-CF43-48D1-8682-FA2F5DFD495F", //GraphicオブジェクトのID。 これが設定されている場合、ターンオーダーリストは卓上のグラフィックに基づいてリストの名前とアイコンを自動的に引き出します。
     "pr": "0", //リスト内の項目の現在値。 数字でもテキストでもよい。
     "カスタム":"//アイテムのカスタムタイトル。 IDが"-1 "以外の値に設定されている場合は無視される。
    },
    {
     "id":"-1", //カスタムアイテムの場合、IDは"-1 "に設定しなければならない（MUST）。
     "pr": "12",
     "custom": "Test Custom" //カスタム項目に表示される名前。
    }
]

ターン順を変更するには、現在のターン順オブジェクトを編集し、JSON.stringify()を使用してキャンペーンの属性を変更します。 リストの順番は配列の順番と同じなので、例えばpush()はリストの最後に項目を追加し、unshift()は先頭に追加する、といった具合である。

var turnorder;
if(Campaign().get("turnorder") == "") turnorder = []; //注：最初に、turnorderが単なる空文字列でないことを確認する。 もしそうなら、空の配列のように扱う。
else turnorder = JSON.parse(Campaign().get("turnorder"));

//ターン・オーダーの最後に新しいカスタム・エントリーを追加する。
turnorder.push({
    id: "-1",
    pr: "15",
    custom: "Turn Counter"
});
Campaign().set("turnorder", JSON.stringify(turnorder))；

選手

マクロ

ロール式テーブル

表項目 

キャラクター

属性

 重要: キャラクターシートのデフォルト値がアトリビュートの使用にどのように影響するかについては、キャラクターシートの操作に関する以下のノートを参照してください。

能力

配布資料

注： APIはフォルダ階層にアクセスできない。 APIで作成されたプリントはルートレベルに置かれます。

デッキ

デッキからカードを「引く」、「配る」、「シャッフルする」ヘルパーAPIメソッドがあることに注意。 2018年3月のAPI Updateフォーラムの投稿を参照。

カード

手

各プレイヤーは1つのハンドしか持ってはならないことに注意。

ジュークボックス・トラック

カスタムFX

imgsrcとアバターのプロパティの制限

imgsrcと アバターのプロパティを編集できるようになりましたが、Roll20のすべてのユーザーに安全性を提供するために、これらのプロパティに以下の制限を設けました：

• Roll20 ライブラリにアップロードされた画像ファイルを使用する必要があります。外部サイト (Imgur など) や Roll20 マーケットプレイスでは使用できません。 メインサーバーにアップロードされた画像の場合は'https://s3.amazonaws.com/files.d20.io/images/'、Devサーバーにアップロードされた画像の場合は'https://s3.amazonaws.com/files.staging.d20.io/images/'で始まります。 画像のソースURLは、ブラウザの開発者ツールを使って見ることができます。

• URLにクエリー文字列を含める必要がある -- 例えば'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png'だけでなく、'https://s3.amazonaws.com/files.staging.d20.io/images/123456/med.png?12345678'のように。

• グラフィックオブジェクト（トークン）の場合は、画像の「サム」サイズを使用する必要があります。 https://s3.amazonaws.com/files.staging.d20.io/images/123456/thumb.png?12345678'のように見えるはずだ。

将来的には、MOD（API）スクリプト専用に画像をアップロードできるツールを追加するかもしれませんが、今のところは、自分のライブラリにアップロードした画像を使ってください。 ライブラリから画像を削除すると、MOD（API）スクリプトを使ったゲームも含め、その画像を使ったすべてのゲームから削除されることに注意してください。

Notes、GMNotes、Bioフィールドの使用 非同期

CharactersおよびHandoutsの "notes"、"gmnotes"、または "bio "フィールドにアクセスするには、get()関数の第2引数にコールバック関数を渡す必要があります。 例を挙げよう：

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
character.get("bio", function(bio) {
    log(bio); //ここでキャラクターのbioに何かをする。
});

これらのフィールドの値は通常通り設定できる。 現在（2016/05/09時点）、これらの非同期フィールドにはバグがあり、createObjに値を渡して設定すると、オブジェクトを奇妙な状態にしたまま静かに失敗することに注意してください。 この問題が解決するまでは、.setを使用してこれらの値を設定する必要があります。 詳細 フォーラム. また、同じset()呼び出しでnotesとgmnotesの両方のプロパティを設定しようとすると、呼び出しの2番目のプロパティが誤って設定されるというバグもある（2016/11/05現在）。 詳細 フォーラム.

キャラクターシートを使う

Character Sheets機能は、Attributesオブジェクト・タイプの使い方に影響します。なぜなら、シートには、シート上の各属性のデフォルト値を指定する機能があるからです。 しかし、アトリビュートがデフォルト値に設定されている場合、そのキャラクタの実際のアトリビュートオブジェクトはまだゲーム内に作成されていません。 私たちは、この複雑さを隠してくれる便利な機能を提供しています。 特に、あるゲームがキャラクター・シートを使用していることが分かっている場合は、この関数を使用して属性の値を取得する必要があります。

getAttrByName(character_id, attribute_name, value_type)

キャラクターのID、属性の名前（IDではない）（例えば "HP "や "Str "など）、そしてvalue_typeに "current "か "max "を指定するだけだ。 例を挙げよう：

var character = getObj("character", "-JMGkBaMgMWiQdNDwjjS");
getAttrByName(character.id, "str"); //strの現在の値、例えば "12"
getAttrByName(character.id, "str", "max"); //strの最大値、例えば"[[floor(@{STR}/2-5)]]"

自動計算された値を持つフィールドは、値の結果ではなく数式を返すことに注意してください。 その計算式を sendChat() に渡すと、ダイスエンジンを使って自動的に結果を計算してくれます。

また、必ず キャラクターシートのドキュメントも参照してください。

getAttrByNameは属性の値のみを取得し、属性オブジェクト自体は取得しません。 current "または "max "以外の属性のプロパティを参照したい場合、または属性のプロパティを変更したい場合は、findObjsなど、上記の他の関数のいずれかを使用する必要があります。

要求された属性が存在しない場合、getAttrByName()はundefined を返します。

オブジェクトの作成

createObj(タイプ, 属性)

注：現在、'graphic'、'text'、'path'、'character'、'ability'、'attribute'、'handout'、'rollabletable'、'tableitem'、'macro'オブジェクトを作成することができます。

ゲーム内で新しいオブジェクトを作成するには、createObj関数を使用します。 オブジェクトのタイプ（上記のオブジェクト・リストにある有効な_typeプロパティの1つ）と、オブジェクトのプロパティのリストを含むattributesオブジェクトを渡す必要があります。 オブジェクトに親オブジェクトがある場合（例えば、アトリビュートやアビリティはキャラクタに属し、グラフィックやテキスト、パスはページなどに属します）、プロパティのリストに親のIDを渡さなければならないことに注意してください（例えば、アトリビュートを作成するときはcharacteridプロパティを含めなければなりません）。 また、新しいオブジェクトを作成する場合でも、読み取り専用のプロパティを設定することはできません。 この例外は、パスを作成するときに、'path'プロパティを含める必要がありますが、パスが最初に作成された後は変更できません。

createObjは新しいオブジェクトを返すので、そのオブジェクトを使って作業を続けることができる。

//ゲームに追加されたキャラクターに新しいStrength属性を作成する。
on("add:character", function(obj) {
    createObj("attribute", {
        name: "Strength",
        current: 0,
        max：30,
        characterid: obj.id
    });
})；

オブジェクトの削除

オブジェクトを削除します。

注：現在、'graphic'、'text'、'path'、'character'、'ability'、'attribute'、'handout'、'rollabletable'、'tableitem'、'macro'オブジェクトを削除することができます。

既存のゲームオブジェクトを削除するには、.remove()関数を使用します。 .remove()関数は、createObj関数で作成できるすべてのオブジェクトに対して機能します。 オブジェクトに対して直接関数を呼び出す。 例えば、mycharacter.remove();。

グローバル・オブジェクト

スクリプトのどこでもグローバルに利用できるオブジェクトがいくつかあります。

キャンペーン() (機能)

キャンペーン・オブジェクトを返す関数。 キャンペーンは1つしかないため、このグローバルは常にゲーム内の唯一のキャンペーンを指す。 Campaign().get("playerpageid")を使用して、オブジェクトがアクティブ・ページにあるかどうかをチェックする場合などに便利です。

状態

ステート変数は、ゲーム内で実行されているすべてのスクリプトからアクセス可能なグローバルスコープのオブジェクトです。 stateというグローバル変数を使うだけで、どの関数やコールバックからもいつでもステート・オブジェクトにアクセスできる。 さらに、状態オブジェクトは サンドボックスの実行の間に永続化されるので、スクリプトの将来の実行に必要な情報を保存するために使うことができます。

注意:stateオブジェクトは、プレイヤーのコンピュータに送信されることはなく、ゲームファイルを大きくすることもないため、APIでのみ必要とされる情報を格納するために使用する必要があります。 ゲーム内で必要な値をRoll20オブジェクトのプロパティに保存します。

保存可能なタイプ

ステート・オブジェクトが永続化できるのは、単純なデータ型だけである。 JSON標準によってサポートされています。

警告初期状態でステートに保存された関数は動作しているように見えますが、サンドボックスの再起動など、ステートが永続化から復元された最初の時点で消えてしまいます。

• 注意:これには、イベントやfindObjs(),getObj(),filterObjs(),createObj() などの関数から取得した Roll20 オブジェクトも含まれます。

重要な注意事項

ステートオブジェクトは、サンドボックス内のすべてのスクリプトで共有される。 他のスクリプトを壊さないためには、いくつかの簡単なガイドラインに従うことが重要である：

• 決してルート・ステート・オブジェクトに直接割り当てないこと。

state = { break: 'all the things' }; // 絶対にやってはいけない！

• 避けるスクリプトの中でstateという名前のローカル変数を使うのは避けましょう。 これでも動作はしますが、後でスクリプトを使用するユーザーを混乱させ、コードが不注意に編集された場合に問題を引き起こす可能性があります。

function turn(){
    var state = Campaign().get('turnorder'); // 悪い習慣なので避けましょう！
    // ...
}

• 常にプロパティを少なくとも1つの名前空間プロパティの下に配置します。 十分に説明的な名前空間プロパティを使用するようにしてください。 スクリプトや セッティングのような名前は避ける。 モジュール名か自分の名前かハンドルネームを使うのがベストだ。

if( ！ state.MyModuleNamespace ) {
    state.MyModuleNamespace = { module：'私のモジュール', ok：'これでいい！', count：0 };
}
state.MyModuleNamespace.count++；

使用例

これは、ステート・オブジェクトを適切に使用する実例である。

on('ready',function() {
    "use strict";

    // 名前空間プロパティが存在するかどうかをチェックし、存在しない場合は作成する
    if( ！ state.MyModuleNS ) {
        state.MyModuleNS = {
            version: 1.0,
            config： {
                color1: '#ff0000',
                color2: '#0000ff'
            }
            count：0
        };
    }.

    // stateプロパティを使用して、チャットへのメッセージを設定する。 
    sendChat(
        'Test Module',
        '<span style="color: '+state.MyModuleNS.config.color1+';">'+
            'State test'+
        '</span> '+
        '<span style="color: '+state.MyModuleNS.config.color2+';">'+
            'Script v'+state.MyModuleNS.version+' started '+(++state.MyModuleNS.count)+' times!'+
        '</span>'
    );
})；

オブジェクトの検索/フィルタリング

APIは、オブジェクトの検索に使用できるいくつかのヘルパー関数を提供している。

getObj(type, id)
オブジェクトの_typeと_idを渡すと、この関数は1つのオブジェクトを取得する。 オブジェクトのコレクション全体を反復処理する必要がないのはこの関数だけなので、可能な限り他のfind関数よりもこの関数を使うのがベストだ。

on("change:graphic:represents", function(obj) {
    if(obj.get("represents") != "") {
       var character = getObj("character", obj.get("represents"));
    }.
});

findObjs(attrs)

この関数に属性のリストを渡すと、一致するすべてのオブジェクトを配列として返します。 これは、全ページの全タイプのオブジェクトに対して動作することに注意してください -- したがって、卓上オブジェクトを扱う場合は、少なくとも_typeと_pageidのフィルタを含めたいでしょう。

var currentPageGraphics = findObjs({                              
  _pageid：Campaign().get("playerpageid"),                              
  _type："graphic",                          
});
_.each(currentPageGraphics, function(obj) {    
  //現在のページにあり、グラフィックであるobjで何かを行う。
});

また、オプションの第2引数として、以下のようなオプションのリストを含むオブジェクトを渡すこともできる：

• caseInsensitive(true/false)：trueの場合、文字列プロパティは文字列の大文字と小文字を区別せずに比較されます。

var targetTokens = findObjs({
    name: "target"
}, {caseInsensitive: true});
//'target'、'Target'、'TARGET'などの名前を持つすべてのトークンを返す。

filterObjs(コールバック)

指定したコールバック関数を各オブジェクトに対して実行し、もしコールバック関数が true を返したら、そのオブジェクトを結果の配列に含めます。 findObjs()には実行速度を向上させるためのインデックスが組み込まれているため、ほとんどの場合、findObjs()を使用して目的の型のオブジェクトを最初に取得し、配列のネイティブ.filter()メソッドを使用してそれらをフィルタリングする方が良いでしょう。

var results = filterObjs(function(obj) {    
  if(obj.get("left") < 200 && obj.get("top") < 200) return true;    
  else return false;
});
//resultsは、テーブルトップの左上隅にあるすべてのオブジェクトの配列です。

getAllObjs()

ゲーム内のすべてのオブジェクト (すべてのタイプ) の配列を返します。 filterObjsを呼び出して、すべてのオブジェクトに対してtrueを返すのと同じです。

getAttrByName(character_id, attribute_name, value_type)

属性の値を取得します。属性が存在しない場合は、キャラクターシートのデフォルト値を使用します。 value_typeはオプションのパラメータで、"current "または "max "を指定する。

getAttrByNameは属性の値のみを取得し、属性オブジェクト自体は取得しません。 current "または "max "以外の属性のプロパティを参照したい場合、または属性のプロパティを変更したい場合は、findObjsなど、上記の他の関数のいずれかを使用する必要があります。

繰り返しセクションの場合は、repeating_section_$n_attribute という書式を使うことができる。nは、繰り返し行番号（ゼロから始まる）。 例えば、repeating_spells_$2_nameは、repeating_spellsの3行目のnameの値を返す。

以下のようにすれば、getAttrByNameと同等の動作を実現できる：

// current と max は、アトリビュートとゲームシステムに完全に依存します
// そのため、これらを自動的に決定する関数はありません
function myGetAttrByName(character_id,
                         attribute_name,
                         attribute_default_current,
                         attribute_default_max,
                         value_type) {
    attribute_default_current = attribute_default_current || ''；
    attribute_default_max = attribute_default_max || '';
    value_type = value_type || 'current';

    var attribute = findObjs({
        type: 'attribute',
        characterid: character_id,
        name: attribute_name
    }, {caseInsensitive: true})[0];
    if (！attribute) {
        attribute = createObj('attribute', {
            characterid: character_id,
            name: attribute_name,
            current: attribute_default_current,
            max: attribute_default_max
        });
    }

    if (value_type == 'max') {
        return attribute.get('max');
    } else {
        return attribute.get('current');
    }.
}