APIチャット

このページでは、チャット機能に関する Roll20 API の詳細を説明します。


チャットイベント

チャット:メッセージ

新しいチャットメッセージを受信するたびにトリガーされます。 メッセージのタイプが "rollresult "または "gmrollresult "である場合、ロール結果の情報を含むオブジェクトを取得するために、メッセージの内容に対してJSON.parse()を呼び出す必要があることに注意してください。

注: もしプレイヤーが感嘆符(!)で始まるチャットメッセージを入力した場合、そのメッセージのタイプは "api "となり、誰にも表示されません。 この機能は、MOD(API)スクリプトが応答するコマンドを提供するために使用されることが意図されている。 つまり、メッセージのタイプが "api "であれば、それは誰にも表示されておらず、チャットメッセージを送ったプレイヤーは、おそらくMod(API)スクリプトがメッセージの結果として何かをすることを期待している。

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

プロパティ デフォルト値 備考
"" メッセージを送信したプレイヤーまたはキャラクターの表示名。
プレイヤーID   メッセージを送信したプレーヤーのID。
タイプ "一般" general"、"rollresult"、"gmrollresult"、"emote"、"whisper"、"desc"、"api "のいずれか。
内容 "" チャットメッセージの内容。 typeが"rollresult "の場合、ロールに関するデータのJSON文字列となる。
オリジナルロール   (「rollresult」または「gmrollresult」のみをタイプする)ロールの元のテキスト:プレイヤーが"/r 2d10+5 fire damage "とタイプした場合、"2d10+5 fire damage "と表示されます。 これは、"rollresult "または "gmrollresult "以外のタイプを持つメッセージにコンテンツを使用することと同じである。
インライナー   (コンテンツは 1 つ以上のインライン・ロールのみを含む)メッセージ内のすべてのインライン・ロールに関する情報を含むオブジェクトの配列。
ロールテンプレート   (コンテンツは1つ以上のロールテンプレートのみを含む)指定されたテンプレートの名前。
ターゲット   (ささやき」のタイプのみ)ささやきを送る相手のプレイヤーID。 囁きがGMの表示名を使わずに送信された場合(つまり、ライリーがGMである場合、"/w Riley text "ではなく、"/w gm text")、または囁きが支配プレイヤーのいないキャラクターに送信された場合、値は "gm "となります。
ターゲット名   ("whisper "タイプのみ)囁きが送られたプレイヤーまたはキャラクターの表示名。
選ばれた   (type "api "のみ)コマンド入力時にユーザーが選択したオブジェクトの配列。

注: おそらくこの情報すべてが必要なわけではないだろう。 ほとんどの場合、ロールの全体的な結果にしか興味がないだろう(最初の例の一番下を参照)。 しかし、ロールの結果を本当に深く掘り下げたいのであれば、それはすべて提供される。

 


ロール結果の構成 例1

を呼び出した後 JSON.パースを呼び出した後 コンテンツプロパティを呼び出すと、次のような形式のオブジェクトが得られます。 /roll {2d6}+5+1t[weather] Attack!)

{
  "type": "V", //"V" = "Validated Roll" (今は常に "V "である)
  "rolls":[
    {
      "type": "G", //"G" はグループ化されたロールを示す。 グループとは、ロールの中の一連の "サブロール "のようなものである。
      "rolls":[
        [
          {
            "type": "R", //"R" = "Roll"
            "dice":2, //振ったサイコロの数(2dXは2個)
            "sides":6, //サイコロの面の数(Xd6は6面)
            "mods":{},
            "results":[各ダイスの結果の配列。
             {
               "v":1 // 最初の2D6で1を出した
             },
             {
               "v":5 //2回目の2D6で5を出した
             }.
            ]
          }
        ]
      ],
      "mods":{},
      "resultType": "sum", //結果は合計(成功チェックとは異なる)
      "results":[
        {
          "v":6 // この場合、グループの総合結果(合計)。
        }
      ]
    },
    {
      "type": "M", //"M" = 数式
      "expr": "+5+"
    },
    {
      "type": "R", //"R" = ロール
      "dice":1,
      "table": "weather", //テーブルプロパティには、このロールがテーブルに対して行われた場合に使用されるテーブルの名前が設定される
      "mods":{},
      "sides":2, //テーブルロールについては、おそらくこれを無視すればよい。
      "results":[
        {
          "v":0, //テーブル項目の "値 "がロールバックされた。 テキスト・テーブルの場合、これは常に0である。
          "tableidx":1, //ロールされたテーブル内の項目のインデックス。
          "tableItem":{テーブルがロールされたときのテーブルアイテムオブジェクトのコピー。
            "name": "rainy", 
            "avatar":", //ローラブルテーブルが画像アイコンを使用している場合、これは画像へのURLになります
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }.
        }
      ]
    },
    {
      "type": "C", // "C" = コメント
      "text":" アタック!"
    }
  ],
  "resultType": "sum", //ロール全体の結果タイプ
  "total":11 //ロール全体の合計(すべてのサブグループを含む)
}.

ロール結果の構成 例2

の結果の注釈付き構造体。 /ロール {1d6!>5}>6(爆発する修正とターゲットの成功を示す):

{
  "type": "V",
  "rolls":[
    {
      "type": "G",
      "rolls":[
        [
          {
            "type": "R",
            "dice":1,
            "sides":6,
            "mods":{ //出目の修正
              "compounding":{ //"compounding" = "配合が爆発する(!!)"
                "comp":">=", //比較タイプ
                "point":5 //比較ポイント
              }.
            },
            "results":[
              {
                "v":13 //Overall dice result. これは複合爆発なので、サイコロの結果は1つだけであることに注意。
              }
            ]
          }
        ]
      ],
      "mods":{
        "success":{
          "comp":">=",
          "point":6
        }.
      },
      "resultType": "sum",
      "results":[
        {
          "v":13
        }
      ]
    }.
  ],
  "resultType": "success", // この場合、結果は成功のカウントである
  "total":1 //成功の総数
}.

チャットイベント例(カスタムロールタイプの実装)

on("chat:message", function(msg) {
  //これでプレイヤーは「!!sr <数字> 」を入力し、「4」を目標にサイコロを振ることができます。
  if(msg.type == "api" && msg.content.indexOf("!sr ") !== -1) {
    var numdice = msg.content.replace("!sr ", "");
    sendChat(msg.who, "/roll " + numdice + "d6>4");
  }.
});

sendChat(speakingAs, input [,callback [, options]] )

この機能を使ってチャットメッセージを送信することができます。

speakingAsは以下のいずれかである:

  • 任意の文字列。この場合、その文字列がメッセージを送った人の名前として使われる。 例 "ライリー"
  • 選手のID。"player|-Abc123 "のフォーマットで、"-Abc123 "は選手のID。 そうすれば、自動的に選手のアバターと名前が使われます。
  • キャラクターのID。"character|-Abc123 "のようにフォーマットされる。 そうすれば、自動的にキャラクターのアバターと名前が使用されます。


入力は、Roll20アプリで使われているものと同じように、有効な式でなければなりません。 テキストを入力して基本的なメッセージを送るか、"/roll"、"/em"、"/w "などのスラッシュ・コマンドを使う。 加えて

  • 文字属性は、@{CharacterName|AttributeName} の形式で使用できます。
  • キャラクター・アビリティは、次のような形式で使用できます:%{CharacterName|AbilityName}.
  • マクロは使えない
  • /direct <msg>" コマンドを使えば、何の処理もせずにメッセージを送信することができ ます(URLの自動リンクなど)。メッセージの中では、以下のHTMLタグを使う ことができます:

 

<code><span><div><label><a><br><br /><p><b><i><del><strike><u><img>
<blockquote><mark><cite><small><ul><ol><li><hr><dl><dt><dd><sup>
<sub><big><pre><figure><figcaption><strong><em><table><tr><td><th>
<tbody><thead><tfoot><h1><h2><h3><h4><h5><h6>

コールバックはオプションの第3パラメータで、ゲームにコマンドを送信する代わりにsendChat() の結果を渡すコールバック関数です。 この方法でsendChat()を使用すると、非同期になる。 sendChat()コマンドの結果は、操作の配列になり、個々のオブジェクトは、chat:messageイベント(上記参照)の間に受け取るオブジェクトと同じようになります。

例えば、Roll20のロール・エンジンを使ってロールを行い、その結果をすぐに得ることができます。 そして、ゲーム内のプレーヤーに送る前に、ロールに追加の修正を加えることができる。

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // opsはコマンド結果の配列になる。
    var rollresult = ops[0];
    //ここで、chat:messageイベントの時と同じように、rollresultで何かをする。
});

オプション はオプションの4番目のパラメータで、メッセージの処理方法のオプションを設定します。 オプションはjavascriptのオブジェクトとして指定され、そのプロパティは設定するオプションの名前で、その値はそのオプションの設定値です。

利用可能なオプション:

  • noarchive-- メッセージがチャットログに保存されないようにするには、これをtrueに設定します。 これは、MOD(API)ボタンのメニューやステート情報など、ストーリーの一部ではない出力に特に便利である。
  • use3d-- sendChat()関数を使って3Dダイスの出目を生成できるようになりました。 構文は次のとおりです:sendChat("Name", "Rolling [[3d6]]", null, {use3d: true}); sendChat("player|-ABC123",...) のように、nameパラメータにプレイヤーIDを渡すと、そのプレイヤーの色がサイコロに使用されます。 そうでない場合は、デフォルトの白が使用される。 

    注: クライアントは一度に1つの3Dロールの結果しか表示できないので、何度も別々の3Dロールを連続して行っても意味がない。 また、3Dロールを使用すると、QuantumRollサーバーに少し負担がかかるので、自分の判断で、1秒間に100回の3Dロールを行わないようにしてください。 3Dロールは、そのロールが選手にとって「重要」であり、ゲームに影響を与える場合に使用する。

    これらのオプションを調整したいが、コールバック・パラメーター(第3のパラメーター--上記参照)を使いたくない場合は、代わりにnullを渡すだけでよい:

 

sendChat("Status", "All players are logged in", null, {noarchive:true});

MOD(API)コマンドボタン

このアップデートにより、チャットに「MOD(API)コマンドボタン」を作成することができるようになりました。

Markdown書式を使って行う:

[攻撃ロール](!attackroll)

括弧内のテキストはボタンに表示され、括弧内の部分は実行されるコマンドである。 通常のロール(マクロ、アビリティ、クエリーなど)には何でも含めることができますが、コマンド自体はそれをクリックしたプレイヤーによって実行されることに留意してください。 例えば、メッセージを見ることができる全員がその文字にアクセスできない場合は、@{Character|AC} を含めないでください。 その代わりに、チャットメッセージを送信する前に、コマンドを送信したときの実際の値を入力してください。 これらのボタンは、一般メッセージ、ウィスパー、gmwhispersなど、すべてのメッセージタイプで機能します。

メッセージの送信に/directを使用した場合、Markdownの解析は行われませんので、独自の <a> タグを含める必要があることに注意してください。 その例を挙げよう:

<a href="!attackroll">攻撃ロール</a>

チャットでMOD(API)ボタンを入力する

また、Markdown構文Mod(API)ボタンをチャットに入力し、他の人が使えるようにすることもできます。 これらはチャットパーサーによって解釈されるため、ボタンがクリックされたときに属性、クエリー、ロールを展開させたい場合は、コマンドの一部を特別な構文(HTMLエンティティ)で入力する必要があります:

キャラクター 交換
 % &#37;
) &#41;
 ? &#63;
@ &#64;
[ &#または &lbrack;
] &#または &rbrack;

このサンプル・ボタンはその一部を使用しています:

[攻撃ロール](!attackroll &#64;{target|token_id} &#91;[1d6+&#63;{Bonus|0}]&#93;)

実際にMOD(API)ボタンを使ってマクロやアビリティを呼び出すことができる。

キャラクター 交換
<キャリッジ・リターン> &#13;

そのためには、コマンド部分を特殊コード!&#13;でマクロを呼び出すか、&#37;(%)で能力を呼び出す:

[マクロ](!&#13;#マクロ名)

[能力](!&#13;&#37;{CharName|AbilityName})

注: 現時点で、サイドバーの「コレクション」タブで保存したマクロを再び開くと、その中のHTMLエンティティが元に戻る。 この動作はアビリティやアビリティ・コマンド・ボタンにはありません。

について アビリティ・コマンド・ボタンボタンを作成するアビリティとそれが参照するアビリティが同じシート上にある場合、構文は非常に簡単です:

[能力](~能力名)

この記事は役に立ちましたか?
21人中14人がこの記事が役に立ったと言っています