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

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

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

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

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

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

こんにちは {playerName} さん!

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

変数名の前後の空白は、自動的に取り除かれます。

${ … } で計算する

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

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

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

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

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

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

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

オブジェクト型を選ぶと、単一の「値」欄の代わりにプロパティの編集画面に切り替わります。

オブジェクト型の変数は、後続ノードで {変数名.キー名} の形で参照します。たとえば変数名が 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)」型の変数は、式の中で次のように扱えます。

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

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

${ {listA} + {listB} }

実際の動作と既定値

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

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

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

差し込んだはずの場所が空になっているときは、変数名のつづり間違い、参照する順番(「変数を設定」ノードより前で参照している)、式の中の型の不一致のいずれかであることが多いです。

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

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

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

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

数値として計算したい変数は「型」を「数値 (number)」にしてください。数値型への変換に失敗した場合の既定値は 0 です。真偽値は計算の中では true が 1、false が 0 として扱われます。

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

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

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

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

配列型を参照したとき

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

• {変数名}[0] — その位置の要素(番号は 0 から始まり、{変数名}[-1] で末尾から数えます)。
• {変数名.length} — 要素の数。
• {変数名.first} — 最初の要素。
• {変数名.last} — 最後の要素。

式の中での扱い方は配列を式の中で扱うを参照してください。

変数の種類と参照のしかた(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_変数名} での参照は以前の値のまま表示され、コマンドは続行します。サーバー内で実行したコマンドからは通常どおり更新できます。DM でも動くコマンドで使う場合は、ユーザー単位(user)や全体(global)のスコープを選んでおくと、DM からの更新も保存されます。

表示されるメッセージ

実行中に問題が起きると、ユーザーには次のメッセージが表示されます。

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

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

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

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

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

永続変数の実際の名前は必ず BSVAR_ で始まります。メッセージなどで参照するときは {BSVAR_変数名}、「変数に演算を適用」「変数を削除」の「対象変数名」に入れるときは BSVAR_変数名(波かっこなし)を使います。

ノードタイトルの変更

「変数を設定」「変数に演算を適用」「変数を削除」のいずれも、設定パネルの一番下にある「ノードタイトル」欄で、コマンドビルダー上の表示名(例: 「勝利数を +1」)に変更できます。

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

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