値の型
プラグインが数値のみを扱う場合、データ型に関する問題に遭遇することは稀です。 しかし、テキストやリストを扱う際には、データ型を正確に理解することが不可欠になります。
データ型
Blockly（およびコンパイル後のC# DLL）のすべての値は、特定のデータ型を持ちます。主に以下の4つの型があります。
| Blockly 型 | C# 型 | 説明 |
|---|---|---|
Number |
int / double |
整数または浮動小数点数。 |
String |
string |
文字のシーケンス。「テキスト」とも呼ばれます。 |
Boolean |
bool |
TrueまたはFalseのいずれかをとる値。 |
Array |
List<dynamic> |
他の値を格納できるコレクション。 |
見た目が似ていても、異なる型のデータは根本的に別物であることを理解することが重要です。例えば、String型の"123"は'1'、'2'、'3'という文字の並びですが、Number型の123は百二十三という数値を表します。同様に、String型の"True"は文字の並びですが、Boolean型のTrueは論理的な真の状態を表します。
BVEインターフェース値の型
BVE APIとの連携において、ほとんどの関数（ビーコン距離を除く）は整数値のみを受け取り、返します。これはパネル、サウンド、ハンドルの状態設定にも適用されます。小数を渡した場合、その値は整数に切り捨てられます。つまり、ゲーム内変数（例: ats.xx / pluginState[x]）に直接小数を渡すことはできません。回避策として、プラグイン内部で値を特定の倍率で乗算し、パネルやアニメーション付きオブジェクトの設定で元のスケールに戻す方法が一般的です。
設定（INI）項目の型
- INIファイルの項目の値が純粋な数値である場合、自動的に
Number型として解釈されます。 - 値が
trueまたはfalse（大文字・小文字を区別しない）の場合、Boolean型として解釈されます。 - それ以外の場合、値は
String型として扱われます。
型変換
ある型の値を別の型に変換するには、「その他」カテゴリにある「文字列に変換」「数値に変換」「ブール値に変換」ブロックを使用します。
これらのブロックは、内部でC#のConvert.ToString、Convert.ToDouble、Convert.ToBoolean関数をそれぞれ呼び出します。
- 数値に変換: 数値文字列を対応する
Number値に変換します。BooleanのTrueは1に、Falseは0に変換されます。数値以外の文字列を渡すと、ランタイムエラーが発生します。 - ブール値に変換:
Numberの0はFalseに、それ以外の数値はTrueに変換されます。文字列の"True"と"False"（大文字・小文字を区別しない）は、対応するBoolean値に変換されます。それ以外の文字列を渡すと、ランタイムエラーが発生します。 - 文字列に変換: 数値と
Boolean値を、その文字列表現（例:"True"、"False"）に変換します。このブロックで配列全体の内部コンテンツを直接文字列として取得することはできません。
型の不一致への注意
互換性のない型同士で操作を行おうとすると（例: NumberからStringを減算する、Numberを期待するパネル変数にStringを割り当てる）、ランタイムエラーが発生します。
多くの場合、Blocklyに組み込まれた型チェックシステムが、互換性のないブロック同士の接続を防ぐことで、このようなエラーを未然に防ぎます。しかし、変数、リスト要素、設定項目は動的な型を持つため、このコンパイル時チェックの対象外です。これらの値の型を把握しきれていない場合、実行時に問題が発生します。
- 変数については、それに代入する値の型を常に意識してください。
- 設定項目については、ユーザーが適切な型の値を提供するか、使用前にコード内で明示的に型変換を行ってください。
事例: 型の不一致によるエラー
パネル変数の値を、あらかじめ定義されたリストの値で循環させるプラグインを例に考えてみましょう。
Blockly コード:
loop.ini 設定:
[loop]
values = 1, 3, 4, 7, 5, 6
id = 5
interval = 1000
BlocklyAtsがINIファイルを解析する際、valuesはStringとして、idとintervalはNumberとして解釈されます。
コードでは、リストの(display + 1)番目の要素を取得しています（Blocklyのリストのインデックスは1から始まるため）。
このコードは正常にコンパイルされますが、実行時にはstringをint（Number）に変換できないというエラーが発生します。どこに問題があるか分かりますか？
問題は、valuesの文字列（"1, 3, 4, 7, 5, 6"）をカンマで分割した結果が、文字列のリスト（["1", "3", "4", ...]）になる点です。そのため、リストから要素を取得すると、それはNumberの1ではなく、Stringの"1"になります。パネル変数は整数しか受け付けないため、文字列を代入しようとして型変換エラーが発生したのです。
解決策:
この問題は、「数値に変換」ブロックを追加して、リスト要素をパネル変数に代入する前にNumber型に変換するだけで解決できます。
より良い実践として、プラグインの読み込み時にループ処理を行い、リスト内のすべての項目をあらかじめ正しい型に変換しておく方法もあります。