永続変数(ストレージ)を作る

永続変数(えいぞくへんすう)は、コマンドの実行が終わっても値が消えずに保存され続ける変数です。「ユーザーごとの所持ポイント」「サーバーごとの累計メッセージ数」「コイントスの通算勝敗」のように、Bot に長く覚えておいてほしいデータはすべて永続変数で扱います。

変数を実際に作成・編集・削除するのはストレージ画面です。

永続変数とは

永続変数はストレージ画面の「変数」タブで作成します。作成した変数は Bot のデータベースに記録され、ユーザーが何度コマンドを実行しても値が引き継がれます。

一方、コマンドの実行中だけ使う一時変数は、ストレージ画面で作らなくてもコマンドビルダーの中で自由に使えます。詳しくは一時変数をご覧ください。

リファレンス名(BSVAR_)と表示名

永続変数には、2 つの「名前」があります。ストレージ画面で変数を作るとき、人が読むための「表示名」を入力すると、それをもとに BSVAR_ で始まる「リファレンス名」が自動で作られます。

「リファレンス名」は表示名から自動生成され、直接編集できません。頭に付く BSVAR_ が、「これは保存され続ける永続変数です」という目印になっています。

スコープ — 値を共有する範囲を決める

永続変数を作るとき、いちばん大切な設定が「スコープ」です。スコープは、その変数の値をどの範囲で共有して覚えておくかを決めるもので、次の 3 つから選びます。

データタイプ — 保存する値の種類

スコープと並んで、変数を作るときに選ぶのが「データタイプ」です。これは、その変数にどんな種類の値を入れるかを表します。データタイプには次の種類があります。

「データタイプ」を選ぶと、その下の「デフォルト値」(初期値)の入力欄が、選んだ型に合わせて変わります。たとえば「数値(Number)」なら数字専用の入力欄に、「真偽値(Boolean)」なら true / false を選ぶ欄になります。デフォルト値は、まだ一度も値が書き込まれていないときに使われる最初の値です(入力は任意です)。

データタイプを指定しなかった場合や、想定外の値が入った場合は、自動的に「文字列(String)」として扱われます。

オブジェクト型のプロパティ

「オブジェクト(Object)」型は、複数の項目をひとまとめにして保存できる型です。たとえば「プロフィール」という 1 つの変数の中に、「名前」「レベル」「称号」といった項目をまとめて持たせられます。

オブジェクト型では「プロパティ」を定義し、「プロパティ追加」で項目を 1 つずつ追加して、それぞれに「キー名」(項目の名前)・「型」・「初期値」を設定します。1 つのオブジェクト型変数に追加できるプロパティは最大 50 個までです。

同じキー名のプロパティを 2 つ作ると、後から定義したほうの値で上書きされ、エラーにはなりません。キー名はそれぞれ重複しないように付けてください。

よく使う項目の組み合わせは、別途「データ型」として登録しておくと、オブジェクト型の変数を作るときに再利用できます。データ型の詳しい作り方はデータ型をご覧ください。

ユーザー型・チャンネル型で指定する「ごとのデータタイプ」

「ユーザー(User)」型または「チャンネル(Channel)」型を選んだときは、追加で「ユーザー/チャンネルごとのデータタイプ」を指定します。これは「各ユーザー(またはチャンネル)に、どんな種類のデータをひもづけて保存するか」を決める設定です。文字列・数値・オブジェクトなどのほか、自分で作ったデータ型も選べます。

永続変数を作成する

永続変数の実体は、すべてストレージ画面の「変数」タブで作成します。「表示名」を入力し、「データタイプ」と「スコープ」を選び、必要に応じて「デフォルト値」やオブジェクト型の「プロパティ」を設定して保存します。保存した変数は「全変数一覧」に追加されます。作成・編集・削除の画面操作はストレージで説明しています。

コマンドの中で永続変数を使う

作成した永続変数は、コマンドビルダーで組み立てるコマンドやイベントの中から参照できます。参照するときは、ストレージ画面で自動生成された「リファレンス名」(BSVAR_ で始まる名前)を、中括弧で囲って書きます。

たとえば「リファレンス名」が BSVAR_score の変数なら、メッセージや式の中で次のように書くと、その時点の値に置き換わります。

あなたの現在のスコアは {BSVAR_score} です。

表示名(例: スコア)をそのまま中括弧で囲っても、永続変数としては認識されません。オブジェクト型の変数では、{BSVAR_profile.level} のように .(ドット)でプロパティ名をつなげて、中の項目を個別に参照できます。

値を読み取るだけでなく、コマンドビルダーのノードを使って値を書き換えることもできます。

• 値を上書きして保存する(代入)
• {BSVAR_score} + 1 のように、今の値をもとに計算して保存する(加算など)
• 値を初期値に戻す(削除・リセット)

これらの具体的なノードの選び方や式の書き方は、コマンド内での変数の使い方で詳しく解説しています。

実際の動作と既定値

値の読み取り(参照)

そのスコープ(全体 / サーバー / ユーザー)で過去に値が書き込まれていればその保存値が使われ、まだ一度も書き込まれていなければストレージ画面で設定した「デフォルト値」が使われます。

参照に使った名前(リファレンス名)に対応する変数が見つからない場合は、置き換えが行われず、{BSVAR_score} のような文字がそのままメッセージに表示されます。ストレージ画面で変数を作成しているか、リファレンス名のつづりが合っているかを確認してください。なお、ストレージ画面で作成していない BSVAR_ 付きの名前に書き込もうとしても、エラーは表示されず保存も行われません。

値の書き込み(代入・計算・リセット)

コマンドビルダーのノードで永続変数を書き換えると、次のように動きます。

• 代入(上書き): 指定した値で変数を上書きし、保存します。次回以降のコマンド実行でも、その新しい値が引き継がれます。
• 計算(加算など): {BSVAR_score} + 1 のように今の値をもとに計算し、結果を保存します。今の値がまだ書き込まれておらずデフォルト値も未設定の場合は、数値なら 0、真偽値なら false、文字列なら空文字から計算を始めるので、{BSVAR_count} + 1 のような書き方が初回でも崩れません。
• 削除(リセット): 保存していた値を取り消し、その変数をデフォルト値に戻します。同じコマンドの後続のノードでも、以降は初期値として扱われ、次回以降の実行でも(再び書き込むまでは)デフォルト値のままになります。

デフォルト値を設定していない変数を「削除(リセット)」すると、戻る先の値が無いため、その後の参照では値が空のまま(None と表示される場合があります)になります。リセットして使う変数には、デフォルト値を設定しておくことをおすすめします。

入力された値の扱い(型ごとの自動変換)

変数に書き込む値は、変数のデータタイプに合わせて自動で整えられます。

• 真偽値(Boolean): true / yes / on / 1 のいずれか(大文字・小文字は区別しません)を書き込むと「はい(true)」になります。それ以外の値(空文字を含む)はすべて「いいえ(false)」になります。
• 数値(Number): 数字として読み取れない値(たとえば abc)を書き込もうとすると、エラーにはならず 0 として保存されます。意図しない 0 を避けるため、数値型の変数には数字だけを渡すようにしてください。

Discord の対象を指す変数(ユーザー・チャンネルなど)

「ユーザー(User)」「チャンネル(Channel)」「ロール(Role)」「サーバー(Guild)」型の変数は、対象そのものへの参照として保存されます。コマンドの中では、メンション(<@123...> のような形)や名前を取り出して表示できます。

参照先の対象がすでに見つからなくなっている場合(ユーザーがサーバーを抜けた、チャンネルやロールが削除されたなど)でも、メンションや ID は引き続き利用できますが、名前を取り出そうとすると 不明 と表示されます。

上限と同時アクセス時の挙動

複数のコマンドが同時に同じ永続変数を計算で書き換えても(たとえば多くのユーザーが同時にポイントを加算しても)、計算は順番に処理され、更新が打ち消し合うことはありません。

注意点・うまくいかないとき

• 数値が意図せず 0 になる: 数値型の変数に、数字として読めない値を書き込んだ可能性があります。渡している値が数字になっているか確認してください。
• 対象の名前が 不明 と表示される: ユーザー・チャンネル・ロール・サーバーを指す変数で、参照先がすでに削除・退出済みのときに起こります。メンションや ID は引き続き使えます。
• 一時的に古い値や初期値が表示される: ごくまれに値の取得が遅れると、その場ではデフォルト値で動作し、多くの場合は次回の実行で本来の値に戻ります。

反映のタイミング

新しく作った変数がコマンドの中で反映されないときは、コマンドを保存し直すか Bot を再起動すると確実に反映されます。

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

• ストレージ — 変数を実際に作成・編集・削除する画面の詳しい操作
• 変数の概要 — BotShade の変数全体の考え方
• 一時変数 — コマンド実行中だけ使う変数
• データ型 — オブジェクト型で使う独自データ型の作り方
• コマンド内での変数の使い方 — 式やノードでの永続変数の書き方
• コマンドビルダーの概要と使い方 — コマンドの組み立て方