1. Roll20 ヘルプセンター
  2. 自動化
  3. Modスクリプト（API）

API: チャット

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

チャットイベント

チャット:メッセージ

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

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

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

不動産 既定値 メモ
誰 "" メッセージを送信したプレイヤーまたはキャラクターの表示名。
プレイヤーID   メッセージを送信したプレイヤーのID。
タイプ 「一般」 「general」、「rollresult」、「gmrollresult」、「emote」、「whisper」、「desc」、または「api」のいずれか。
コンテンツ "" チャットメッセージの内容。 型が「rollresult」の場合、これはロールに関するデータのJSON文字列となります。
origロール   （"rollresult" または "gmrollresult" のみ入力）プレイヤーが "/r 2d10+5 fire damage" と入力した際の、ダイスロールの元のテキスト。例： "2d10+5 fire damage" これは「rollresult」または「gmrollresult」以外のタイプのメッセージに対するコンテンツの使用に相当します。
インラインロール   (コンテンツには1つ以上のインラインロールのみが含まれます)メッセージ内のすべてのインラインロールに関する情報を含むオブジェクトの配列。
ロールテンプレート   (コンテンツには1つ以上のロールテンプレートのみが含まれます)指定されたテンプレートの名前。
ターゲット   (「秘話」のみ入力)秘話を送る相手のプレイヤーID。 秘話がGMに送信された際、そのGMの表示名を使用しなかった場合（例：GMがRileyの場合、「/w Riley テキスト」ではなく「/w gm テキスト」）、または秘話が操作プレイヤーのいないキャラクターに送信された場合、値は「gm」となります。
ターゲット名   (「秘話」のみ入力)秘話が送信されたプレイヤーまたはキャラクターの表示名。
選択された   (「api」のみ入力)コマンド入力時にユーザーが選択していたオブジェクトの配列。

注: おそらく、この情報のすべては必要ないでしょう。 ほとんどの場合、ダイス振りの全体的な結果のみに関心があるでしょう（最初の例の下部を参照）。 ただし、ダイスの出目の結果を本当に深く掘り下げたい場合には、これらすべてが提供されます。

 

ロール結果構造 例1

JSON.parseを呼び出した後 JSON.parse を content プロパティに対して呼び出すと、以下の形式のオブジェクトが得られます（これはコマンド /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

結果の注釈付き構造 /roll {1d6!!>5}>6 (爆発修正と目標成功を表示):

{
  "type":"V",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":1,
            "sides":6,
            "mods": { //ダイスロールへの修正
              "compounding": { //"compounding" = "爆発ダイスの複合効果 (!!)"
                "comp":">=", //比較タイプ
                "point":5 //比較ポイント
              }
            },
            "results": [
              {
                "v":13 //総合ダイス結果 これは複利爆発であるため、ダイスの結果は1つだけであることに注意してください。
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // この場合、結果は成功件数です
  "total":1 // 成功の総数
}

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

on("chat:message", function(msg) {
  //これによりプレイヤーは !sr と入力可能 <number> 目標値4でd6ダイスを指定回数振る。
  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>

コールバック はオプションの第三引数であり、ゲームにコマンドを送信する代わりにsendChat()呼び出しの結果を渡されるコールバック関数で構成されます。 sendChat()をこのように使用すると非同期になります。 sendChat()コマンドの結果は操作の配列となり、個々のオブジェクトはchat:messageイベントで受信するオブジェクトと同様のものとなります（上記参照）。

例えば、Roll20のダイスロールエンジンを使用してロールを実行し、その結果を即座に取得するためにこれを使用できます。 その後、ロールをゲーム内のプレイヤーに送信する前に、追加の修正を加えることができます。

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops はコマンド結果の配列になります。
    var rollresult = ops[0];
    //ここでrollresultを使って何か処理を行う。チャット:メッセージイベント時と同じように...
});

options は、メッセージの処理方法を設定するためのオプションの第四引数です。 オプションはJavaScriptオブジェクトとして指定され、そのプロパティは設定するオプションの名前、値はそれらの設定値となります。デフォルト値がfalseであるため、通常はtrueを指定します。

利用可能なオプション：

  • noarchive-- メッセージがチャットログに保存されないようにするには、これをtrueに設定してください。 これは特に、Mod（API）ボタンメニューや状態情報など、ストーリーの一部ではない出力に有用です。

  • use3d-- sendChat()関数を使用して3Dダイスロールを生成できるようになりました。 構文は単純です：sendChat("名前", "[[3d6]]を振ります", null, {use3d: true});名前パラメータにプレイヤーIDを渡した場合（例：sendChat("player|-ABC123",...)）、そのプレイヤーの色がダイスに使用されます。 そうでない場合はデフォルトの白色が使用されます。 

    注：クライアントは一度に1つの3Dロール結果しか表示できないため、連続して複数の3Dロールを実行しても意味がありません。 また、3Dロールの使用はQuantumRollサーバーに若干の負荷をかけるため、ご自身の判断でご利用いただき、1秒間に100回の3Dロールを行わないようお願いします。 ロールがプレイヤーにとって「重要」であり、ゲームに影響を与える場合に3Dロールを使用する。

    これらのオプションを調整したいが、コールバックパラメータ（3番目のパラメータ—上記参照）を使用したくない場合は、その代わりにnullを渡すだけで済みます：

 

sendChat("Status", "すべてのプレイヤーがログインしました。", null, {noarchive:true});

Mod (API) コマンドボタン

「ホールド」の更新により、API生成メッセージおよびマクロ・技能生成メッセージの両方で、新たなテキストチャット書式を活用し、チャット内に「Mod (API) コマンドボタン」を作成できるようになりました。

Markdown 形式を使用してこれを行うには：

[攻撃ロール](!attackroll)

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

/direct でメッセージを送信する場合、Markdown の解析は行われないため、 <や> といったタグは自身で追加する必要があります。 その例を挙げると：

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

チャット内でのMod（API）ボタンの入力

また、チャット内でMarkdown構文Mod（API）ボタンを入力すると、他のユーザーが使用できるようになります。 チャットパーサーによって解釈されるため、ボタンクリック時に属性・クエリ・ロールを展開させたい場合は、コマンドの一部を特別な構文（HTMLエンティティ）で入力する必要があります：

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

このサンプルボタンはそれらのいくつかを使用しています：

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

実際にMod（API）ボタンを使用してマクロや技能を呼び出すことができます。

キャラクター 代替
<改行> &#13;

これを行うには、コマンド部分を特殊コード「!&#13;」で開始し、マクロ呼び出しには「#」、能力呼び出しには「&#37;」(%)を追加します。

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

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

注記: 現時点では、サイドバーの「コレクション」タブに保存されたマクロを再開すると、内部のHTMLエンティティが元に戻されます。その後マクロを保存すると、その変更も保存されます。 この挙動は 技能 や技能コマンドボタンでは発生しません。

For 技能コマンドボタン場合、ボタンを生成する技能と参照される技能が同じシート上にある場合、構文は非常にシンプルです：

[技能](~AbilityName)

この記事は役に立ちましたか？
24人中17人がこの記事が役に立ったと言っています