はじめに
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:58 | Player2 が追放された |
| 2021/01/24 10:24:58 | タスクフェイズが開始された |
| 2021/01/24 10:25:33 | Player4 がキルされた |
| 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:57 | Player9 がキルされた |
| 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_id |
Discord でのギルドの 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_id |
Discord でのギルドの ID |
connect_code |
AmongUsCapture との接続コード |
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_id |
Discord でのユーザの 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_id |
Discord でのユーザの ID |
guild_id |
Discord でのギルドの 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_id |
Discord でのユーザの 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 |
説明 |
|---|---|
0 |
The Skeld |
1 |
Mira HQ |
2 |
Polus |
3 |
dlekS ehT |
4 |
The 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）で分析に使われるデータそのものです。人間が読み取るにはややこしさもありますが、うまく活用できるとおもしろいかもしれません。