コマンド内での変数の使い方(設定・演算・削除)

コマンドビルダーでは、ユーザーの入力やコマンドの実行結果を「変数」に入れて、あとで使い回すことができます。たとえば「ユーザーが入力した名前」をメッセージに差し込んだり、「コインの勝利数」を 1 ずつ増やして保存したりできます。

このページでは、変数を扱うための 3 つのノード「変数を設定」「変数に演算を適用」「変数を削除」の使い方と、文章の中に変数を埋め込むための書き方({変数名} と ${ … })をまとめて説明します。

まずは変数の書き方を覚える

変数を使うときは、メッセージや入力欄の中に「合言葉」を書いておくと、実行時に実際の値に置き換わります。書き方は次の 2 種類です。

{変数名} で値を差し込む

波かっこ { と } で変数名をはさむと、その変数に入っている値に置き換わります。たとえばメッセージ本文に次のように書くと、

こんにちは {playerName} さん!

実行時には {playerName} の部分が、その変数の値(たとえば「タロウ」)に置き換わります。

${ … } で計算する

足し算や掛け算などの計算をしたいときは、ドルマーク付きの波かっこ ${ … } で式を囲みます。式の中では、変数を {変数名} の形で参照できます。

合計金額は ${ {price} * {quantity} } 円です

この場合、{price}(価格)と {quantity}(個数)を掛け算した結果が表示されます。${ … } の中で使える計算の種類は、後述の計算式の書き方で詳しく説明します。

「変数を設定」ノードで変数を作る

新しく変数を作り、値を入れるには「変数を設定」ノードを使います。このノードを通過した後のノードから、{変数名} で値を参照できるようになります。

オブジェクト型で複数の項目をまとめる

「型」で「オブジェクト (Object)」を選ぶと、1 つの変数の中に複数の項目(プロパティ)を持たせられます。たとえば「プレイヤー」という 1 つの変数の中に「名前」「スコア」「レベル」をまとめて入れる、といった使い方ができます。

オブジェクト型を選ぶと「値」欄の代わりにプロパティの編集画面に切り替わり、プロパティ(例: プロパティ (0/50))を最大 50 件まで追加できます。

オブジェクト型の変数は、後続ノードで {変数名.キー名} の形で参照します。たとえば変数名が player、キー名が name なら {player.name} です。

「変数に演算を適用」ノードで数値を増減する

すでにある変数の値を計算して書き換えたいとき(たとえばカウンターを 1 増やす、ポイントを加算するなど)は「変数に演算を適用」ノードを使います。

このノードは「式を評価して、その結果を対象の変数に入れ直す」動きをします。

計算式の書き方

${ … } 式ブロックや「変数に演算を適用」の「式」の中では、次のような計算ができます。

使える演算子

計算の優先順位は、ふつうの算数と同じです(掛け算・割り算が先、足し算・引き算が後)。順番を変えたいときは丸かっこ ( ) でくくります。

数値の計算

数値どうしは、そのまま四則演算できます。

${ {price} * {quantity} }
${ {count} + 1 }
${ ( {a} + {b} ) / 2 }

文字の連結

+ は、片方が文字(文字列)のときは「つなげる」動きになります。文字をそのまま書くときは、ダブルクォーテーション "…" かシングルクォーテーション '…' で囲みます。

${ {firstName} + " " + {lastName} }

比較する

比較演算子(< > <= >= == !=)は、条件分岐などと組み合わせて使えます。

${ {score} >= 100 }
${ {name} == "admin" }

比較の結果は、小文字の true または false という文字で表示されます(True / False ではありません)。たとえば ${ {score} >= 100 } で score が 120 のときは true が差し込まれます。

配列を式の中で扱う

「配列(array)」型の変数は、式の中で要素を取り出したり、件数を数えたり、つなげたりできます。配列型は「変数を設定」ノードなどで作れる変数の種類の 1 つで、同じ種類の値を順番に並べて持たせるものです(たとえば「参加者の一覧」や「在庫リスト」など)。

式の中では、配列を次のように扱えます。

たとえば参加者の一覧が入った配列 members があるとき、${ length({members}) } で人数を、${ join({members}, ", ") } でカンマ区切りの一覧を差し込めます。

また、+ を使うと配列どうしをつなげて 1 つの配列にまとめられます。

${ {listA} + {listB} }

実際の動作と既定値

ここからは、変数の書き方が実行時にどのように評価されるか(ランタイムの挙動)を説明します。書き方を覚えたあと、思ったとおりの結果にならないときの確認にも役立ちます。

見つからない変数は空文字になる(フェイルオープン)

変数の解決は「フェイルオープン」方式です。つまり、参照した変数が見つからない・式の評価に失敗したといった場合でも、そこでコマンドが止まったりエラー文が出たりはせず、その部分が空文字(何も表示されない)に置き換わってコマンドはそのまま続行します。

• {存在しない変数} のように見つからない変数は、空文字になります。
• ${ … } 式の中で参照した変数が見つからない場合や、計算に失敗した場合は、その式ブロック全体が空文字になります。
• このとき、ユーザーに見えるエラーメッセージは出ません。コマンドは後続のノードへ進みます。

数値は余分な .0 を付けずに表示される

数値の値が整数として表せるとき(5.0 や 42.0 など)は、.0 を付けずに 5・42 と表示されます。小数部があるとき(2.5 など)はそのまま小数で表示されます。これは {変数名} での差し込みでも、${ … } 式の結果でも同じです。

たとえばカウンター変数の中身が 42.0 でも、表示は 42 になります。

割り算は小数になる

割り算 / は小数で結果を返します。${ 5 / 2 } は 2 ではなく 2.5 になります(整数の切り捨てではありません)。0 での割り算や 0 での余り計算(${ 5 / 0 } など)は計算に失敗するため、フェイルオープンによりその式ブロックは空文字になり、コマンドは続行します。

文字列型の変数は数値に変換されない

変数の「型」が「文字列 (string)」のときは、中身が数字に見えても(たとえば 42)、数値としては解釈されません。このため ${ {output} + 100 } で output が文字列型の 42 のときは、足し算ではなく文字の連結になり、結果は 142 ではなく 42100 になります。

これは画面で宣言した「型」を尊重する動きです。数値として計算したいときは、その変数の「型」を「数値 (number)」にしてください。逆に、文字列として扱いたい値が勝手に数値になってしまうのを防ぐ役割もあります。

真偽値(boolean)として扱われる文字

「真偽値 (boolean)」型の変数では、true / yes / on / 1(いずれも小文字)が「はい(真)」として扱われ、それ以外は「いいえ(偽)」になります。

オブジェクト型をそのまま参照したとき

オブジェクト型の変数を {変数名} のように丸ごと参照すると、その中身が JSON 形式の文字列として差し込まれます。特定の項目だけを使いたいときは、{変数名.キー名} のようにプロパティを指定してください。API リクエストの応答など、構造を持った値も同様に、{apiReq_response.status} のようにたどって取り出せます。

配列型を参照したとき

配列型の変数も、{変数名} のように丸ごと参照すると、その中身が JSON 形式の文字列として差し込まれます。一部だけを取り出したいときは、次のように書きます。

• {変数名}[0] — 角かっこに番号を入れて、その位置の要素を取り出します(番号は 0 から始まり、{変数名}[-1] のような負の数で末尾から数えられます)。
• {変数名.length} — 要素の数。
• {変数名.first} — 最初の要素。
• {変数名.last} — 最後の要素。

たとえば参加者の一覧が入った配列なら、{members.length} で人数、{members.first} で先頭の参加者を差し込めます。式の中でのさらに進んだ扱い方は、前述の配列を式の中で扱うを参照してください。

変数の種類と参照のしかた(namespace)

{ … } の中では、用途の違ういくつかの種類の変数を参照できます。いずれも実行時に値へ置き換わります。

• 基本情報: {User.name}・{Guild.name}・{Channel.name}・{Now}(現在時刻)など、コマンドを実行した人やサーバー・チャンネルの情報。
• コマンドの入力(オプション): {option_user.mention} など、ユーザーがコマンド実行時に入力した値。
• 一時変数(ローカル変数): 「変数を設定」ノードなどで作った、その実行中だけ有効な変数。
• 永続変数: {BSVAR_変数名} の形で参照する、実行をまたいで保存される変数。
• ループ変数: ループの中で自動的に作られる進捗用の変数(後述)。

ドット記法で使えるプロパティは決まっている

{User.name} の .name のように、ドット記法で取り出せるプロパティは種類ごとに用意されたものに限られます。たとえばユーザーには name・id・mention・icon・createdAt、ロールには name・id・mention・color・position といった候補があります。

用意されていない項目や、先頭がアンダースコア _ で始まる項目({User._private} など)は参照できず、空文字になります。これは内部の項目を読み出せないようにするための仕組みです。

コマンド入力(オプション)変数のプロパティ

ユーザー・ロール・チャンネルなどを受け取るオプションは、オブジェクトとして扱われます。{option_user} だけだとそのオブジェクト全体、{option_user.mention} のようにプロパティを付けると個別の項目を取り出せます。たとえば {option_user.mention} はそのユーザーへのメンション、{option_role.mention} はロールへのメンションとして表示されます。

ループ変数(進捗の取得)

ループのノードで変数名を決めておくと、ループの中でその進捗を 2 つのプロパティで取り出せます。

• {ループ変数名.index} — 現在が何回目かを表す番号(0 から始まります)。
• {ループ変数名.count} — 繰り返しの合計回数。

たとえば {loopVar.index} / {loopVar.count} 件目 のように書くと、処理の進み具合を表示できます。これらは自動で作られるため、「変数を設定」で上書きすることはできません。

上限とクールダウン

変数を使ったコマンドには、暴走防止のための実行上限が共通で適用されます。現在はベータ版で、本来プレミアムの機能も含めて全ユーザーが無料で利用できます。

また、書き方そのものにも次の制限があります。

• ${ … } 式ブロックの中に、さらに ${ … } を入れることはできません(入れ子の式は不可)。
• {{変数名}} のように波かっこを 2 重にすることはできません(1 段だけ有効)。

永続変数(BSVAR_)の実行時の挙動

永続変数(BSVAR_)は、コマンドの実行をまたいで保存される変数です。実行時の挙動には、いくつか押さえておきたい点があります。

新しい永続変数はストレージでだけ作れる

「変数を設定」ノードでは、新しい永続変数を作ることはできません。永続変数は必ず先にストレージで作っておく必要があり、コマンドの中の「変数を設定」「変数に演算を適用」「変数を削除」でできるのは、すでにストレージにある永続変数の値を更新・リセットすることだけです。ストレージに登録されていない BSVAR_ 名を指定しても、その操作は何も起こりません。

スコープと、DM での書き込み

永続変数には「全体・サーバー・ユーザー」などのスコープ(値が共有される範囲)があります。スコープの考え方は永続変数で詳しく説明しています。

サーバー単位(guild / guild_user)のスコープを持つ永続変数を、DM(ダイレクトメッセージ)で実行したコマンドから更新しようとすると、サーバーが特定できないため、その書き込みは行われません(エラー表示はなく、静かにスキップされます)。このとき値の読み取り自体はできるため、{BSVAR_変数名} での参照は以前の値のまま表示され、コマンドは続行します。サーバー内で実行したコマンドからは通常どおり更新できます。

表示されるメッセージ

変数を使ったコマンドの実行で問題が起きたとき、ユーザーに表示される主なメッセージは次のとおりです。いずれも、変数の置き換えに失敗しただけでは出ません(その場合は空文字になり、コマンドは続行します)。

ステップ数の上限を超えたときは、上の警告が 1 回表示され、残りのノードはスキップされます。

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

• 変数を差し込んだ場所が空になる: つづり間違い・参照する順番(「変数を設定」より前で参照していないか)・式の中の型の不一致が原因のことが多いです。エラーは出ないため、表示の抜けで気づく必要があります。
• 計算結果が想定とずれる(例: 142 のはずが 42100): 計算に使う変数が「文字列 (string)」型のままだと、+ が連結として働きます。数値計算をしたい変数は「型」を「数値 (number)」にしてください。
• 種類の違う値を比べると結果が出ない: 数値どうし・文字どうしのように、同じ種類の値で比べてください。種類が混ざると比較結果が得られず、空文字になります。
• DM で永続変数が保存されない: サーバー単位スコープの永続変数は DM では書き込めません。前述の「スコープと、DM での書き込み」を確認してください。
• 0 で割っている: ${ … / 0 } は計算に失敗してその式が空になります。割る数が 0 にならないようにしてください。

「変数を削除」ノードで永続変数をリセットする

「変数を削除」ノードは、永続変数(後述のストレージで作った変数)の値を空(初期値)に戻すためのノードです。ローカル変数はコマンド終了で自動的に破棄されるため対象外です。

このノードを実行すると、対象の永続変数は、ストレージで設定された初期値(デフォルト値)に戻ります。

一時変数と永続変数の違い

BotShade の変数には、大きく分けて 2 種類あります。仕組みも使い方も違うので、混同しないように注意してください。

一時変数(ローカル変数)

「変数を設定」ノードで作る変数や、ユーザーがコマンドに入力した値などは、すべて一時変数です。これらはそのコマンドが 1 回実行されている間だけ存在し、実行が終わると消えてしまいます。「今回の実行だけで使う計算用の値」に向いています。

永続変数(カスタム変数・BSVAR_)

一方、「ユーザーのコイントス勝敗」「サーバーの累計ポイント」のように、コマンドを実行し終わっても残しておきたい値は、永続変数を使います。永続変数はストレージの画面であらかじめ作っておく必要があり、その実際の名前は必ず BSVAR_ で始まります。

コマンドビルダーの中で永続変数を扱うときは、この BSVAR_ 付きの名前を使います。

• メッセージなどで参照するとき: {BSVAR_変数名}
• 「変数に演算を適用」「変数を削除」の「対象変数名」に入れるとき: BSVAR_変数名(波かっこなし)

ストレージに登録されていない BSVAR_ 名を「変数を設定」「変数に演算を適用」「変数を削除」で使っても、その操作は実行されません(前述の新しい永続変数はストレージでだけ作れる)。

たとえば「コインの勝利数」を増やすには、ストレージで BSVAR_coinflip_win_count を作っておき、「変数に演算を適用」ノードで対象変数名に BSVAR_coinflip_win_count、式に {BSVAR_coinflip_win_count} + 1 と入力します。リセットしたいときは「変数を削除」ノードに BSVAR_coinflip_win_count を入力すると、ストレージで決めた初期値に戻ります。

ノードタイトルの変更

「変数を設定」「変数に演算を適用」「変数を削除」のいずれのノードでも、設定パネルの一番下に「ノードタイトル」欄があります。ここに名前を入力すると、コマンドビルダー上でのそのノードの表示名を、わかりやすい名前に変更できます。

たとえば「変数に演算を適用」ノードに「勝利数を +1」のようなタイトルを付けておくと、コマンドの流れを見たときに何をするノードなのか一目でわかります。タイトルはあくまで表示用なので、変数の動き自体には影響しません。

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

• ストレージ — 永続変数(BSVAR_)を作成・管理する画面です。
• 永続変数 — BSVAR_ 変数とスコープ(全体・サーバー・ユーザー)の考え方をくわしく説明します。
• Bot の作成 — コマンドビルダーを開くための Bot 管理の入口です。