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

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

このページでは、永続変数とは何か、値を共有する範囲を決める「スコープ」、そしてコマンドの中での参照のしかたを、操作のイメージとあわせて説明します。変数を実際に作成・編集・削除するのはストレージ画面で、その細かい操作はそちらのページで解説しています。

永続変数とは

BotShade の変数には、大きく分けて 2 つの種類があります。

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

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

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

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

たとえば「表示名」に スコア と入れると、「リファレンス名」は BSVAR_score のように自動生成されます。この BSVAR_ という頭の文字が、「これは保存され続ける永続変数です」という目印になっています。

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

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

イメージしやすいように、同じ「スコア」という変数で考えてみます。

• 「グローバル(Global)」にすると、誰がどのサーバーで使っても、同じ 1 つのスコアを共有します。
• 「サーバー毎(Guild)」にすると、サーバー A のスコアとサーバー B のスコアは別々に記録されます。
• 「ユーザー毎(User)」にすると、ユーザーごとに自分専用のスコアを持ち、別のサーバーで使っても同じ自分の値が引き継がれます。

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

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

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

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

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

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

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

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

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

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

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

永続変数を作成する

永続変数の実体は、すべてストレージ画面で作成します。ここでは流れの概要だけ紹介します。

作成済みの変数を編集するには一覧の鉛筆アイコンをクリックし、削除するには編集画面の左下にあるゴミ箱アイコンをクリックします。これらの操作の詳細はストレージで説明しています。

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

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

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

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

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

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

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

実際の動作と既定値

ここでは、コマンドの実行中に永続変数がどのように読み書きされるか、実際の挙動と初期値の決まり方をまとめます。

値の読み取り(参照)

メッセージや式の中で {BSVAR_score} のように書くと、Bot はその時点の値を探して文字に置き換えます。値の決まり方は次の順序です。

参照に使った名前(リファレンス名)に対応する変数が見つからない場合は、置き換えが行われず、{BSVAR_score} のような文字がそのままメッセージに表示されます(対処は「注意点・うまくいかないとき」を参照)。

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

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

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

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

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

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

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

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

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

一時変数(BSVAR_ なし)との違い

BSVAR_ が付いていない名前をコマンドビルダーで使うと、その値はそのコマンドの実行中だけ保持され、コマンドが終わると消えます。データベースには保存されないため、次にコマンドが実行されたときには残っていません。計算の途中結果やその場限りのメモにはこれで十分ですが、ポイントや勝敗のように覚えておきたい値には必ず BSVAR_ 付きの永続変数を使ってください。

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

複数のコマンドが同時に同じ永続変数を計算で書き換えても(たとえば多くのユーザーが同時にポイントを加算しても)、計算は順番に処理され、更新が打ち消し合うことはありません。{BSVAR_count} + 1 のような加算が同時にたくさん走っても、最終的な合計は正しく積み上がります。

表示されるメッセージ

永続変数の読み書きそのものについて、Bot が Discord 上に専用のメッセージを出すことは基本的にありません。値の参照は静かにメッセージへ反映され、書き込みも画面上には特別な通知なく行われます。

ただし、変数の保存に失敗するなどコマンドの実行自体がエラーになった場合は、次の一般的なメッセージが表示されます。

コマンドの実行中にエラーが発生しました。

このメッセージが出たときは、しばらく待って再度コマンドを実行すると解消することがあります。

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

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

コマンドの中で使える操作(ノード)

コマンドビルダーでは、永続変数に対して次の操作(ノード)が使えます。式やノードの詳しい書き方はコマンド内での変数の使い方をご覧ください。

反映のタイミング

新しく作った変数をコマンドの中で参照しても値が出てこないときは、まず変数を保存できているか(「全変数一覧」に表示されているか)を確認してください。それでも反映されない場合は、コマンドを保存し直すか Bot を再起動すると確実に反映されます。

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

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