変数の概要(3種類の使い分け)
BotShade では、Bot に値を「覚えさせる」ための仕組みとして 3 種類の変数 が用意されています。それぞれ「どこまでの範囲で値を共有するか」「いつまで値が残るか」が異なります。最初にこの違いを押さえておくと、後から「値が消えてしまう」「保存したのに使えない」といった迷いがなくなります。
このページでは、まず 3 種類の全体像をつかみ、それぞれをどの画面で作るのかを順番に説明します。
『データストレージ』(永続変数)と『環境変数』は別の機能です。値を保管する目的が違うので混同しないでください。
3 種類の変数とは(早見表)
BotShade の変数は、用途別に次の 3 つに分かれます。
| 種類 | 主な用途 | 値が残る期間 | どこで作る? |
|---|---|---|---|
| 永続変数(ストレージ) | スコア・ポイント・設定値など、何度も使い回す値 | コマンドの実行が終わっても 残り続ける | 左メニューの「データストレージ」 |
| 環境変数 | 他サービスの API キー・トークン・各種 ID を安全に保管する | -(現在開発中のため未定) | 左メニューの「環境変数」 |
| 一時変数 | コマンドの処理中だけ使う計算用・中間結果の値 | そのコマンドの実行が 終わると消える | コマンドビルダーの「変数を設定」ノード |
ひとことでいうと、判断の基準は「その値をどれくらい長く覚えておきたいか」です。
- 実行中の計算で一瞬使うだけ → 一時変数
- 次回のコマンドでも使いたい・サーバーやユーザーごとに記録したい → 永続変数(ストレージ)
- 外部サービスへの接続情報を安全にしまっておきたい → 環境変数(現在開発中)
最初は「永続変数(ストレージ)」と「一時変数」の 2 つだけ覚えれば十分です。環境変数は現在開発中で、まだ追加できません。
永続変数(ストレージ): 値を保持してコマンド実行をまたいで残す
永続変数は、コマンドの実行が終わっても値が残り続ける 変数です。たとえば「コイントスの勝利数」「サーバーのウェルカムメッセージ」「ユーザーごとのポイント」のように、何度も読み書きして使い回す値に向いています。
永続変数は左メニューの「データストレージ」を開いて作成・管理します。
保存される範囲(スコープ)
永続変数を作るときは、その値を「どの範囲で共有するか」を スコープ で選びます。スコープは次の 3 つです。
| スコープ | 共有される範囲 | 使いどころの例 |
|---|---|---|
| グローバル(Global) | Bot 全体で 1 つの値 | Bot 全体の累計実行回数 |
| サーバー毎(Guild) | Discord サーバー単位 | サーバー内のランキング |
| ユーザー毎(User) | Discord ユーザー単位(サーバーをまたいで共通) | 個人の通算成績 |
設定画面のヘルプにも global: Bot 全体 / guild: サーバー単位 / user: Discord ユーザー単位 と表示されます。
「変数」タブと「データ型」タブ
「ストレージ」画面には 2 つのタブがあります。
- 変数: 実際に値を保持する変数を作成・編集します。各変数には「表示名」「リファレンス名」「データタイプ」(値の種類)「スコープ」「デフォルト値」を設定します。
- データ型: 複数のプロパティ(項目)をまとめた、自分専用の「型」を定義できます。たとえば
RPGStatsのような型を作り、その中に複数の項目を持たせる、といった使い方ができます。
詳しい作成手順は 永続変数を作る を参照してください。
「表示名」を入力すると、その内容をもとに「リファレンス名」が自動で BSVAR_ から始まる名前として作られます。リファレンス名は実際にコマンドビルダーなどで使われる変数名で、画面上では編集できないようになっています。
環境変数: API キー・トークン・各種 ID を安全に保管する(※現在開発中)
「環境変数」機能は現在開発中です。画面を開くと「この機能は現在開発中です」というお知らせが表示され、「環境変数を追加」「プリセットから追加」ボタンは無効になっています。下記は提供開始後にできる予定の概要です。
環境変数は、他サービスの API キー・トークン・Discord の各種 ID・URL など を安全に保管しておくための機能です。
提供開始後の予定:
- 変数を一覧で確認し、「変数名で検索」や「タイプ」「並び替え」で絞り込む
- 値の種類(トークン / チャンネル ID / ロール ID / サーバー ID / ユーザー ID / URL / フラグ など)ごとにアイコンで区別する
- 機密情報は「シークレット」として伏せ字で表示し、必要なときだけ表示する
ポイントやスコアのようにコマンドで読み書きする値は永続変数(ストレージ)を、外部サービスへの接続情報は環境変数を使い分けます。
環境変数の画面には「※ 変更は Bot 再起動後に反映されます」という注意書きがあります(提供開始後の挙動の予定)。
一時変数: コマンドビルダーの「変数を設定」ノードで作る
一時変数は、コマンドビルダーの「変数を設定」ノードで作る、そのコマンドの実行中だけ有効な変数 です。計算の途中結果を一時的に置いておきたいときなどに使います。
「変数を設定」ノードの設定画面では、次の項目を入力します。
| 項目 | 内容 |
|---|---|
| 変数名 | 代入先の変数名。後続ノードから参照するときの名前になります |
| 型 | 値の種類。文字列 / 数値 / 真偽値 / ユーザー / チャンネル / ロール / オブジェクト から選びます |
| 値 | 変数に代入する値 |
設定画面には「変数に値を代入します。後続ノードから {変数名} で参照できます。」という案内が表示されます。
コマンドビルダーの『変数を設定』ノードで作った変数は、原則そのコマンドの実行が終わると消えます。値を残したい場合は永続変数(ストレージ)を使ってください。
どこで作る?(ストレージ画面 / 環境変数画面 / コマンドビルダー内)
3 種類の変数は、それぞれ作る場所が違います。
| 作りたいもの | 開く場所 | 操作 |
|---|---|---|
| 永続変数 | 左メニューの「データストレージ」→「ストレージ」画面 | 「変数」タブで「新しい変数を作成」 |
| 自分専用のデータ型 | 同じ「ストレージ」画面 | 「データ型」タブで「データ型を新規作成」 |
| 環境変数 | 左メニューの「環境変数」 | 「環境変数を追加」(現在は開発中でクリックできません) |
| 一時変数 | コマンドビルダー内 | 「変数を設定」ノードを追加して設定 |
左メニュー(サイドバー)には「データストレージ」「環境変数」がそれぞれ別の項目として並んでいます。コマンドビルダーは「コマンドビルダー」から開きます。
値の「寿命」を決める
まず、その値を「実行中だけ使えればよいのか」「次回以降も残したいのか」を決めます。実行中だけなら一時変数、何度も使い回すなら永続変数です。
永続変数を作るときは「データストレージ」を開く
左メニューの「データストレージ」を開き、「ストレージ」画面の「変数」タブで「新しい変数を作成」をクリックします。表示名・データ型・スコープ・デフォルト値を設定して保存します。
コマンド内だけで使うときは「変数を設定」ノードを使う
コマンドビルダーで「変数を設定」ノードを追加し、変数名・型・値を入力します。
接続情報を保管したいときは「環境変数」を開く
他サービスの API キーやトークンを保管したいときは、左メニューの「環境変数」を開きます。ただし現在は開発中のため、追加はまだできません。
{変数名} で参照する基本
作った変数は、コマンドビルダーの入力欄などで {変数名} の形で書くことで、その場所に値が差し込まれます。
- 一時変数: 「変数を設定」ノードで
scoreという変数名を作ったら、後続のノードで{score}と書いて参照します。 - 永続変数: 「ストレージ」で作った変数は、自動で付く「リファレンス名」(
BSVAR_から始まる名前)を使って参照します。たとえばリファレンス名がBSVAR_scoreなら、{BSVAR_score}と書きます。
オブジェクト型の変数の場合は、{変数名.キー名} のように後ろにキー名を付けることで、その中の特定の項目だけを取り出せます。
参照は「中かっこ」で変数名を囲む形です。閉じかっこの付け忘れ({score のように途中で切れる)に注意してください。
よくある勘違い
最後に、つまずきやすいポイントをまとめます。
- 一時変数は実行が終わると消えます。 「変数を設定」ノードで作った値を翌日もう一度コマンドを実行したときに残っていてほしい場合は、永続変数(ストレージ)を使ってください。
- 「データストレージ」と「環境変数」は別物です。 ポイントやスコアのような、コマンドで読み書きする値は「データストレージ」で作ります。外部サービスへの接続情報は「環境変数」(開発中)です。
- 「データ型」を作っただけでは、その型が Bot に値として送られるわけではありません。 「データ型」タブで作るのは、あくまで「項目の組み合わせの定義(ひな形)」です。実際に値を保持させるには、「変数」タブで変数を作り、その変数にこのデータ型を割り当てて使います。
- 永続変数の「表示名」と「リファレンス名」は別物です。 表示名は人が見て分かりやすい名前、リファレンス名(
BSVAR_から始まる名前)は実際にコマンドビルダーで参照するときに使う名前です。参照するときはリファレンス名を使います。