BotShadeコマンドの基本設定(名前・クールダウン・権限・エラー処理)
コマンドビルダーの起点となるノード「スラッシュコマンド」では、Discord 上でのコマンド名や説明、クールダウン、誰がそのコマンドを使えるかといった「コマンド全体の基本設定」をまとめて行います。コマンドの実行中にエラーが起きたときの動きは「エラーハンドラー」ノードで決めます。
スラッシュコマンドノードの設定一覧
キャンバス上の「スラッシュコマンド」ノードはコマンドに必ず1つだけ存在し、削除や移動はできません。このノードをクリックすると設定パネルが開き、次の項目を設定できます。
| 設定項目 | 入力方法 | 内容 |
|---|---|---|
| 「コマンド名」 | テキスト入力 | Discord 上に表示されるコマンドの名前。必須です。半角英数字とハイフン・アンダースコア・ピリオド(- _ .)で 3〜50 文字。日本語やスペースは使えず、条件を満たしていないと保存時にエラーになります。グループ配下のコマンドでは、入力欄の左に編集できない /親 子 のプレフィックスが表示され、その下に Discord 上のフルコマンドが出ます。 |
| 「コマンドの説明」 | テキスト入力 | Discord 上に表示されるコマンドの説明文。任意です。 |
| 「コマンドクールダウン」 | 選択(あり/なし) | 連続実行を制限するかどうか。 |
| 「クールダウン期間」 | テキスト入力 | クールダウンの長さ(数値)。クールダウンありのときだけ表示されます。 |
| 「クールダウン単位」 | 選択(秒/分/時間) | クールダウン期間の単位。クールダウンありのときだけ表示されます。 |
| 「個別権限設定を有効化」 | オン/オフのスイッチ | BotShade 独自の権限設定を使うかどうか。 |
| 「Discord権限より個別設定を優先」 | オン/オフのスイッチ | Discord の権限判定をバイパスする危険な設定。 |
| 「永続パネルのボタンにも権限を適用する」 | オン/オフのスイッチ | 永続化したメッセージのボタン・選択メニューにコマンドの権限を適用するか。 |
| 「親グループの権限を継承しない」 | オン/オフのスイッチ | グループ配下のコマンドにだけ表示されます。 |
既存のコマンドの名前を変更して保存すると、新しい名前に置き換わります(以前の名前のコマンドは残りません)。
コマンドクールダウン(あり/なし・期間・単位)
クールダウンは、同じコマンドが短時間に何度も実行されるのを防ぐための設定です。「コマンドクールダウン」の選択欄で次のどちらかを選びます。
| 選択肢 | 動作 |
|---|---|
| 「クールダウンなし」 | クールダウンを設けません(初期状態)。 |
| 「クールダウンあり」 | 一定時間あけないと同じコマンドを再実行できなくします。 |
例えば「クールダウン期間」に 30、「クールダウン単位」に「秒」を設定すると、コマンドを使ったあと 30 秒間は同じ人が再実行できなくなります。
クールダウンは実行者ごとに適用されるため、あるユーザーがクールダウン中でも別のユーザーは実行できます。ボタン・選択メニュー・モーダルには適用されません。
権限設定 — 個別権限設定の有効化
「権限設定」という見出しの下では、そのコマンドを「誰が使えるか」を細かく制御できます。中心となるのが「個別権限設定を有効化」のスイッチです。
| スイッチの状態 | 権限の判定方法 |
|---|---|
| オフ(初期状態) | 通常の Discord の権限判定を使います。 |
| オン | BotShade 独自の権限設定(ホワイトリスト/ブラックリストなど)を使います。 |
ロール・権限のホワイトリスト/ブラックリスト
「個別権限設定を有効化」をオンにすると表示される「詳細権限設定」パネルには、次の6つのリストがあります。許可(ホワイト)と拒否(ブラック)を、ロール単位・ユーザー単位・権限単位で指定できます。
| リスト | 役割 |
|---|---|
| 「ホワイトロールリスト」 | 指定したロールには常にアクセスを許可します。 |
| 「ブラックロールリスト」 | 指定したロールのアクセスは常に拒否します。 |
| 「ホワイトユーザーリスト」 | 指定したユーザーには常にアクセスを許可します。ロールより優先されます。 |
| 「ブラックユーザーリスト」 | 指定したユーザーのアクセスは常に拒否します。ロールより優先されます。 |
| 「ホワイト権限リスト」 | 許可する権限条件を設定します。条件に一致するメンバーはアクセスが許可されます。 |
| 「ブラック権限リスト」 | 拒否する権限条件を設定します。条件に一致するメンバーはアクセスが拒否されます。 |
ユーザーリストは、サーバーを選んでからメンバーを検索して追加します(ID の直接入力にも対応しています)。1 本のユーザーリストに登録できるのは最大 25 件です。ロールリストに件数の上限はありません。ユーザーリストが無かった時代に保存したコマンドは、空のリストとして扱われるため挙動は変わりません。
判定の順序
複数のリストに当てはまるときは、次の順に判定され、最初に当てはまったところで結果が決まります。
管理者バイパス → ブラックユーザーリスト → ブラックロールリスト → ブラック権限リスト → ホワイトユーザーリスト → ホワイトロールリスト → ホワイト権限リスト → 既定
拒否が許可に優先し、同じ色のリストの中ではユーザー指定がロール指定より先に見られます。
権限リストの編集(条件の追加)
「ホワイト権限リスト」「ブラック権限リスト」では「条件を追加」ボタンで条件を1つずつ追加します。各条件(「条件 #1」のように番号が付きます)では、まず判定の仕方を選び、続いてチェックしたい Discord 権限にチェックを入れていきます。
判定の仕方(モード)は次の4種類から選びます。
| モード | 意味 |
|---|---|
| 「AND (すべて必要)」 | 選んだ権限をすべて持っている場合に一致します。 |
| 「OR (いずれか1つ)」 | 選んだ権限のいずれか1つを持っていれば一致します。 |
| 「STRICT (完全一致)」 | 選んだ権限と完全に一致する場合に一致します。 |
| 「CONTAINS (含む)」 | 選んだ権限を含んでいる場合に一致します。 |
チェックを入れた権限が条件の対象になり、権限ごとに「許可」と「拒否」を切り替えられます。権限の項目には「管理者」「メンバーをキック」「メンバーをBan」「メッセージの管理」「ロールの管理」など、Discord の各権限が日本語で並んでいます。
各リストは組み合わせて使えます。リストを空のままにすると、そのリストによる絞り込みは行われません。
Discord権限より個別設定を優先(危険な上書き設定)
「Discord権限より個別設定を優先」は、Discord 側の権限チェックを無視して、上で設定した個別の権限設定だけで判定させる上書き設定です。「個別権限設定を有効化」がオフのあいだは操作できず、オフに戻すとこの優先設定も自動的にオフになります。
「Discord権限より個別設定を優先」をオンにすると Discord の権限チェックが回避され、意図しない人がコマンドを使えてしまう恐れがあります。通常はオフのままにしてください。
永続パネルのボタンにも権限を適用する
永続化した「メッセージを送信」ブロックが付けたボタンや選択メニューは、押されるたびにそのコマンドの権限が再評価されます。「永続パネルのボタンにも権限を適用する」をオフにすると、この再評価を行わず、誰でも操作できるようになります。/rules のように「発行できる人は絞りたいが、貼ったパネルは全員に使わせたい」公開パネル向けの設定です。コマンド自体の実行権限は変わりません。
- 既定はオンです。
- コマンド本体にも関数にも永続化した「メッセージを送信」ブロックが 1 つも無いときは操作できません。
- オフにしても外れるのは、そのコマンドの権限の再評価だけです。親グループの権限は引き続き適用され、参照先のグループが壊れている場合は常に拒否されます。
- 一時的なパネル(永続化していないメッセージ)のボタンは、この設定の対象外です。
親グループの権限を継承しない
グループに入れたコマンドは、既定では親グループの権限で先に絞り込まれてから、そのコマンド自身の権限で判定されます。「親グループの権限を継承しない」をオンにすると、親グループの権限を無視し、そのコマンド単体の権限だけで判定します。
エラーハンドラーとは — 実行中のエラーを捕捉して処理する
コマンドビルダーには、起点の「スラッシュコマンド」ノードとは別に、独立した起点として「エラーハンドラー」ノードがあります。これは、コマンドの実行中にどこかでエラー(例外)が発生したときに動くノードです。
エラー処理を作るには、「エラーハンドラー」ノードの下に動作ノード(メッセージを送信する、変数に記録する、など)をつなぎます。コマンドの途中でエラーが起きると、つないだノード列が実行され、ログを残したり、ユーザーに知らせたり、後始末をしたりできます。
このノードも起点ノードのため、削除・移動はできません。エラー処理を使わない場合は、下に何もつながなくて構いません。
エラー時に使える組み込み変数
エラー処理のノードの中では、発生したエラーの内容を次の組み込み変数で表示できます。テキスト入力欄やメッセージ本文に、中括弧で囲んで書き込むと、その部分が実際のエラー内容に置き換わります。
| 変数 | 内容 |
|---|---|
{Error.message} | エラーメッセージ本文 |
{Error.detail} | エラーの詳細(スタックトレースなど) |
{Error.block} | エラーが発生したブロックのラベル(未設定ならブロックの種類) |
{Error.type} | エラーの種別(下表) |
{Error.message} と {Error.detail} は、環境変数の値などの秘密を取り除いたうえで 500 文字に切り詰められます。
エラーの種別 {Error.type}
「比較による条件分岐」ブロックの基準値に {Error.type} を入れると、種別ごとに処理を振り分けられます。
| キー | 意味 |
|---|---|
undefined_variable | 未定義の変数を参照 |
undefined_function | 存在しない関数を呼んだ |
invalid_argument | 引数が不足 / 型が違う |
execution_limit | 呼出深度 / 総呼出数の上限 |
api_request | 外部 API 呼び出しの失敗 |
discord_api | Discord API 側の失敗 |
expression | ${ ... } 式の評価失敗 |
timeout | 実行タイムアウト |
function | 上記以外の関数実行の失敗 |
unknown | 種別を特定できない |
構文エラーは保存前の検証で弾かれるため、実行時には出ません。また、未定義変数エラーとタイムアウトはエラーハンドラーには流れません(未定義変数は実行を止めず該当箇所がそのまま出力され、タイムアウトはエンジンごと打ち切られるためです)。
エラーハンドラーには本体とは別の実行時間が与えられるため、本体が実行時間を使い切ってもエラー処理は動きます。
エラーメッセージをプライベート表示にする
「エラーハンドラー」ノードの設定パネルには「エラーメッセージをプライベートメッセージにするか」という選択欄があります。これは、エラーの内容を「コマンドを実行した本人だけに見せるか」を決める設定です。
| 選択肢 | 動作 |
|---|---|
| 「はい」 | コマンドの実行者本人にだけエラーメッセージが表示され、ほかの人には見えません。 |
| 「いいえ」 | 通常のメッセージとして表示されます。 |
プライベート表示にしても、一部の動作や DM では適用されないことがあります。エラー内容に機密情報が含まれないよう、表示するメッセージにはご注意ください。
Config(設定可能パラメータ)
コマンドの基本設定パネルには、起点ノードの一般設定に続いて「Config (設定可能パラメータ)」セクションがあります。これはコマンドの作り手と、サーバーごとに値だけを差し替える運用者を分けて考えるためのしくみで、次の 2 段階で使います。
- コマンドを作るときに、「外から差し替えたい設定」を 宣言 する(キーと型を決める)。
- 宣言した設定の 現在の値 を、同じ画面の下にある「現在の値 (Configure)」フォームから埋める。
宣言したパラメータは、永続変数(BSVAR_…)のカタログに自動で展開されるため、コマンド本体のノードからは {BSVAR_<キー名>} の形で値を取り出せます。
Config フィールドを宣言する
「フィールド追加」ボタンで、宣言を 1 件ずつ増やします。各フィールドには次を設定します。
| 設定項目 | 内容 |
|---|---|
「キー (prefix: BSVAR_)」 | キー名の 末尾部分 だけを入力します。先頭の BSVAR_ は自動で付きます(例: welcome_channel → 実際のキーは BSVAR_welcome_channel)。 |
| 「型」 | 値の種類。「文字列 (string)」「数値 (number)」「真偽値 (boolean)」「URL」「チャンネル (channel)」「ロール (role)」「ユーザー (user)」「絵文字 (emoji)」から選びます。 |
| 「表示ラベル」 | この設定を「現在の値 (Configure)」フォームに表示するときの名前です。 |
| 「説明 (任意)」 | 「現在の値 (Configure)」フォームでのヘルプテキストです。 |
| 「必須項目」 | オンにすると、値が空のときにコマンド一覧で「設定未完了」の目印が付きます。 |
キー名のルールに合わないとき、または同じキーを 2 か所で宣言したときは警告が表示されます(例: 「キー 'BSVAR_xxx' が他のフィールドと重複しています」)。不要になったフィールドは削除できます。
現在の値 (Configure) を埋める
Config フィールドを 1 つでも宣言すると、その下に「現在の値 (Configure)」フォームが現れ、宣言した各キーの値を入力できます。「値を保存」を押すと、宣言したフィールドに対応する 永続変数の既定値 がまとめて更新されます(値が変わっていないとボタンは押せません)。
たとえば welcome_channel を宣言しておけば、メッセージ送信ノードの「送信先チャンネル」に {BSVAR_welcome_channel} と書くだけで、Configure で埋めた値が使われます。
次のステップ / 関連ページ
- コマンドビルダーの基本
- 変数と式の使い方 —
{BSVAR_…}の参照のしかた - コマンド内関数(サブルーチン) — 同じコマンド内で処理を関数として切り出す
- ストレージ・変数
最終更新: