Skip to Content
コマンドビルダー変数と式の使い方

変数と式の使い方

コマンドの中で値を一時的に覚えさせたり、覚えた値を後から差し込んだり、簡単な計算をしたりする仕組みが「変数」です。たとえば「ユーザーが入力した名前」「サイコロの出目」「コイントスの勝った回数」などを変数に入れておけば、メッセージの中で {変数名} と書くだけでその値を呼び出せます。

このページでは、変数の基本から、計算式の書き方、サーバーやユーザーごとに値を保存できる「カスタム変数」までを、画面の操作に沿って説明します。

このページの操作はすべてコマンドビルダーの画面で行います。コマンドビルダーの基本的な使い方をまだ知らない場合は、先にそちらをご覧ください。

変数とは — 値を覚えて後から使い回す仕組み

変数は「名前の付いた箱」のようなものです。箱に値を入れておくと、あとからその名前を書くだけで中身を取り出せます。

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

種類いつ消えるか主な使いどころ
一時的な変数(ローカル変数)コマンドの実行が終わると自動的に消える1 回のコマンド処理の中だけで使う計算結果や入力値
カスタム変数(永続変数)自分で削除するまで残る(データベースに保存される)サーバーやユーザーごとの累計スコア・設定など

まずは「一時的な変数」を中心に説明し、後半で「カスタム変数」を扱います。

変数の埋め込み {変数名} と計算式 ${...}

テキストを入力する欄(メッセージ本文など)には、2 種類の書き方を埋め込めます。

書き方例役割
{変数名}{User.name}、{option_名前}1 つの値をそのまま差し込む
${ ... }${ {price} * 1.1 }、${ {a} + {b} }計算した結果を差し込む

値をそのまま差し込む {変数名}

中括弧で変数名を囲むと、その変数の値に置き換わります。

  • 例: こんにちは、{User.name} さん! → こんにちは、たろう さん!
  • ドットでつなぐと、変数が持つ細かい情報(プロパティ)を取り出せます。例: {User.id}、{User.mention}

中括弧の二重ネスト({{変数名}} のような書き方)はできません。1 組の中括弧で 1 つの変数を参照します。

計算した結果を差し込む ${ ... }

計算をしたいときは、${ と } で式を囲みます。式の中では {変数名} を使って変数の値を取り込めます。

  • 例: ${ {price} * 1.1 } → price に 1.1 を掛けた結果
  • 例: ${ {a} + {b} } → a と b を足した結果

式の中で使える演算子:

種類演算子説明
計算(算術)+ - * / %足す・引く・掛ける・割る・余り
比較< > <= >= == !=大小や一致を判定し、true / false を返す
連結+どちらかが文字列のとき、+ は文字をつなげる

割り算は整数だけにならず、小数まで計算されます(例: 5 / 2 は 2.5)。また + は、両方が数値なら足し算、どちらかが文字列なら文字の連結になります(例: ${ {name} + "さん" })。

三項演算子(条件 ? A : B のような書き方)など、一部の式はまだ未対応です。また {変数 as number} のような型変換の書き方も使えません。

オプションやループから自動的に使える変数

自分で「変数を設定」しなくても、コマンドの作りによっては最初から使える変数があります。

  • コマンドの**オプション(引数)**を追加すると、その入力値が {option_オプション名} という変数として自動で使えます。たとえばテキスト入力のオプションを「名前」で作ると、{option_名前} でその値を参照できます。
  • ユーザー・チャンネル・ロールを受け取るオプションは、まとまった情報(オブジェクト)として使えます。たとえば {option_対象.id}、{option_対象.mention} のように細かい情報を取り出せます。
  • ループノードを使うと、繰り返しの状況を表す変数が自動で作られます。ループの変数名を 名前 にした場合、{名前.index}(今が何回目か。0 から数える)と {名前.count}(全体の回数)が使えます。
  • このほか、「メッセージを送信」「ロールを作成」「API リクエスト」などのノードも、結果を変数として残せます。

オプションやループで作られる値は、特別な設定をしなくても自動的に変数として使えます(例: ループの {名前.index})。どんな変数が使えるかは、テキスト入力欄の変数ボタンから一覧で確認できます。

よく使う組み込み変数のプロパティ

ユーザーやサーバーなどの情報は、ドットでプロパティをつないで取り出します。代表的なものを挙げます。

変数取り出せる主な情報
ユーザー (User)name(名前)/ id / mention(@メンション)/ icon.url(アイコン画像)
サーバー (Guild)name / id / memberCount(メンバー数)/ owner.name(オーナー名)
チャンネル (Channel)name / id / mention
ロール (Role)name / id / mention / color / position

変数を設定(setVariable)— 名前と値・型を決めて代入する

自分で好きな値を覚えさせたいときは、「変数を設定」ノードを使います。左パネルの「変数」カテゴリ(変数操作)から追加できます。

変数まわりのノードは、左パネルの**「変数」カテゴリ**にまとまっています。カテゴリは左から「選択」「動作」「条件」「制御」「変数」と並び、「変数」の中はさらに「変数操作」(変数を設定/変数に演算を適用/変数を削除)・「配列操作」(配列に追加 など 6 種)・「乱数」(乱数（数値）/配列から抽選)の小見出しに分かれています。

「変数を設定」ノードを追加する

ノードをキャンバスへドラッグするかクリックして追加します。追加したノードを選ぶと、右側に設定欄が開きます。

「変数名」を入力する

「変数名」欄に、覚えさせる変数の名前を入力します。これが後で {変数名} として参照する名前になります。英字・数字・アンダースコア(_)で分かりやすい名前を付けるのがおすすめです。

「型」を選ぶ

「型」欄で、入れる値の種類を選びます。種類については次の節で説明します。

「値」を入力する

「型」が「オブジェクト」「配列」以外のときは、「値」欄に代入する値を入力します。値の欄では {変数名} の参照や ${ ... } の計算式も使えます。「オブジェクト」「配列」を選んだときは、単一の「値」欄の代わりに専用のエディタが表示されます(後述)。

必要なら「ノードタイトル」を変える

「ノードタイトル」欄で、このノードのキャンバス上の表示名を任意に変更できます(処理内容には影響しません)。

変数名を入力すると、設定欄に {変数名} という参照用のコピー欄が表示されます。これをコピーして、後続のノードのテキスト欄に貼り付ければ、その値を差し込めます。

「変数を設定」で作った変数は一時的な変数(ローカル変数)です。サーバーやユーザーごとに値を残したい場合は、後述のカスタム変数を使ってください。

型の選択(文字列/数値/真偽値/ユーザー/チャンネル/ロール/オブジェクト/配列)

「変数を設定」の「型」欄では、次の種類から選べます。型を正しく選ぶと、後続ノードの入力補助(オートコンプリート)に適切なプロパティが表示されます。

型の表示説明
「文字列 (string)」文字のデータ。名前やメッセージなど
「数値 (number)」数のデータ。計算に使えます
「真偽値 (boolean)」はい/いいえ(true / false)
「ユーザー (User)」Discord ユーザー。.id / .name / .mention などが使えます
「チャンネル (Channel)」Discord チャンネル。.id / .name / .mention などが使えます
「ロール (Role)」Discord ロール。.id / .name / .mention などが使えます
「オブジェクト (Object)」複数のプロパティをまとめて持てる箱。下のエディタで中身を定義します
「配列 (Array)」同じ型の値を順番に並べて持てるリスト。下のエディタで要素の型と初期要素を定義します(後述)

オブジェクト型でプロパティを定義する {変数名.キー名}

型で「オブジェクト (Object)」を選ぶと、専用の「プロパティ」エディタで中身を定義します。プロパティとは、1 つの変数の中に持たせる「小さな名前付きの値」のことです。

「プロパティを追加」をクリックする

「プロパティを追加」ボタンでプロパティを 1 件追加します。プロパティは最大 50 件まで作れます。

「キー名」を入力する

各プロパティの「キー名」欄に、プロパティの名前を入力します。キー名は英字・数字・アンダースコア(_)のみで、先頭は英字または _ にしてください(ルールに合わないと赤い注意が表示されます)。

「型」と「値」を設定する

プロパティごとに「型」を選び、「値」を入力します。値の欄では {変数名} 参照や ${ ... } 式も使えます。

定義したプロパティは、後続ノードから {変数名.キー名} の形式で参照できます。各プロパティの上部には、{変数名.キー名} の形のプレビューが表示されるので、それを見ながら参照すると確実です。

不要になったプロパティは、各プロパティ右上のごみ箱アイコンで削除できます。

配列型で要素の型と初期要素を定義する

型で「配列 (Array)」を選ぶと、「値」の単一入力欄の代わりに「要素の型」セレクタと「初期要素」エディタが表示されます。配列は「同じ型の値を順番に並べたリスト」で、たとえば「当選者の候補」「サイコロの履歴」などを 1 つの変数にまとめて持てます。

「要素の型」を選ぶ

「要素の型」欄で、配列に入れる値の種類を選びます。「文字列 (string)」「数値 (number)」「真偽値 (boolean)」「ユーザー (User)」「チャンネル (Channel)」「ロール (Role)」「サーバー (Guild)」「時刻 (Time)」から選べます。

「初期要素」を追加する

「要素を追加」ボタンで要素を 1 件追加します。各要素の入力欄には {変数名} 参照や ${ ... } 式も使えます。各要素の左には [0]、[1] のように位置(添字)が表示されます。要素を追加しないまま保存すると、空の配列になります。

定義した配列は、後続ノードから要素の位置を指定して参照できます。たとえば 1 番目の要素は {変数名.0}、要素数は {変数名.length} のように取り出せます(要素型に「ユーザー (User)」などを選ぶと、{変数名.0.mention} のようなプロパティも入力補助に出ます)。

配列の中身を読み取る(添字・長さ・先頭/末尾)

配列の特定の要素や全体の情報は、ドットや角かっこの添字記法で取り出せます。いずれもテキスト欄では {変数名} の中に書きます。

書き方取り出せるもの
{変数名.0} / {変数名[0]}先頭(0 番目)の要素。添字は 0 から数えます
{変数名[1]}2 番目の要素
{変数名[-1]}末尾の要素(マイナスの添字は末尾から数えます)
{変数名.length}要素の個数
{変数名.first}先頭の要素({変数名.0} と同じ)
{変数名.last}末尾の要素({変数名[-1]} と同じ)

要素型が「ユーザー (User)」などのオブジェクト系のときは、{変数名.0.mention} や {変数名.first.name} のように、取り出した要素のプロパティをさらにドットでつなげます。

これらの記法は、計算式 ${ ... } の中でも使えます(添字アクセスや length などの関数)。式の中での配列の扱いについては式の言語(${ ... } の書き方)で詳しく説明しています。

配列の中に配列を入れたり(ネスト)、配列の要素にオブジェクトを入れることはできません。要素の型には「配列 (Array)」「オブジェクト (Object)」は選べません。

要素を追加・取り出し・更新・挿入・削除したいときは、初期要素のエディタではなく、後述の配列操作ノードを使います。各要素は右上のごみ箱アイコンで削除できます。

配列操作(配列に要素を出し入れする)

配列型の変数に対して、要素を後から追加したり取り出したりするためのノードが「配列操作」です。左パネルの「変数」カテゴリ(配列操作)に 6 種類あります。いずれも「対象変数名」には中括弧 {} を付けず、名前だけ(例: members)を入力し、配列(Array)型の変数を指定します。永続変数を対象にするときは BSVAR_ で始まるリファレンス名を指定します。

ノード役割主な入力
「配列に追加」配列の末尾に要素を 1 つ追加する「対象変数名」/「値」(/「要素の型」)
「配列から取り出し」配列の末尾の要素を取り除く。取り除いた要素は任意の変数へ退避できる「対象変数名」/「退避先変数名 (任意)」
「配列を更新」指定した位置(添字)の要素を上書きする「対象変数名」/「添字」/「値」
「配列に挿入」指定した位置(添字)の前に要素を割り込ませる「対象変数名」/「添字」/「値」
「配列から削除」指定した位置(添字)の要素を取り除く「対象変数名」/「添字」
「配列を空にする」配列をまるごと空([])にリセットする「対象変数名」

配列に追加・取り出し

「配列に追加」は配列の末尾に値を 1 つ足します。「値」欄には追加したい値を入力し、{変数名} 参照や ${ ... } 式も使えます。対象の配列を「変数を設定」やカスタム変数で宣言してあると、その要素の型が自動的に引き継がれます(「要素の型」が継承表示になります)。まだ宣言していない配列を対象にしたときは、「要素の型」を自分で選びます。

「配列から取り出し」は末尾の要素を 1 つ取り除きます。「退避先変数名 (任意)」を指定すると、取り除いた要素をそのローカル変数に入れて後続で使えます(永続変数 BSVAR_ は退避先に指定できません)。空欄にすると要素は捨てられます。

位置(添字)を指定する操作

「配列を更新」「配列に挿入」「配列から削除」は、操作する位置を「添字」欄で指定します。

  • 添字は 0 から数えます(先頭は 0、2 番目は 1)。
  • マイナスの値を入れると末尾から数えます(-1 が末尾)。
  • 「配列を更新」「配列から削除」では、範囲の外を指したときは何も起きません。
  • 「配列に挿入」では、指定した添字の前に要素が入ります。

「添字」欄や「値」欄でも {変数名} 参照や ${ ... } 式が使えます。

配列を空にする

「配列を空にする」は、対象の配列をまるごと空([])に戻します。たとえば「抽選候補をいったん全部クリアする」といったときに使います。

配列操作ノードは、コマンド内だけの一時的な配列にも、BSVAR_ で始まるカスタム変数(永続変数)の配列にも使えます。永続変数の配列を対象にするときは、あらかじめカスタム変数で配列として作成しておいてください。

乱数(ランダムな値を作る)

ランダムな値がほしいときは、「変数」カテゴリの「乱数」にある 2 つのノードを使います。どちらも結果をローカル変数に入れ、後続ノードから {変数名} で参照できます。

乱数の結果はローカル変数(一時的な変数)にしか入れられません。BSVAR_ で始まるカスタム変数(永続変数)を「結果変数」に直接指定しても書き込まれません。乱数の結果を永続的に残したいときは、いったんローカル変数に入れてから、「変数に演算を適用」などで BSVAR_ の変数へ反映してください。

乱数（数値）

「乱数（数値）」ノードは、指定した範囲の中からランダムな数を 1 つ作ります。

「最小値」「最大値」を入力する

「最小値」に範囲の下限、「最大値」に範囲の上限を入力します。{変数名} 参照や ${ ... } 式も使えます。範囲は両端を含みます。最大値が最小値より小さいときは、自動的に入れ替えて扱われるので、大小を気にせず入力できます。

「整数で生成」を切り替える

「整数で生成」をオンにすると整数、オフにすると小数(実数)が作られます。初期状態はオンです。

「結果変数」を入力する

「結果変数」欄に、作った数値を入れる変数名を入力します({} は付けず名前だけ)。入力すると、{変数名} のコピー欄が表示されます。

配列から抽選

「配列から抽選」ノードは、配列の中からランダムに要素を選び出します。たとえば「参加者の中から当選者を選ぶ」といった抽選に使えます。

「ソース配列」を入力する

「ソース配列」欄に、抽選元の配列変数名を入力します({} は付けず名前だけ)。一時的な配列でも BSVAR_ のカスタム変数でも指定できます。配列(Array)型を指定してください。

「個数」を入力する

「個数」欄に、いくつ選ぶかを入力します(初期値は 1)。1 なら単一の要素を、2 以上なら選ばれた要素の配列を返します。{変数名} 参照や ${ ... } 式も使えます。

「重複なし」を切り替える

「重複なし」をオンにすると、同じ要素を重複させずに選びます。個数が配列の要素数を超える場合、オンのときは要素数までに収まるよう調整されます(クランプされ、要素数より多くは選ばれません)。オフにすると同じ要素が複数回選ばれることがあり、個数が要素数を超えてもその分だけ選ばれます。初期状態はオンです。

なお、一度に抽選できる個数には上限があります。極端に大きな個数を指定しても、上限を超える分は切り詰められます。

「結果変数」を入力する

「結果変数」欄に、抽選結果を入れる変数名を入力します({} は付けず名前だけ)。個数が 1 のときは単一の要素、2 以上のときは配列({変数名.0} や {変数名.length} などで参照)が入ります。

変数に演算を適用(加減乗除・連結)

すでにある数値の変数に対して「足し算」などをして、その結果を同じ変数に入れ直したいときは、「変数に演算を適用」ノードを使います。たとえば「勝った回数を 1 増やす」といった処理に向いています。

「変数に演算を適用」ノードを追加する

左パネルの「変数」(変数操作)から「変数に演算を適用」を追加し、ノードを選びます。

「対象変数名」を入力する

「対象変数名」欄に、計算結果を入れたい変数の名前を入力します。ここでは中括弧 {} は付けず、名前だけを入力してください(例: score)。

「式」を入力する

「式」欄に、計算したい内容を入力します。ここでは {変数名} 参照や ${ ... } 式が使えます。

  • 例: {counter} * 2(counter を 2 倍にする)
  • 例: {customVar} + 3(customVar に 3 を足す)

必要なら「ノードタイトル」を変える

このノードのキャンバス上の表示名を任意に変えられます。

「変数に演算を適用」でカスタム変数(サーバーやユーザーごとに保存される変数)を増やすときは、複数の人が同時に実行しても値が壊れないよう、内部で安全に加算する仕組みが働きます。数値タイプのカスタム変数なら、まだ値がない場合でも 0 から数え始めるので、最初の 1 回目から正しく増えます。

変数を削除(永続変数を空にリセット)

「変数を削除」ノードは、指定したカスタム変数(永続変数)の値を空(初期値)にリセットするためのノードです。たとえば「累計スコアをゼロに戻す」といったときに使います。

「変数を削除」ノードを追加する

左パネルの「変数」(変数操作)から「変数を削除」を追加し、ノードを選びます。

「対象変数名」を入力する

「対象変数名」欄に、リセットしたい永続変数の名前を入力します。ここでも中括弧 {} は付けず、名前だけを入力してください。

このノードはカスタム変数(永続変数)専用です。一時的な変数(ローカル変数)はコマンドの実行が終われば自動的に消えるため、削除の対象にはなりません。

左パネルの「変数」でカスタム変数を作成・管理する

サーバーやユーザーごとに値をずっと保存しておきたいときは、「カスタム変数」を作成します。カスタム変数は、コマンドビルダー左側のサイドバーにある「変数」(コード記号のアイコン)から管理します。

「変数」パネルを開く

左サイドバーの「変数」アイコンを選びます。これまでに作成したカスタム変数の一覧が表示されます。まだ 1 つも作っていない場合は「カスタム変数がまだ作成されていません」と表示されます。

「新しいカスタム変数」をクリックする

パネル上部の「新しいカスタム変数」ボタンをクリックすると、作成用のウィンドウが開きます。

「表示名」を入力する

「表示名」欄に分かりやすい名前を入力します(日本語も使えます)。入力すると「リファレンス名」が自動で決まります。リファレンス名は実際にコマンドビルダーで使う変数名で、自動的に BSVAR_ で始まる名前になります(この欄は読み取り専用です)。

「データタイプ」を選ぶ

「データタイプ」で保存する値の種類を選びます。「文字列(String)」「数値(Number)」「真偽値(Boolean)」「オブジェクト(Object)」「配列(Array)」「ユーザー(User)」「チャンネル(Channel)」「サーバー(Guild)」「ロール(Role)」から選べます。

「スコープ」を選ぶ

「スコープ」で、この変数をどの範囲で共有するかを選びます(詳しくは次の節)。

「デフォルト値」を設定する(任意)

「デフォルト値」欄に初期値を入力できます。型によって入力方法が変わり、数値なら数値入力、真偽値なら true / false の選択になります。

「保存」をクリックする

「保存」ボタンをクリックすると、カスタム変数が作成され、一覧に追加されます。

作成したカスタム変数は、コマンドビルダーのテキスト欄で {リファレンス名}(例: {BSVAR_score})として参照したり、「変数を設定」「変数に演算を適用」「変数を削除」ノードの変数名として使えます。

カスタム変数の編集・削除

一覧の各カードには、その変数の「型:」と「スコープ:」、そして「カスタム」バッジが表示されます。カードの「編集」ボタンで内容を修正でき、「削除」ボタンで変数そのものを削除できます。編集ウィンドウの中からも削除できます。一覧上部の「検索…」欄で、名前から変数を絞り込めます。

カスタム変数で「オブジェクト(Object)」型を選ぶと、ここでもプロパティ(「キー名」「型」「初期値」)を定義でき、「プロパティ追加」ボタンで追加できます。{リファレンス名.キー名} の形で参照します。

カスタム変数で「配列(Array)」型を選ぶと、「要素の型」セレクタと初期要素のエディタが表示されます。作成した配列の永続変数は、配列操作ノードや「配列から抽選」の対象に BSVAR_ で始まるリファレンス名で指定できます。

カスタム変数のスコープ(グローバル / サーバーごと / ユーザーごと)

「スコープ」は、その変数の値をどの単位で覚えておくかを決める設定です。

スコープの表示共有される単位使いどころの例
「グローバル(Global)」Bot 全体で 1 つBot 全体の累計実行回数
「サーバー毎(Guild)」Discord サーバーごとに別々サーバー内ランキング、サーバーの設定
「ユーザー毎(User)」Discord ユーザーごとに別々(サーバーをまたいで同じ)個人の通算成績(コイントスの勝敗など)

一覧カードの「スコープ:」欄では、それぞれ「グローバル」「サーバーごと」「ユーザーごと」と表示されます。

「サーバー毎(Guild)」のスコープは、サーバー内での実行が前提です。DM(ダイレクトメッセージ)など、サーバーが特定できない場所では、このスコープの変数への書き込みは行われません(エラーは出ず、静かにスキップされます)。読み取り自体はでき、以前の値がそのまま参照されます。サーバーをまたいで個人ごとに値を残したい場合は「ユーザー毎(User)」を選んでください。

未定義変数の警告について

存在しない変数名を {} で参照すると、そのノードに「この名前の変数は見つかりません」という黄色の警告が表示されます。

存在しない変数名を {} で参照すると黄色の警告が出ます。保存自体は可能ですが、実行時にはその部分が空になることがあります。変数名のスペルミスや、まだ「変数を設定」していない名前を参照していないか確認してください。

警告が出たときは、次の点を見直してください。

  • 変数名のスペルが、設定したときの名前と一致しているか
  • カスタム変数なら、BSVAR_ で始まる正しいリファレンス名を使っているか
  • その変数が、参照しているノードより前のノードで作られているか(一時的な変数は、設定したノードより後でしか使えません)

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

最終更新:
制御フローイベントビルダー