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

コマンドビルダーの入力欄では、変数の値や計算結果を差し込めます。書き方は次の 2 種類です。

変数は、それを作ったノードより後ろのノードでだけ参照できます。変数の種類(一時変数・永続変数)の違いは一時変数と永続変数をご覧ください。

変数名とキー名に使える文字見出しへのリンクをコピー

• 変数名: 文字・数字・アンダースコア(_)・ドット(.)が使えます。文字には日本語・中国語・韓国語・キリル文字なども含まれるため、お金 や 用户名 のような名前も使えます。空白・記号・絵文字は使えません({🎉} のように書いても変数とは見なされず、そのまま表示されます)。
• オブジェクト型のキー名: 英字・数字・アンダースコアだけが使え、先頭は英字またはアンダースコアにします。プロパティは 1 つの変数につき最大 50 件です。後続ノードからは {変数名.キー名} で参照します。

ノードごとの注意点見出しへのリンクをコピー

• 「変数を設定」: 新しい永続変数(BSVAR_)は作れません。永続変数は先にストレージで作っておく必要があり、登録していない BSVAR_ 名を指定しても何も起こりません。
• 「変数に演算を適用」「変数を削除」の「対象変数名」: 波かっこを付けずに名前だけを入力します(例: counter、BSVAR_score)。波かっこ付きの {変数名} を使うのは、値を参照する式の中だけです。カウンターを 1 増やすなら、対象変数名に counter、式に {counter} + 1 と入力します。
• 「変数を削除」: 対象にできるのは永続変数だけで、ストレージで設定した初期値(デフォルト値)に戻します。一時変数名を入れても何も起こりません。

計算式の書き方見出しへのリンクをコピー

${ … } と「変数に演算を適用」の「式」では、次の演算子が使えます。優先順位はふつうの算数と同じで、丸かっこ ( ) で順番を変えられます。

• 式の中で文字を直接書くときは、"…" か '…' で囲みます(例: ${ {firstName} + " " + {lastName} })。
• 比較の結果は、小文字の true / false として差し込まれます。種類の違う値どうしを比べると結果が得られず、空文字になります。
• 文字列で足し算以外の計算をしたり、種類の違う値を比べたりすると、編集画面に警告が出ることがあります(保存はできます)。

数値を丸める見出しへのリンクをコピー

引数が数値でない、n が整数でない、n の絶対値が 15 を超える、引数の数が合わない、のいずれかに当てはまると、その ${ … } は空文字になります。

配列を式の中で扱う見出しへのリンクをコピー

${ {listA} + {listB} } のように + で配列どうしをつなげることもできます。

実際の動作と既定値見出しへのリンクをコピー

解決できない参照は書いたままの文字が残る見出しへのリンクをコピー

参照先が見つからない・式の評価に失敗した、という場合でもコマンドは止まらず、ユーザーにエラーも表示されません。

• {存在しない変数} は、空文字ではなく {存在しない変数} という文字のまま残ります。1 回の実行につき変数名ごとに 1 度だけ警告がログに記録されます。
• ${ … } の評価に失敗したとき(構文の誤り、${ 5 / 0 } のような 0 での割り算・余り計算など)は、その ${ … } が書いたまま残ります。式の中の {変数} だけは値に置き換わります。
• ただし、${ … } の中で参照した変数が見つからないときは、その式全体が空文字になります。
• ${ … } の結果に { … } の形が含まれていても、変数としては展開されません。

{ … } がそのまま表示されているときは、変数名のつづり、参照する順番(作成するノードより前で参照していないか)、使えないプロパティを指定していないかを確認してください。

値の型による扱い見出しへのリンクをコピー

• 数値: 整数として表せる値は .0 を付けずに表示されます(5.0 は 5)。
• 文字列型は数値に変換されない: 型が「文字列 (string)」の変数は、中身が 42 でも数値として扱われません。${ {output} + 100 } は 142 ではなく 42100 になります。計算に使う変数は「数値 (number)」型にしてください。数値型への変換に失敗したときは 0 になります。
• 真偽値: true / yes / on / 1(大文字・小文字は区別しません)が真、それ以外は偽です。計算の中では true が 1、false が 0 として扱われます。
• オブジェクト型・配列型: {変数名} で丸ごと参照すると、JSON 形式の文字列が差し込まれます。API リクエストの応答なども {apiReq_response.status} のようにたどって取り出せます。

配列の要素を式の外で取り出す見出しへのリンクをコピー

角かっこの {変数名}[0] と、[-1] のような負の番号は ${ … } の中でだけ使えます。

リストをまとめて扱う見出しへのリンクをコピー

配列型の変数と、{Guild.roles} のようなリストのプロパティには、次の書き方も使えます。

• 要素がオブジェクトのときは、{shop.sum.price} {shop.highest.price} のようにキーを指定して集計できます。has count position も [name=Potion] のように「キー=値」で探せます。
• 集計で数えるのは、数値と、"7" のように数値として読める文字列だけです。
• 一致は、両方が数値として読めれば数値として比べます(5 と "5" は一致)。それ以外は文字列として、大文字・小文字を区別して比べます。
• [ ] の中には {User.id} のような単純な変数を書けます({joined.has[{User.id}]})。その変数が解決できないと、参照全体が解決されません。[ ] = $ \ を文字として書くときは前に \ を付けます。{ } は書けません。
• each has count position は [ ] を省略できません。
• .each と .join の結果は文字列なので、後ろに続けて書けません。

each の書式見出しへのリンクをコピー

書式は要素ごとに繰り返され、次の記号が置き換わります。\n で改行します。

{bag.each[$number. $value\n]} は 1. sword 2. shield と 1 行ずつ並べます。要素に無いキーは $キー名 のまま表示されます。

件数の上限見出しへのリンクをコピー

• .each と .join が出力するのは先頭 1,000 件・4,000 文字までです。4,000 文字を超える要素からあとは出力されません。
• 集計・検索・[キー=値] が調べるのは先頭 10,000 件までです。

数値の表記見出しへのリンクをコピー

数値型の変数と数値のプロパティ({Guild.memberCount} など)は、次の書き方で表記を変えられます。

• 負の数は先頭に - が付きます。.formatted と .japanese は整数部だけを変換し、小数部はそのまま付けます(1234.5 → 1,234.5)。
• 結果は文字列なので、後ろに続けて書けません。{変数名.sum.formatted} のように集計の後ろには付けられます。
• 文字列型の変数に入った数値("1234" など)には使えず、書いたままの文字が残ります。

変数の種類と参照のしかた(namespace)見出しへのリンクをコピー

{ … } の中では、次の種類の変数を参照できます。

• {Now} と {Now.unix} は協定世界時(UTC)基準で、Bot が動いているホストのタイムゾーンには左右されません。時刻での条件分岐は Bot のタイムゾーンで判定します。
• ボタンや選択メニューの分岐の中では、{Command.*} は「そのクリック」の文脈を指します。
• {Event.*} で使える変数はイベントの中で使える変数をご覧ください。値が用意されない参照は文字列のまま残り、その参照を使った条件は false になります。
• ユーザー・ロール・チャンネルなどを受け取るオプションはオブジェクトとして扱われます。「オプション変数」を option_user にした場合、{option_user} はオブジェクト全体、{option_user.mention} はメンションになります。

ドット記法で使えるプロパティは決まっている見出しへのリンクをコピー

ドット記法は、組み込みの型(ユーザー・サーバー・チャンネル・ロール・日時・金額・URL・絵文字・スタンプ・メッセージ)と、オブジェクト型・配列型の変数の、決められたプロパティにだけ使えます。型ごとのプロパティはデータ型をご覧ください。

• 文字列・数値・真偽値にドットを付けても解決されません({score.real} は無効です)。数値に付けられるのは数値の表記の 3 つだけです。
• 用意されていないプロパティや、先頭がアンダースコアの名前({User._private} など)も解決されません。
• ボタン・選択メニューの結果は、.user・.channel・.guild・.value・.label・.style・.disabled を参照できます。

上限とクールダウン見出しへのリンクをコピー

実行時間・ステップ数・ループ回数のプラン別の上限とクールダウンは、コマンドビルダーの上限とクールダウンにまとめています。補足として次の点があります。

• 実行時間には、ボタンやモーダルの入力待ちの時間も含まれます。ただし、入力を受け取るたびに待ち時間ぶん延長されます。
• ループの回数に上限より大きい値を指定しても、上限の回数で止まります。
• ステップ数の上限を超えると警告が 1 回だけ表示され、残りのノードはスキップされます。メッセージの文面はコマンドビルダーの「表示されるメッセージ」をご覧ください。

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

• ${ … } の中に、さらに ${ … } を入れることはできません。
• {{変数名}} のように波かっこを 2 重にすることはできません。

次のステップ / 関連ページ見出しへのリンクをコピー

• 永続変数 — BSVAR_ 変数のスコープと、DM での書き込みなど読み書きの挙動
• ストレージ — 永続変数を作成・管理する画面
• 変数と式の使い方 — 配列操作・乱数など、変数まわりのノード