コメントを使う

マルチプレイのニコ生ゲームでは、配信に流れたコメントを受信して、ゲーム内で利用することができます。

コメントを受け取ることで「視聴者のコメントに応じてゲームの展開が変化する」「放送者のコメントによってゲームを制御する」といったコンテンツが作成できます。

INFO

• この機能はマルチプレイゲーム専用です。ランキングゲームは利用できません。
• ニコ生ゲームでコメントを受信しても、配信上のコメント表示には影響しません。

コメントの受信

ニコ生ゲームでコメントを受信するには、次の手順が必要です。

1. game.json に environment.external.namagameComment プロパティを追加する
2. シーンの onMessage トリガーに、コメントを処理するハンドラを登録する
3. g.game.external.namagameComment の start() を呼び出す

コメントの受信開始・停止は g.game.external.namagameComment (namagameComment プラグイン) で行います (3)。 このプラグインを使うために game.json を編集する必要があります (1)。 配信に送られたコメントはメッセージイベント (g.MessageEvent) としてゲームに通知されるため、 onMessage トリガーのハンドラで受け取ることができます (2)。

TIP

namagameComment のように g.game.external 以下に与えられる機能を 外部プラグイン (または単に "プラグイン") と呼びます。 Akashic ゲームは、必要な外部プラグインを game.json で宣言することができます。 ただしどの外部プラグインが利用できるかは実行環境に依存します。

namagameComment プラグインは、ニコニコ生放送のほか akashic serve コマンドで利用できます。 (参照: #動作確認)

game.json の編集

game.json に environment.external.namagameComment プロパティを追加してください。 値は現在のところ "0" とする必要があります。

{
  "environment": {
    "sandbox-runtime": "3",
    "external": {
      "namagameComment": "0"
    }
  }
}

これによりゲーム内で g.game.external.namagameComment を利用できるようになります。

コメントを処理するハンドラの登録

コメントはゲームに対して g.MessageEvent として送られます。 シーン (g.Scene) の onMessage トリガーにハンドラを登録して、ゲームに必要な形でコメントを処理してください。

以下は、受信したコメントの情報をコンソールに出力するだけのコード例です。

// scene はコメントを受信したいシーンとする。
scene.onMessage.add((ev) => {
  // .data.type が "namagame:comment" であるのがコメント通知イベント。
  if (ev.data && ev.data.type === "namagame:comment") {
    // .data.comments にコメント情報の配列が与えられる。
    const comments = ev.data.comments;

    for (const c of comments) {
      // 各コメント情報からコメント本文などを取得できる。
      console.log(
        c.comment, // コメント本文
        c.isAnonymous // 匿名コメントであるか否か
      );
    }
  }
});

コメントを通知するイベントは「data.type プロパティが "namagame:comment" である g.MessaveEvent 」として通知されます。 data.comments にコメント情報が配列で格納されています。

このコード例ではコメント情報のうち、コメント本文 (comment プロパティ) と 「匿名コメントであるかどうか」のフラグ (isAnonymous プロパティ) を利用しています。 (他のプロパティについては 後述)

TIP

大量のコメントを受信する際の通信量を減らすため、 comments は配列になっています。 上のコード例では for-of 文で単純にすべてのコメント情報を順に処理しています。 頻度が高くなければ、コメントは一つずつ (長さ 1 の配列で) MessageEvent として通知されます。

受信開始

受信開始は namagameComment プラグインの start() メソッドで行います。

g.game.external.namagameComment?.start();

?. を使っていることに注意してください。

これはこのプラグインが、ニコニコ生放送のサーバ上の (視聴者に対応しない) 特殊なインスタンスにしか存在しないためです。 その一箇所で呼び出しさえすれば、マルチプレイの全員がコメント通知イベントを受信できるようになっています。 そのため ?. を使うなどして「プラグインがある環境では start() を呼び出し、ない環境では何もしないでおく」必要があります。

TIP: ?. 演算子のサポート

?. (optional chaining) 演算子は、akashic-cli@3.0.0 以降で利用できるようになりました。 (参考: ニコ生ゲームを作ろう » ECMAScript のバージョン (JavaScript で利用できる機能) について)

以前のバージョンでは、if 文などを使って書く必要があります。

if (g.game.external.namagameComment) g.game.external.namagameComment.start();

ただし、いずれにせよ akashic serve でコメント機能を動作確認するには、後述のとおり 3.0.7 (予定) 以降の akashic-cli が必要です。バージョンが古い場合は npm install -g @akahsic/akashic-cli を実行して、最新に更新することをおすすめします。

受信停止

コメントが必要なくなった時には、 stop() メソッドで受信を停止してください。

g.game.external.namagameComment?.stop();

動作確認

akashic serve コマンドで、namagameComment プラグインを含む動作確認が可能です。 akashic serve 上では次の方法でコメントを送信でき、またゲーム内で受信できます。

• UI (ブラウザ画面) から送信
• sandbox.config.js で指定したテンプレートを (自動または手動で) 送信

INFO

これらの機能は akashic-cli@3.0.10 以降で利用可能です。

serve の UI (ブラウザ画面) からの送信

akashic serve の開発者ツール、 Niconico タブでコメントを送信できます。

開発者ツールの Niconico タブ (画面下側) を開いた akashic serve

開発者ツールの Niconico タブで、画面左側から "Comment" を選択すると、以下の UI が表示されます。

• 受信したコメント一覧
• コメント入力欄

TIP

画面下側の開発者ツール (devtool) 部分は、画面右上のハンバーガーボタン () を押すと表示されます。

コメント入力欄では、コメント本文とコマンドとして任意の文字列を指定できます。 "Send" ボタンを押すと、送信者タイプ (Anonymous, Named, Broadcaster) に応じた内容でコメントが送信されます。

送信者 タイプ	意味合い	詳細
Anonymous	「なふだ機能」OFFで送信	ゲームに送られるコメント通知イベントの isAnonymous を true 、userID をランダムな文字列にする
Named	「なふだ機能」ONで送信	ゲームに送られるコメント通知イベントの isAnonymous を false に、 userID をそのウィンドウのプレイヤー ID にする
Broadcaster	放送者コメントとして送信	ゲームに送られるコメント通知イベントの isAnonymous を false に、 userID と vpos を undefined にする

TIP 放送者コメントの確認

serve が --target-service nicolive (または -s nicolive) で起動されている場合、 最初に開かれたウィンドウが放送者役として扱われます (詳細)。 このウィンドウの送信者タイプは Broadcaster に固定されます。 また他のウィンドウでは Broadcaster を選択できなくなります。

INFO

Comment の画面は、 game.json の environment.external.namagameComment フィールドがあるゲームでのみ有効になります。

テンプレートからの送信

動作確認中に都度入力する手間を省くため、事前にコメントのテンプレートを作成しておくことができます。

テンプレート設定がある場合の画面

テンプレートの設定がある場合、コメント入力欄の上に "Template" 列が表示されます。 この列のボタン押下で指定したコメント (複数可) を送信できます。

テンプレートは、 sandbox.config.js の external.namagameComment.templates フィールドで指定します。

TIP sandbox.config.js

sandbox.config.js は akashic serve/sandbox コマンドの設定ファイルです。 game.json のあるディレクトリにこの名前のファイルを置くと、起動時に自動的に認識されます。 詳細は リファレンス » 設定ファイル » sandbox.config.js の仕様 を参照してください。

次の例は、「あいうえお」というコメントが 3 度送られるテンプレート "あいうえおx3" を記載した sandbox.config.js です。

module.exports = {
  external: {
    namagameComment: {
      templates: {
        // (テンプレート名): (内容) の形式で指定
        "あいうえおx3": {
          // コメントの内容
          comments: [
            // userID: pid1 が非匿名で「あいうえお」とコメント
            { comment: "あいうえお", userID: "pid1", isAnonymous: false },
            // 最初のコメントの 300 フレーム後、放送者コメントとして「かきくけこ」とコメント
            { comment: "かきくけこ", isAnonymous: false, frame: 300 },
            // 最初のコメントの 1000 フレーム後、匿名で「らりるれろ」とコメント
            { comment: "らりるれろ", userId: "ghijkl", isAnonymous: true, frame: 1000 },
          ],
        },
      },
    },
  },
};

comments の各要素には、コメント情報に存在するフィールドをすべて指定できます (参考: #コメント通知イベント) 。 さらに frame プロパティで、送信開始から何フレーム後に送信するかも指定できます (指定しなければ直前のコメントと同時に送られます) 。

そのほかテンプレートでは、特定タイミングでの自動送信も指定できます。 詳細は #コメントテンプレート の節を参照してください。

仕様

このページの以下の部分は、各 API やデータの仕様をまとめています。

プラグインAPI

namagameComment プラグインは、 start(), stop() の 2 つのメソッドを持ちます。

WARNING

このプラグインはインスタンスによって存在しない場合があります。 各メソッドは ?. 演算子などを使って、常に存在を確認してから呼び出してください 。

start()

start() はコメントの受信を開始します。

g.game.external.namagameComment.start(opts, callback);

引数 opts はコメント受信のオプション、 callback は完了時に呼び出されるコールバックです。 ただしどちらも省略できます。

第一引数 opts は将来の拡張に備えたもので、現在のところ未使用です。 (型定義上は null や {} を渡せるようになっています)

第二引数 callback は、 start() の完了時に呼び出される関数です。 呼び出しの際、以下の引数が与えられます。

引数	型	値
第一引数 (err)	Error または null	名前取得に成功した場合、 null 。 失敗した場合、対応する Error 。

完了を待つ必要がなく、エラーに対して行う処理がない場合は、 callback を省略することができます。

start() の戻り値は undefined です。

stop()

stop() はコメントの受信を停止します。

g.game.external.namagameComment.stop();

引数はありません。戻り値は undefined です。

コメント通知イベント

配信上のコメントは、 コメント通知イベント としてゲームに与えられます。 コメント通知イベントは、次の条件を満たすイベント ev です。

• g.MessageEvent である
• ev.player.id (送信者) が ":akashic" である
• ev.data が次の要素を持つオブジェクトである

プロパティ名	内容
type	"namagame:comment" という文字列
comments	コメント情報の配列

g.MessageEvent の data.type を確認することで、そのイベントがコメント通知イベントかどうか判別することができます。

TIP

data プロパティは undefined や null でもありうることに注意してください。 data が null などでも動作する形で判定を行う必要があります。

ev.data?.type === "namagame:comment";

コメント通知イベントの comments は、コメント情報の配列です。 コメント情報 は、次のプロパティを持つオブジェクトです。

プロパティ名	型	内容
comment	string	コメント本文。
command	string または undefined	コメントのコマンド指定。(参考: 生放送プレーヤー操作方法) ない場合は undefined 。
userID	string または undefined	コメントを送信したユーザ ID 。「なふだ機能」が OFF (匿名) のコメントの場合、ハッシュ化されたユーザ ID。放送者コメントの場合のみ undefined 。
isAnonymous	boolean	匿名のコメント (「なふだ機能」が OFF) かどうか。放送者コメントの場合は false 。
vpos	number または undefined	コメントの受信タイミング。放送開始からのセンチ秒の経過時刻。放送者コメントの場合のみ undefined 。

TIP コメントの分類

すなわちコメントは次のようなコードで振り分けることができます。

if (comment.userID === undefined) {
  // 放送者のコメント
} else {
  // 視聴者のコメント

  // さらに匿名かどうかで処理を分けるなら
  if (comment.isAnonymous) {
    // 視聴者の匿名コメント
  } else {
    // 視聴者の非匿名コメント
  }
}

注意: userID とプレイヤー ID

コメント情報の userID は、ゲーム内のプレイヤー ID (g.game.selfId や、イベントの player.id プロパティで得られる値) と比較することができます。

しかしニコニコ生放送のコメントは、デフォルトでは匿名 (「なふだ機能」が OFF) になっています (参考: なふだ機能とは) 。 少なくないコメントにおいて userID が匿名化された値になっている可能性が高く、 コメントの送信者とゲームのプレイヤーを紐づけることは必ずしもできない 点に注意してください (放送者コメントを除き) 。

「ゲームに参加しているプレイヤーのコメント」を特に識別したい場合は、 「ゲーム内で "なふだ機能" を ON にするよう求める」 「メインゲーム開始前にプレイヤーにテストコメントを送信させて確認する」など、ゲーム側での対応が必要になります。

補足: vpos と受信順

ゲームがコメント通知イベントを 受信する順 は、vpos の値と厳密に対応する保証はありません。 いくらか前後する可能性があります。

コメントリスト (配信画面のコメント一覧) の表示順にできるだけ合わせて順序を判定したい場合は、 vpos の値で比較してください。 ただし vpos で比較してもなお、センチ秒 (1/100 秒) 単位で同一時刻のコメントの順序は保証されません。 そもそも放送者コメントは vpos が与えられないこともあり、コメントリストの表示順を完全に再現することはできないものとして扱ってください。

コメントテンプレート

sandbox.config.js の external.namagameComment.templates は、コメントテンプレートのテーブルです。 存在する場合、templates はオブジェクトでなければなりません。 templates の各キーはテンプレート名、値は対応するコメントテンプレートです。

// sandbox.config.js の external.namagameComment.templates の構造
{
  external: {
    namagameComment: {
      templates: {
        "<テンプレート名A>": {/* コメントテンプレート */},
        "<テンプレート名B>": {/* コメントテンプレート */},
        // ...
      }
    }
  }
}

コメントテンプレートは、次の要素を持つオブジェクトです。

プロパティ名	型	省略可否	説明
comments	配列	必須	送信するコメント内容の指定。
startBy	"playStart", "pluginStart", または "manual"	省略可	自動送信の開始タイミング (後述)。 省略された場合、 "manual" 。

comments はコメント内容を指定するオブジェクトの配列です。その各要素は次のプロパティを持ちます。

プロパティ名	型	省略可否	説明
comment, command, userID, isAnonymous, vpos	-	省略可	コメント情報 の同名のプロパティに対応。
frame	number	省略可	送信タイミング。単位はフレーム。 値の解釈は startBy によって決まる。 省略された場合、この要素が配列の最初の要素なら 0 、それ以外は直前の要素のそれと同値。

startBy は自動送信の有無・タイミングを指定します。値は次のいずれかです。

startBy	自動 送信	frame の解釈 (送信タイミング)
"playStart"	する	ゲーム開始からの経過フレーム数。
"pluginStart"	する	namagameComment プラグインの start() 呼び出しからの経過フレーム数。
"manual"	しない	UI から送信 (して、serve のサーバに到達) してからの経過フレーム数。

TIP

startBy の指定に関わらず、全てのコメントテンプレートは serve の UI からボタンで送信できます。

次のコードは、三種類のコメントテンプレートを定義した sandbox.config.js の例です。

module.exports = {
  external: {
    namagameComment: {
      templates: {
        // userID: "pid1" が非匿名で「あいうえお」と送信するテンプレート。
        "あいうえお": {
          comments: [
            { comment: "あいうえお", userID: "pid1", isAnonymous: false }
          ]
        },
        // コマンド "shita red" つきの放送者コメント「あいうえお」と匿名コメント「かきくけこ」を送信するテンプレート。
        "あいうえお＆かきくけこ": {
          comments: [
            { comment: "あいうえお", isAnonymous: false, command: "shita red" },
            { comment: "かきくけこ", userID: "efgefg", isAnonymous: true, command: "shita red" },
          ],
        },
        // userID: "pid1" と匿名 (「なふだ機能」OFF) の二人が
        // 200 フレーム間隔で「わこつ」と送信するテンプレート。
        // namagameComment プラグインの `start()` 後 100 フレーム目から自動送信。
        "自動送信:わこつ×3": {
          startBy: "pluginStart",
          comments: [
            { frame: 100, comment: "わこつ", userID: "pid1", command: "ue", isAnonymous: false },
            { frame: 300, comment: "わこつ", userID: "abcabc", isAnonymous: true },
            { frame: 500, comment: "わこつ", userID: "cdecde", isAnonymous: true }
          ]
        }
      }
    }
  }
};