コマンドの基本設定(名前・クールダウン・権限・エラー処理)

コマンドビルダーの起点となるノード「スラッシュコマンド」では、Discord 上でのコマンド名や説明、クールダウン、誰がそのコマンドを使えるかといった「コマンド全体の基本設定」をまとめて行います。あわせて、コマンドの実行中にエラーが起きたときの動きを決める「エラーハンドラー」ノードについても、このページで説明します。

設定をひらく

設定を変更するには、コマンドビルダーの編集画面で起点のノードをクリックします。

起点の「スラッシュコマンド」ノードをクリックする

コマンドビルダーのキャンバス上には、一番左(または上)に必ず1つだけ「スラッシュコマンド」のノードがあります。これがコマンドの入り口です。このノードをクリックすると、右側に設定パネルが開きます。

設定パネルで各項目を編集する

開いたパネルで、コマンド名・コマンドの説明・コマンドクールダウン・権限設定の各項目を上から順に編集します。入力・選択するとすぐに反映されます。

起点の「スラッシュコマンド」ノードはコマンドに必ず1つだけ存在し、削除や移動はできません。

スラッシュコマンドノードの設定一覧

「スラッシュコマンド」ノードの設定パネルにある項目:

設定項目	入力方法	内容
「コマンド名」	テキスト入力	Discord 上に表示されるコマンドの名前。必須です。
「コマンドの説明」	テキスト入力	Discord 上に表示されるコマンドの説明文。任意です。
「コマンドクールダウン」	選択(あり/なし)	連続実行を制限するかどうか。
「クールダウン期間」	テキスト入力	クールダウンの長さ(数値)。クールダウンありのときだけ表示されます。
「クールダウン単位」	選択(秒/分/時間)	クールダウン期間の単位。クールダウンありのときだけ表示されます。
「個別権限設定を有効化」	オン/オフのスイッチ	BotShade 独自の権限設定を使うかどうか。
「Discord権限より個別設定を優先」	オン/オフのスイッチ	Discord の権限判定をバイパスする危険な設定。

コマンド名とコマンドの説明

パネルの一番上にあるのが「コマンド名」と「コマンドの説明」です。どちらも Discord のコマンド入力欄に表示される情報です。

「コマンド名」(補足:「Discord上から操作するコマンドの名前」): ユーザーが Discord で / を入力したときに候補として出てくる名前です。必須項目です。既存のコマンドの名前を変更して保存すると、新しい名前に置き換わります(以前の名前のコマンドは残りません)。
「コマンドの説明」(補足:「Discord上から操作するコマンドの詳細」): コマンド名の横に小さく表示される説明文で、入力は任意です。

コマンド名には使える文字に決まりがあります。半角英数字と、ハイフン・アンダースコア・ピリオド(- _ .)を使い、3〜50 文字の範囲で付けてください。日本語やスペースは使えません。保存時にこの条件を満たしていないとエラーになります。

コマンドクールダウン(あり/なし・期間・単位)

クールダウンは、同じコマンドが短時間に何度も実行されるのを防ぐための設定です。「コマンドクールダウン」の選択欄で次のどちらかを選びます。

選択肢	動作
「クールダウンなし」	クールダウンを設けません(初期状態)。
「クールダウンあり」	一定時間あけないと同じコマンドを再実行できなくします。

「コマンドクールダウン」を「クールダウンあり」にする

選択欄をクリックして「クールダウンあり」を選びます。すると、下に「クールダウン期間」と「クールダウン単位」の2つの欄が追加で表示されます。

「クールダウン期間」に数値を入力する

クールダウンの長さを数値で入力します。

「クールダウン単位」を選ぶ

期間の単位を「秒」「分」「時間」から選びます。

例えば「クールダウン期間」に 30、「クールダウン単位」に「秒」を設定すると、コマンドを使ったあと 30 秒間は同じ人が再実行できなくなります。

クールダウンはコマンドの実行者ごとに適用されます。あるユーザーがクールダウン中でも、別のユーザーは実行できます。なお、ボタン・選択メニュー・モーダルにはこの設定は適用されません。

権限設定 — 個別権限設定の有効化

「権限設定」という見出しの下では、そのコマンドを「誰が使えるか」を細かく制御できます。中心となるのが「個別権限設定を有効化」のスイッチです。

スイッチの状態	権限の判定方法
オフ(初期状態)	通常の Discord の権限判定を使います。
オン	BotShade 独自の権限設定(ホワイトリスト/ブラックリストなど)を使います。

「個別権限設定を有効化」をオンにする

オンにすると、下に「詳細権限設定」のパネルが表示され、ロールや権限のリストを設定できます。

ロールや権限のリストを設定する

次の「ロール・権限のホワイトリスト/ブラックリスト」を参考に、許可・拒否したい対象を追加します。

ロール・権限のホワイトリスト/ブラックリスト

「個別権限設定を有効化」をオンにすると表示される「詳細権限設定」パネルには、次の4つのリストがあります。許可(ホワイト)と拒否(ブラック)を、ロール単位・権限単位で指定できます。

リスト	役割
「ホワイトロールリスト」	許可するロールを指定します。リストに含まれるロールは常にアクセスが許可されます。
「ブラックロールリスト」	拒否するロールを指定します。リストに含まれるロールはアクセスが拒否されます。
「ホワイト権限リスト」	許可する権限条件を設定します。条件に一致するメンバーはアクセスが許可されます。
「ブラック権限リスト」	拒否する権限条件を設定します。条件に一致するメンバーはアクセスが拒否されます。

ロールリストの編集

「ホワイトロールリスト」「ブラックロールリスト」では、サーバーのロールを選んでリストに追加します。追加したロールは一覧で表示され、不要になったら削除できます。

権限リストの編集(条件の追加)

「ホワイト権限リスト」「ブラック権限リスト」では「条件を追加」ボタンで条件を1つずつ追加します。各条件(「条件 #1」のように番号が付きます)では、まず判定の仕方を選び、続いてチェックしたい Discord 権限にチェックを入れていきます。

判定の仕方(モード)は次の4種類から選びます。

モード	意味
「AND (すべて必要)」	選んだ権限をすべて持っている場合に一致します。
「OR (いずれか1つ)」	選んだ権限のいずれか1つを持っていれば一致します。
「STRICT (完全一致)」	選んだ権限と完全に一致する場合に一致します。
「CONTAINS (含む)」	選んだ権限を含んでいる場合に一致します。

各権限の行にはチェックボックスと、その横に「許可」または「拒否」のバッジが付いています。バッジをクリックすると「許可」と「拒否」を切り替えられます。チェックを入れた権限が条件の対象になります。条件は「削除」ボタン(ゴミ箱アイコン)で削除できます。

権限の項目には、例えば「管理者」「メンバーをキック」「メンバーをBan」「メッセージの管理」「ロールの管理」など、Discord の各権限が日本語で並んでいます。

ロールリストと権限リストは組み合わせて使えます。例えば「ホワイトロールリスト」に運営ロールを入れ、さらに「ホワイト権限リスト」で特定の権限を持つ人にも許可する、といった設定ができます。リストを空のままにすると、そのリストによる絞り込みは行われません。

Discord権限より個別設定を優先(危険な上書き設定)

権限設定パネルの一番下には、「Discord権限より個別設定を優先」というスイッチがあります。これは、Discord 側の権限チェックを無視して、上で設定した個別の権限設定だけで判定させるための上書き設定です(スイッチの説明:「危険な設定です。既存のDiscord権限をバイパスして、JSON側の権限設定を優先します。個別権限設定を有効化すると利用できます。」。ここでいう「JSON側の権限設定」とは、上で設定した個別の権限設定のことです)。

このスイッチは「個別権限設定を有効化」をオンにしていないと使えません。オフのときは、スイッチの下に「個別権限設定を有効化すると利用できます。」と表示されます。「個別権限設定を有効化」をオフに戻すと、この優先設定も自動的にオフになります。

「Discord権限より個別設定を優先」は Discord の権限チェックを回避する危険な設定です。意図しない人がコマンドを使えてしまう恐れがあるため、慎重に扱ってください(「個別権限設定を有効化」したときだけ使えます)。通常は、この設定をオフのままにしておくことをおすすめします。

エラーハンドラーとは — 実行中のエラーを捕捉して処理する

コマンドビルダーには、起点の「スラッシュコマンド」ノードとは別に、独立した起点として「エラーハンドラー」ノードがあります。これは、コマンドの実行中にどこかでエラー(例外)が発生したときに動くノードです。

エラー処理を作るには、「エラーハンドラー」ノードの下に動作ノード(メッセージを送信する、変数に記録する、など)をつなぎます。コマンドの途中でエラーが起きると、つないだノード列が実行され、ログを残したり、ユーザーに知らせたり、後始末をしたりできます。

「エラーハンドラー」ノードを見つける

キャンバス上にある「エラーハンドラー」ノードを探します。このノードは起点として最初から用意されています。

エラー時に動かしたいノードをつなぐ

「エラーハンドラー」ノードの下に、エラー発生時に実行したい動作ノードを接続します。例えば「メッセージを送信」を置けば、エラー時にメッセージを表示できます。

「エラーハンドラー」ノードは起点ノードのため、削除・移動はできません。エラー処理を使わない場合は、下に何もつながなくて構いません。

エラー時に使える組み込み変数

エラー処理のノードの中では、発生したエラーの内容を次の組み込み変数で表示できます。テキスト入力欄やメッセージ本文に、中括弧で囲んで書き込むと、その部分が実際のエラー内容に置き換わります。

変数	内容
`{Error.message}`	エラーメッセージ本文
`{Error.detail}`	スタックトレースなどの詳細
`{Error.block}`	エラーが発生したノードのラベル

例えばエラー時に送るメッセージの本文に「エラーが発生しました: {Error.message}」のように書いておくと、実行時にその位置へ実際のエラーメッセージが入ります。

{Error.message} などのエラー変数は、「エラーハンドラー」の直接の子ノード(すぐ下に直接つないだノード)でも参照できます。もちろん、その先につないだノードでも同様に利用できます。

エラーメッセージをプライベート表示にする

「エラーハンドラー」ノードの設定パネルには「エラーメッセージをプライベートメッセージにするか」という選択欄があります。これは、エラーの内容を「コマンドを実行した本人だけに見せるか」を決める設定です。

選択肢	動作
「はい」	コマンドの実行者本人にだけエラーメッセージが表示され、ほかの人には見えません。
「いいえ」	通常のメッセージとして表示されます。

プライベート表示にしても、一部の動作や DM では適用されないことがあります。エラー内容に機密情報が含まれないよう、表示するメッセージにはご注意ください。

次のステップ / 関連ページ

このページでは「スラッシュコマンド」ノードと「エラーハンドラー」ノードの設定を紹介しました。続いて、コマンドに引数(オプション)を追加したり、メッセージ送信や条件分岐などの動作ノードをつなげて、実際のコマンドの流れを組み立てていきましょう。