Skip to content

Types

If your plugin only deals with numbers, you are unlikely to encounter issues related to data types. However, a solid understanding of data types becomes essential when working with text and lists.

Data Types

All values in Blockly (and in the compiled C# DLL) have a specific data type. There are four primary types:

Blockly Type C# Type Description
Number int / double An integer or a floating-point number.
String string A sequence of characters, also known as text.
Boolean bool A value that can be either True or False.
Array List<dynamic> A collection that can hold other values.

It is crucial to understand that data of different types are fundamentally distinct, even if they appear similar. For example, the String "123" is a sequence of characters '1', '2', and '3', whereas the Number 123 represents the numerical value one hundred twenty-three. Similarly, the String "True" is a sequence of characters, while the Boolean value True represents a logical state.

BVE Interface Value Types

When interacting with the BVE API, most functions (with the exception of beacon distance) exclusively accept and return integer values. This applies to setting panel states, sound states, and handle positions. If a decimal number is provided, it will be truncated to an integer. This means you cannot directly pass decimal numbers to in-game variables (e.g., ats.xx / pluginState[x]). A common workaround is to multiply the value by a factor before passing it to BVE and then scale it back down in your panel or animated object configuration.

Configuration (INI) Item Types

  • If the value of an INI item is purely numeric, it will be automatically parsed as a Number.
  • If the value is true or false (case-insensitive), it will be parsed as a Boolean.
  • In all other cases, the value will be treated as a String.

Type Conversion

To convert a value from one type to another, use the "to string," "to number," and "to boolean" blocks, which can be found in the "Others" category. These blocks internally use C#'s Convert.ToString, Convert.ToDouble, and Convert.ToBoolean functions, respectively.

  • to number: Converts a numeric string to its corresponding Number value. The Boolean True is converted to 1, and False to 0. Passing a non-numeric string will raise a runtime error.
  • to boolean: Converts the Number 0 to False and any other number to True. The strings "True" and "False" (case-insensitive) are converted to their corresponding Boolean values. Passing any other string will raise a runtime error.
  • to string: Converts numbers and Boolean values to their string representations (e.g., "True", "False"). Note that this block cannot be used to directly access the string representation of an entire array's contents.

Avoiding Type Mismatches

Attempting to perform operations on incompatible types (e.g., subtracting a String from a Number, or assigning a String to a panel variable that expects a Number) will trigger a runtime error.

In most cases, Blockly's built-in type checking system prevents such errors by ensuring that only blocks of compatible types can be connected. However, this compile-time checking does not apply to variables, list elements, or configuration items, as their types are dynamic. A runtime error will occur if you lose track of their types.

  • For variables, always be mindful of the type of value you assign to them.
  • For configuration items, either ensure that users provide values of the correct type or explicitly convert them in your code before use.

Example: A Type Mismatch Scenario

Let's consider a plugin designed to cycle a panel variable through a predefined list of values.

Blockly Code: Blockly Code

loop.ini Configuration: 

[loop]
values = 1, 3, 4, 7, 5, 6
id = 5
interval = 1000

Based on how BlocklyAts parses INI files, values will be interpreted as a String, while id and interval will be parsed as Numbers. In the code, we retrieve the (display + 1)-th element from the list, because list indices in Blockly are 1-based.

This code will compile successfully. However, at runtime, it will fail with an error stating that a string cannot be converted to an int (a Number). Can you spot the issue? Runtime Error

The problem is that when we split the values string ("1, 3, 4, 7, 5, 6") by the comma delimiter, the result is a list of strings: ["1", "3", "4", ...]. Consequently, when we access an element from this list, we get a String (e.g., "1"), not a Number (1). The error occurs because panel variables can only be set to integers, and we are attempting to assign a string.

Solution: The issue can be resolved by simply adding a "to number" block to convert the string element to a number before assigning it to the panel variable. Solve Error

As a best practice, you could also convert all items in the list to their correct types in a loop when the plugin first loads.