AutoMuteUs 7.0 のリリース： スラッシュコマンド対応などいろいろ

AutoMuteUs が 7.0 にメジャアップデートされ、操作方法が .au やメンション から スラッシュコマンド に変更されました。これによって操作感が大きく変わり、またセルフホストでは関連するオプションがいくつか追加されています。

本エントリでは、公式ボットサービスの利用者 と セルフホストの利用者 の 双方 を対象に、簡単に変更点とその概要、使い方を紹介します。

全利用者向けの情報

公式ボットサービスとセルフホストのどちらの利用者にも適用できる情報です。

アップデートの背景

今回のアップデートは、ひとことで言えば、Discord 側の仕様変更への追従が目的です。

2021 年 10 月に、大規模に使われているボットでは .au などプレフィックス形式のコマンドが将来的に受け取れなくなる 旨が、Discord 側から予告 されていました。開発者には対策としてスラッシュコマンドなど新しい方式への移行が求められたため、今回、AutoMuteUs もこれに対応したということです。

スラッシュコマンド化しなくても メンションは引き続き受け取れる旨も案内されていた ため、先日、暫定的にメンションでコマンドを受け付ける修正が行われていました（6.15.3）が、今回のアップデートで、恒久的な対策として、より望ましい形への改修が行われたことになります。

スラッシュコマンドへの統一

これまでの AutoMuteUs の操作は、次のように .au などの文字列か、あるいはボットへのメンションなど、所定のプレフィックスを先頭に付与してコマンドを実行する形でした。

.au new
@AutoMuteUs new

AutoMuteUs の 7.0 から、これが Discord の スラッシュコマンド を使った実装に変更され、プレフィックスでは操作できなくなりました。

7.0 では、Discord の入力欄で / を入力 するだけで 使えるコマンドが一覧 され、候補から簡単に選択できる ほか、/ の後も続けて入力すれば候補を絞り込めるようになっています。タブ補完 も有効で、その後に続ける パラメータ も 取りうる値に応じて適切な選択肢が表示 されます。

総じて 手でコマンドを一字一句入力する手間がほとんどない 状態になり、ユーザビリティが大きく向上しています。モバイルアプリケーションからの操作もしやすくなっています。

キャプチャ用リンクの通達方法の変更

従来の .au new に相当する /new の実行時、従来は DM でキャプチャ用のリンクが届いていましたが、これが以下のように コマンドへの返信 で届くようになります。この返信は /new を実行したユーザにしか見えません。

通常、返信は ゲーム開始のメッセージの上 にあることになるので、見落とさないように注意です。

プレイヤごとの色の指定方法の変更

これまで、Discord のユーザとゲーム中のプレイヤの色の紐づけは、Bot からのメッセージへの絵文字でのリアクションで行っていました。これが、メッセージ下のプルダウンからの選択に変更されています。

従来の手法には、小さくて操作しにくい、色の判別がしにくいなどいくつか課題がありましたが、今回の変更で、簡単かつ確実な操作ができるようになっています。

従来のコマンドのスラッシュコマンドとの対応付け

基本的には、.au new に相当するものは /new、.au map に相当するものは /map など、従来のコマンドをそのまま / で表記 すれば動作するように対応づけられているものが大半です。

一方で、一部、パラメータの有無や指定方法が変更されているものもあります。また、キャッシュ制御や全員のアンミュートなど、通常は利用しない一部の特殊な操作が /debug コマンドにまとめられました。使えるコマンドは 公式のヘルプ で一覧されています。

とはいえ、実際にコマンドを入力しはじめれば使えるコマンドが一覧されますし、指定が必須のものは必ず入力を求められる（入力しないと送信できない）ようになっています。/help を起点にコマンドを見つけて、実際に触ってみるとわかりやすいでしょう。

使えるコマンドの一覧

今回のアップデートに合わせて、公式のヘルプ が非常に充実しました。全てのコマンドとオプションが列挙されていますので、併せてどうぞ。

• AutoMuteUs – Commands

コマンドを丸ごとコピー＆ペーストしたい場合

コピー＆ペーストで使えるようにコマンドの全文を書き下したい場合は、スラッシュコマンドに渡すオプションは <オプション名>:<値> で表現できます。以下は例です。

• AirShip のマップを表示する
  • /map map_name:Airship
• ユーザ @kurokobo をゲーム内の黒色にリンクさせる
  • /link user:@kurokobo color:black

多言語対応が Crowdin に対応

7.0 でローカライズの仕組みが刷新され、Crowdin に対応しました。刷新直後（7.0.5 まで）は、機械翻訳に置き換えられてしまったことで日本語訳もだいぶ破綻していましたが、すでに複数名にご協力いただけており（ありがとうございます☺️）、7.0.6 以降は落ち着いてきています。

まだまだ完全ではないので、もし修正の提案などコントリビューションに興味がある方がいたら、Crowdin の AutoMuteUs ワークスペース から参加いただけます。

その他のノウハウやナレッジ

見かけ上の操作方法は大きく変わりましたが、内部の処理はほとんど変わっていません。設定項目などもほぼ従来のままなので、以下のエントリで紹介している諸々は引き続き有効です。

• AutoMuteUs のよくある質問と回答とかいろいろ
• Among Us 用ボット AutoMuteUs のあまり知られていない便利な機能

併せてどうぞ。

公式ボットサービス利用者向けの情報

公式ボットサービスの利用者向けの情報です。

サーバでスラッシュコマンドが使えない場合

サーバに ボットを招待した時期 によって、/ を入力してもコマンドが表示されない 場合があります。また、コマンドを実行した際に “I’m missing the following required permissions to function properly in this server or channel” と怒られる 場合があります。

これは、ボットに対してスラッシュコマンドを使う 権限が割り当てられていない ことが原因です。

この場合、通常は以下のリンクからボットを サーバに招待しなおす と解消します（キックは不要です）。

• https://add.automute.us/

念のためにキックしてから再招待してもよいですが、ボットをキックすると、.au settings や /settings でカスタマイズしていた設定が初期化される点には注意が必要です。なお、統計情報（戦績）は削除されずに維持されます。

再招待しても解決しない場合、ボットに対してサーバの中で割り当てているロールのパーミッションと、テキストチャンネルやボイスチャンネルごとのロールに対するパーミッションを確認してください。

セルフホスト利用者向けの情報

セルフホスト利用者のうち、スラッシュコマンドに対応した 7.0.0 以降を使いたい方向け の情報です。なお、スラッシュコマンドが必要ない場合 は、以前のバージョンを引き続き利用可能 です。

変更点ざっくりまとめ

• ボットに必要な権限が変更されました。招待用 URL の再発行とボットの再招待が必要になる場合があります
• Docker Compose で使う docker-compose.yml と .env が修正されています。最新のファイルをダウンロードして置き換えることをおすすめします
• ボットの使い道に応じて、.env の中身と起動の仕方に工夫が必要です。若干ややこしい部分です

ボットの権限の追加と再招待の必要性

スラッシュコマンドを使うには、サーバごとに従来の bot スコープに加えて application.commands スコープ の許可が必要です。このスコープは比較的最近追加されたもので、詳細な事情は割愛しますが、これまで各所で紹介されている手順で 2021 年 3 月 24 日以降にボットを招待した場合 は、ほとんどの場合スコープが足りない はずです。

これに対応するには、以下のドキュメントを参考に 招待用 URL を再発行 し、ボットを 再度サーバに招待 します（キックは不要です）。

• deploy/BOT_README.md at main · automuteus/deploy

重要なのは、SCOPES の欄で 従来の bot に加えて application.commands にチェック を入れる点です。その下の BOT PERMISSIONS 欄でも、従来の各所の手順のように Administrator ではなく、できればていねいに指定するとよいでしょう。

併せて、ボットの権限をサーバ内のロールやチャンネルごとのパーミッションで制御している場合は、適宜修正が必要です。

Docker Compose 用のファイルの更新

スラッシュコマンド化に併せて、以下の Docker Compose 用のファイルが更新されています。

• docker-compose.yml（ダウンロード用直リンク）
• sample.env（ダウンロード用直リンク）

7.0.0 以降を利用したい場合は、新しいファイルをダウンロードして、これまで使っていたモノを置き換える（sample.env は .env に名前を変える必要があります）とよいでしょう。具体的な設定値については次項で紹介します。

環境変数ファイル .env で利用するタグ

スラッシュコマンドを利用するには、以下のタグを指定します。

最新バージョンは GitHub のリポジトリ（AutoMuteUs、Galactus）で確認できます。基本的には、最新バージョンを使う とよいでしょう。

古いバージョンも使えますが、その場合でも、7.0.5 まではパーミッション周りのハンドリングや翻訳が微妙な部分があるため、個人的には 7.0.6 以降がおすすめです。

環境変数ファイル .env の新しいパラメータ

sample.env に、ボットが制御するスラッシュコマンドの種類を決める SLASH_COMMAND_GUILD_IDS と、ボット停止時のコマンドの削除を安全に行えるようにする STOP_GRACE_PERIOD が追加されました。

これの使い方を理解するには、前提として Discord のスラッシュコマンドの仕様と AutoMuteUs の実装をもう一歩踏み込んで理解する必要があります。

前提： スラッシュコマンドの種類

スラッシュコマンドには、Discord の仕様として グローバルコマンド と ギルドコマンド の二種類が用意されており、おおまかにはそれぞれ次の特性があります。

• グローバルコマンド
  • そのボットを招待している すべてのサーバ でスラッシュコマンドが使えるようになる
  • スラッシュコマンドの登録後、実際にサーバでスラッシュコマンドが使えるようになるまで 最大で 1 時間 かかる
    • ボットがサーバに参加してからの時間ではなく、あくまでコマンドの登録後の時間である点に注意
    • つまり、コマンドの登録後（≒後述するがボットの起動後）に 1 時間以上が経過していれば、それ以降にそのボットを招待したサーバでは即座にコマンドが使える
  • スラッシュコマンドの削除後、実際にサーバでスラッシュコマンドが見えなくなるまで 最大で 1 時間 かかる
• ギルドコマンド
  • ボットを招待しているサーバのうち、明示的に指定した特定のサーバでだけ スラッシュコマンドが使えるようになる
  • スラッシュコマンドの登録後、スラッシュコマンドは 直ちに 使えるようになる
  • スラッシュコマンドの削除後、スラッシュコマンドは 直ちに 見えなくなる

前提： AutoMuteUs の実装

AutoMuteUs の現在の実装では、グローバルコマンドもギルドコマンドも、コマンドの登録はボットの起動時に 1 度だけ 行われます。

同様に、コマンドの削除も停止時に 1 度だけ 行われます。

新しいパラメータ： SLASH_COMMAND_GUILD_IDS

SLASH_COMMAND_GUILD_IDS をデフォルトの 空欄のまま にすると、すべてのスラッシュコマンドは グローバルコマンド として登録されます。

SLASH_COMMAND_GUILD_IDS にカンマ区切りで サーバ ID を列挙 すると、スラッシュコマンドは 列挙したサーバに対するギルドコマンド として登録されます。

前述のグローバルコマンドとギルドコマンドの特性を踏まえ、セルフホストしたボットの使い道に応じて設定を決定する必要があります。典型的には、不特定多数から利用されうる公開ボットや常時稼働させるボットであればグローバルコマンドが、利用する規模が小さい場合や頻繁に停止起動する場合はギルドコマンドが、それぞれ使い勝手がよいでしょう。

新しいパラメータ： STOP_GRACE_PERIOD

AutoMuteUs は、停止時（SIGTERM 受信時）に Discord に登録したコマンドを削除しますが、レート制限の影響もあり、通常は完了まで一分程度かかります。一方で Docker は、コンテナの停止処理を開始（SIGTERM を送信）してから、デフォルトでは 10 秒経過するとそのコンテナを強制的に終了（SIGKILL を送信）します。つまり、デフォルトの動作では、AutoMuteUs はコマンドの削除が完了する 前 に強制終了され、Discord 側に情報が残ることになります。これにより、ボットがオフラインであるにも関わらず、中途半端にスラッシュコマンドが引き続き見えてしまう状態が引き起こされます。

これを回避するために、停止処理の開始から強制終了に至るまでの待ち時間を指定するパラメータが STOP_GRACE_PERIOD です。

デフォルトでは 2 分（2m）に設定されていますが、二つ以上のサーバにギルドコマンドとして登録した場合 は、サーバ数に応じて伸ばす とよいでしょう。目安として、1 サーバあたり 1 分、バッファとして固定で 1 分と考えて設定する（例えばサーバが 3 つなら 3 分 + バッファ 1 分で 4m）と安全そうです。

グローバルコマンドとして登録した場合は、デフォルトの 2 分のままでほとんど安全です（停止後にコマンドが見えなくなるまで最大 1 時間かかりますが、待っていれば消えるはずです）。

ボットの招待と起動の順番

スラッシュコマンドを ギルドコマンド として登録する場合に限り、コマンドの登録がボットの起動時にのみ行われることを踏まえ、ボットを起動する前にボットをサーバに招待しておく必要がある 点に注意が必要です（ボットの招待は、ボットの起動状態とは無関係に行えます）。

これは、ボットへの権限の付与がサーバへの招待時に行われることと、ギルドコマンドの登録それ自体に権限が必要なことによる制約です。

ボットの起動時にギルドコマンドの登録に権限不足で失敗すると、以下のようなログとともに起動に失敗し、再起動が繰り返されます。

...
2022/**/** **:**:** Registering command help in guild 80258********36117
2022/**/** **:**:** Cannot create command: HTTP 403 Forbidden, {"message": "Missing Access", "code": 50001}
panic: Cannot create command: HTTP 403 Forbidden, {"message": "Missing Access", "code": 50001}

goroutine 1 [running]:
log.Panicf(0xd9cf7f, 0x19, 0xc000863dd0, 0x1, 0x1)
        /usr/local/go/src/log/log.go:358 +0xc5
main.discordMainWrapper(0xc000086390, 0x621b9c2d)
        /src/main.go:215 +0xfde
main.main()
        /src/main.go:43 +0x76

グローバルコマンド であれば、この制約はありません。

起動の確認

正しく登録が完了すると、コンテナ automuteus に以下のようなログが記録されます。

...
2022/**/** **:**:** Registering command new in guild 80258********36117
2022/**/** **:**:** Registering command refresh in guild 80258********36117
2022/**/** **:**:** Registering command pause in guild 80258********36117
2022/**/** **:**:** Registering command end in guild 80258********36117
2022/**/** **:**:** Registering command link in guild 80258********36117
2022/**/** **:**:** Registering command unlink in guild 80258********36117
2022/**/** **:**:** Registering command settings in guild 80258********36117
2022/**/** **:**:** Registering command privacy in guild 80258********36117
2022/**/** **:**:** Registering command info in guild 80258********36117
2022/**/** **:**:** Registering command map in guild 80258********36117
2022/**/** **:**:** Registering command stats in guild 80258********36117
2022/**/** **:**:** Registering command premium in guild 80258********36117
2022/**/** **:**:** Registering command debug in guild 80258********36117
2022/**/** **:**:** Finishing registering all commands!

これはギルドコマンドとして登録した場合の例で、グローバルコマンドとして登録した場合は若干表示が異なります（サーバ ID でなく GLOBALLY が表示）が、いずれにしても、最後に Finishing registering all commands! が表示されれば起動は正常に完了 しています。

スラッシュコマンドが使えない場合

次のような場合は、ボットに必要な権限が足りていない可能性があります。

• / を入力してもコマンドが表示されない
• コマンドを実行すると “I’m missing the following required permissions to function properly in this server or channel” と怒られる

この場合は、前述の ボットの権限の追加と再招待の必要性 を参照して、招待用 URL を再発行 し、ボットを 再度サーバに招待 したり、ロールの設定やチャンネルごとのパーミッション を確認・修正したりしてみてください。

6.x からのバージョンアップ

前述した Docker Compose 関連のファイルの更新だけ若干要注意ですが、6.x のアップデートのときと同様、統計情報（戦績）などを維持したままアップデートできます。大まかには以下の流れです。

1. 必要に応じて正しいパーミッションでボットをサーバに再招待する
2. 既存の docker-compose.yml を最新のものに置き換える
3. 既存の .env を最新の sample.env をもとに置き換えて、パラメータを適切に埋める
4. ボットを再起動する（docker-compose down して docker-compose up -d する）

7.x 内でのバージョンアップ

いちど 7.x.x の環境を作ったあと、7.x の範囲でバージョンアップをしたい場合は、AUTOMUTEUS_TAG を書き換えて再起動（docker-compose down、docker-compose up -d）するだけで完了します。

まとめ

AutoMuteUs のスラッシュコマンド化と、その周辺のもろもろを紹介しました。

バグや不明点があれば、サポートの Discord などもうまくつかっていきましょう。

AutoMuteUs 関連おすすめエントリ

• AutoMuteUs 7.3 の新機能： データベース内のデータのダウンロード
• AutoMuteUs 7.0 のリリース： スラッシュコマンド対応などいろいろ
• AutoMuteUs のよくある質問と回答とかいろいろ
• Among Us 用ボット AutoMuteUs のあまり知られていない便利な機能