AutoMuteUs 7.3 の新機能： データベース内のデータのダウンロード

@kurokobo AutoMuteUs・IT・趣味

はじめに

AutoMuteUs の 7.3 がリリースされました。このバージョンでは、AutoMuteUs のデータベース内の自ギルドに関するデータを CSV 形式でダウンロードできる機能 が追加されています。

データベース内のデータとは、簡単にいえば 戦績の集計の元ネタ です。過去の全ゲームの参加者や色や勝敗や勝因 だけでなく、各ゲームの時系列 も取得できるため、何らかの分析をしたい場合にはよい情報源にできそうです。

一方で、ダウンロードできるのは本当に データベースの中身そのもの なので、正規化された表がそのまま出力されますし、内部的な ID も ID のままで、手がかりがないと読みにくい状態です。

そこで本エントリでは、簡単にコマンドの使い方を紹介するとともに、CSV の中身の見方も簡単に説明します。

概要

前述の通り、この機能は AutoMuteUs のデータベース内の自ギルドに関するデータを CSV 形式でダウンロードできる ものです。

コマンドの構文

ダウンロードするためのコマンドは、公式のヘルプ にも記載がありますが、/download category:<カテゴリ> です。

実行すると確認メッセージが表示され、了承すると CSV ファイルがプライベートメッセージで添付されてきます。

コマンドで指定する カテゴリ には、次の 5 つがあります。各カテゴリで実際にダウンロードできる CSV ファイルの中身は、追って紹介します。

カテゴリ名内容
guildそのギルドの情報
gamesそのギルドで行われたゲームの一覧。開始・終了の時刻と勝因を含む
usersそのギルドで行われたゲームに参加したことのあるユーザの一覧
users_gamesそのギルドで行われた各ゲームに参加したユーザの一覧。参加時のプレイヤ名や役割、勝敗情報を含む
game_eventsそのギルドで行われた各ゲームの詳細な時系列情報

利用上の注意

利用にあたって、次の制約があります。

  • 公式ボット で利用するには、AutoMuteUs プレミアム の ゴールド が必要です（セルフホストでは無条件で利用できます）
  • ダウンロードできるのは、カテゴリごとに 24 時間に 1 回だけ です（セルフホストでも同じ制限があります）
  • CSV ファイルの中身は ソートされていません
  • CSV ファイルのサイズが 8 MB を超える 場合は ダウンロードできません（7.3.1 現在、Discord の添付ファイルのサイズの制約により、The interaction failed のエラーが返ります）
  • データ収集を オプトアウト（/privacy optout）したユーザに関する情報 は、そもそもデータベースに保存されていないため、ダウンロードできる CSV ファイルにも含まれません

8 MB の制限は開発側も認識しています が、相当な数のゲームが行われたギルドでないとこのサイズには到底届かないため、現時点では配慮されていません。もしこの問題に直面したギルドがあれば、サポートの Discord などで要望をあげてもらえれば、実装を検討できると思います。

CSV ファイルの解釈例

まずは CSV ファイルから読み取れる具体的な情報を紹介します。細かな読み取り方は後述します。

games カテゴリの CSV ファイルの解釈例

game_id,guild_id,connect_code,start_time,win_type,end_time,
1,8025**********6123,F3BF4835,1611451395,4,1611451752,

この CSV ファイルは、次のように解釈できます。

  • このゲームのマッチ ID は F3BF4835:1 である
  • このゲームは 2021/01/24 10:23:15（日本標準時）に開始し、同 10:29:12 に終了した
  • 勝利したのはインポスターチームであり、勝因はサボタージュの時間切れである

users_games カテゴリの CSV ファイルの解釈例

user_id,guild_id,game_id,player_name,player_color,player_role,player_won
3057**********2493,8025**********6123,1,Player1,0,0,false
3466**********4338,8025**********6123,1,Player2,7,0,false
3840**********4563,8025**********6123,1,Player3,4,1,true
5090**********1842,8025**********6123,1,Player4,3,0,false
7962**********0756,8025**********6123,1,Player5,8,0,false
7982**********4468,8025**********6123,1,Player6,9,0,false
7982**********4458,8025**********6123,1,Player7,5,1,true
7982**********6161,8025**********6123,1,Player8,1,0,false
7998**********7914,8025**********6123,1,Player9,2,0,false

この CSV ファイルからは、ゲームへの参加ユーザが次の通りであったことが読み取れます。

プレイヤ名プレイヤの色役割勝敗
Player1レッドクルー敗北
Player2ホワイトクルー敗北
Player3オレンジインポスター勝利
Player4ピンククルー敗北
Player5パープルクルー敗北
Player6ブラウンクルー敗北
Player7イエローインポスター勝利
Player8ブルークルー敗北
Player9グリーンクルー敗北

game_events カテゴリの CSV ファイルの解釈例

event_id,user_id,game_id,event_time,event_type,payload,
1,,1,1611451395,2,1,
2,,1,1611451412,2,2,
3,3466**********4338,1,1611451498,3,{"Name": "Player2", "Color": 7, "Action": 6, "IsDead": false, "Disconnected": false},
4,,1,1611451498,2,1,
5,,1,1611451507,3,{"Name": "Player2", "Color": 7, "Action": 2, "IsDead": true, "Disconnected": false},
6,5090**********1842,1,1611451533,3,{"Name": "Player4", "Color": 3, "Action": 2, "IsDead": true, "Disconnected": false},
7,,1,1611451534,2,2,
8,,1,1611451578,2,1,
9,,1,1611451625,2,2,
10,,1,1611451703,2,1,
11,7998**********7914,1,1611451737,3,{"Name": "Player9", "Color": 2, "Action": 2, "IsDead": true, "Disconnected": false},
12,,1,1611451747,2,4,
13,,1,1611451752,2,0,

この CSV ファイルからは、ゲームの時系列を次のように再現できます。

時刻イベント
2021/01/24 10:23:15タスクフェイズが開始された
2021/01/24 10:23:32緊急会議が開始された
2021/01/24 10:24:58Player2 が追放された
2021/01/24 10:24:58タスクフェイズが開始された
2021/01/24 10:25:33Player4 がキルされた
2021/01/24 10:25:34緊急会議が開始された
2021/01/24 10:26:18タスクフェイズが開始された
2021/01/24 10:27:05緊急会議が開始された
2021/01/24 10:28:23タスクフェイズが開始された
2021/01/24 10:28:57Player9 がキルされた
2021/01/24 10:29:07ゲームオーバーになった
2021/01/24 10:29:12ロビーに戻った

CSV ファイルの読み方

ここから、前述のカテゴリごとにダウンロードできる CSV ファイルのカラムの意味を紹介します。

guild カテゴリ

guild カテゴリでは、そのギルドの情報がダウンロードできます。

通常、中身は 1 行だけで、意味のあるカラムは guild_id と guild_name のみです。それ以外は CSV 化にあたって強制的に削除または固定値に置換されているため、意味のあるデータを含みません。

guild_id,guild_name,premium,tx_time_unix,transferred_to,inherits_from,
8025**********6123,discord.example.com,5,,,
カラム名説明
guild_idDiscord でのギルドの ID
guild_nameギルドの名前
premium意味なし（必ず 5）
tx_time_unix
transferred_to
inherits_from		意味なし（必ず空）

games カテゴリ

games カテゴリでは、そのギルドで行われたゲームの一覧がダウンロードできます。

1 行が 1 ゲームに相当します。game_id は後述の users_games カテゴリや game_events カテゴリの同名のカラムに対応しています。

なお、connect_code と game_id を <connect_code>:<game_id> の形式で連結した文字列は、マッチ ID として /stats view match <マッチ ID> コマンドに利用できます。

以下の例はソートしたものです。

game_id,guild_id,connect_code,start_time,win_type,end_time,
1,8025**********6123,F3BF4835,1611451395,4,1611451752,
2,8025**********6123,F3BF4835,1611451813,0,1611452925,
3,8025**********6123,F3BF4835,1611453125,1,1611454338,
4,8025**********6123,C02B1DE7,1611454568,1,1611455222,
5,8025**********6123,C02B1DE7,1611455317,1,1611456206,
...
カラム名説明
game_idそのゲームの一意の ID
guild_idDiscord でのギルドの ID
connect_codeAmongUsCapture との接続コード
start_timeそのゲームの開始時刻（エポック秒）
win_typeそのゲームが終了した理由（次表参照）
end_timeそのゲームの終了時刻（エポック秒）
win_type説明
0クルーがインポスターを追放して勝利
1クルーがタスクを完了して勝利
2インポスターがクルーを追放して勝利
3インポスターがクルーをキルして勝利
4インポスターがサボタージュで勝利
5インポスターがクルーの切断で勝利
6クルーがインポスターの切断で勝利
-1 または 7何らかの理由による異常終了

users カテゴリ

users カテゴリでは、そのギルドで行われたゲームに参加したことのあるユーザの一覧がダウンロードできます。

1 行が 1 ユーザに対応します。user_id は後述の users_games カテゴリや game_events カテゴリの同名のカラムに対応しています。

user_id,opt,vote_time_unix,
7982**********9956,true,,
5090**********1841,true,,
7982**********4467,true,,
7998**********7914,true,,
7962**********0756,true,,
...
カラム名説明
user_idDiscord でのユーザの ID
optデータ収集にオプトインしていれば true、オプトアウトしていれば false
vote_time_unix意味なし（必ず空）

users_games カテゴリ

users_games カテゴリでは、そのギルドで行われた各ゲームに参加したユーザの一覧がダウンロードできます。

game_id で絞り込めば、そのゲームに参加したユーザの情報が一覧できますし、user_id で絞り込めば、あるユーザの通算のゲームの参加状況や勝敗を一覧できます。

以下の例は game_id でソートしたものです。

user_id,guild_id,game_id,player_name,player_color,player_role,player_won
3057**********2493,8025**********6123,1,Player1,0,0,false
3466**********4338,8025**********6123,1,Player2,7,0,false
3840**********4563,8025**********6123,1,Player3,4,1,true
5090**********1842,8025**********6123,1,Player4,3,0,false
7962**********0756,8025**********6123,1,Player5,8,0,false
7982**********4468,8025**********6123,1,Player6,9,0,false
7982**********4458,8025**********6123,1,Player7,5,1,true
7982**********6161,8025**********6123,1,Player8,1,0,false
7998**********7914,8025**********6123,1,Player9,2,0,false
3057**********2493,8025**********6123,2,Player1,0,0,true
3466**********4338,8025**********6123,2,Player2,7,0,true
3840**********4563,8025**********6123,2,Player3,4,0,true
5090**********1842,8025**********6123,2,Player4,3,1,false
7962**********0756,8025**********6123,2,Player5,8,0,true
7982**********4468,8025**********6123,2,Player6,9,0,true
7982**********4458,8025**********6123,2,Player7,5,0,true
7982**********6161,8025**********6123,2,Player8,1,0,true
7998**********7914,8025**********6123,2,Player9,6,1,false
...
カラム名説明
user_idDiscord でのユーザの ID
guild_idDiscord でのギルドの ID
game_idそのゲームの一意の ID
player_nameそのユーザのプレイヤ名
player_colorそのユーザのプレイヤの色の ID（次表参照）
player_roleそのユーザがクルーなら 0、インポスターなら 1
player_wonそのユーザが勝利したなら true、敗北したなら false
player_color説明
0レッド
1ブルー
2グリーン
3ピンク
4オレンジ
5イエロー
6ブラック
7ホワイト
8パープル
9ブラウン
10シアン
11ライム
12マルーン
13ローズ
14バナナ
15グレー
16タン
17コーラル

game_events カテゴリ

game_events カテゴリでは、そのギルドで行われた各ゲームの詳細な時系列情報がダウンロードできます。

1 行がゲーム中の 1 イベントに相当します。ある単一のゲームで発生したイベントを時系列で追いかけたい場合、当該の game_id で絞り込んで、イベント群を event_id の順に見ていくことになります。

後述しますが、イベントにはいくつか種類があり、その種類に応じた補足情報が payload に保持されています。

なお、ここで記録されているイベントは、あくまでゲームの内部処理に基づくものです。したがって、例えば追放イベントとそれによる死亡イベントが時間差で別のイベントとして記録されるなど、プレイヤ目線の時系列とは若干のギャップがあることがあります。このあたりは、いくつかのゲームで実際に時系列の再現を試みると雰囲気がつかめるはずです。

event_id,user_id,game_id,event_time,event_type,payload,
1,,1,1611451395,2,1,
2,,1,1611451412,2,2,
3,3466**********4338,1,1611451498,3,{"Name": "Player2", "Color": 7, "Action": 6, "IsDead": false, "Disconnected": false},
4,,1,1611451498,2,1,
5,,1,1611451507,3,{"Name": "Player2", "Color": 7, "Action": 2, "IsDead": true, "Disconnected": false},
6,5090**********1842,1,1611451533,3,{"Name": "Player4", "Color": 3, "Action": 2, "IsDead": true, "Disconnected": false},
7,,1,1611451534,2,2,
8,,1,1611451578,2,1,
9,,1,1611451625,2,2,
10,,1,1611451703,2,1,
11,7998**********7914,1,1611451737,3,{"Name": "Player9", "Color": 2, "Action": 2, "IsDead": true, "Disconnected": false},
12,,1,1611451747,2,4,
13,,1,1611451752,2,0,
14,,2,1611451813,2,1,
15,3840**********4563,2,1611451908,3,{"Name": "Player3", "Color": 4, "Action": 2, "IsDead": true, "Disconnected": false},
16,3057**********2493,2,1611451943,3,{"Name": "Player1", "Color": 0, "Action": 2, "IsDead": true, "Disconnected": false},
17,,2,1611451955,2,2,
18,,2,1611452124,2,1,
19,,2,1611452178,2,2,
20,,2,1611452346,2,1,
21,7982**********4468,2,1611452389,3,{"Name": "Player6", "Color": 9, "Action": 2, "IsDead": true, "Disconnected": false},
22,,2,1611452392,2,2,
23,7998**********7914,2,1611452561,3,{"Name": "Player9", "Color": 6, "Action": 6, "IsDead": false, "Disconnected": false},
...
37,,26,1611453125,2,0,
38,,26,1611453125,1,{"Map": 0, "Region": 1, "LobbyCode": "TKZODF"},
...
カラム名説明
event_idそのイベントの一意の ID
user_idDiscord でのユーザの ID
game_idそのゲームの一意の ID
event_timeそのイベントの発生時刻（エポック秒）
event_typeそのイベントの種類（次表参照）
payloadそのイベントの補足情報（後述）
event_type説明payload
1ロビーの詳細情報（マップやロビーコードなど）JSON 文字列
2フェイズの遷移（タスク開始、緊急会議開始など）フェイズの ID
3プレイヤの状態の変化（追放、キルなど）JSON 文字列

event_type が 1 のときの payload

payload説明
Mapマップの ID（次表参照）
Regionリージョンの ID（次々表参照）
LobbyCodeロビーコード
Map説明
0The Skeld
1Mira HQ
2Polus
3dlekS ehT
4The Airship
Region説明
0北米
1アジア
2欧州

event_type が 2 のときの payload

payload説明
0ロビーに移動
1タスクを開始
2緊急会議を開始
3メニューに移動
4ゲームオーバー

event_type が 3 のときの payload

payload説明
Nameプレイヤ名
Colorプレイヤの色の ID（users_games カテゴリの表参照）
Actionプレイヤの状態変化の種類の ID（次表参照）
IsDead死亡していれば true、生存していれば false
Disconnected切断されていれば true、接続されていれば false
Action説明
0プレイヤがロビーに参加した
1プレイヤがゲームから離脱した
2プレイヤが死亡した
3プレイヤが色を変更した
4プレイヤの情報が再読み込みされた
5プレイヤがゲームから切断された
6プレイヤが追放された

まとめ

AutoMuteUs 7.3 で追加された、データベース内のデータをダウンロードする機能を紹介しました。

ダウンロードできるデータは、実際に AutoMuteUs の戦績表示（/stats view）で分析に使われるデータそのものです。人間が読み取るにはややこしさもありますが、うまく活用できるとおもしろいかもしれません。

AutoMuteUs 関連おすすめエントリ

@kurokobo

くろいです。ギターアンサンブルやら音響やらがフィールドの IT やさんなアルトギター弾き。たまこう 48 期ぎたさん、SFC '07 おんぞう、新日本ギターアンサンブル、Rubinetto。今は野良気味。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です