|
|
| Line 1: |
Line 1: |
| '''Variables''' in BSL are very similar to variables in other programming languages. Here's a brief explanation of what a variable is:
| | To learn how to declare and use variables, read the BSL manual's [[BSL:Manual#Variables|Variables]] section. This page documents Oni's built-in (or "native") scripting variables. The other half of the available scripting commands are in [[BSL:Functions]]. |
| | |
| When writing logical programs, one often needs the program to remember some information (a number, a piece of text, the ON/OFF state of a switch, etc) so that the information can be used at a later time.
| |
| | |
| The usual thing to do in this situation is to store the needed data in a '''variable''': an elementary data container.
| |
| | |
| ==General notions==
| |
| ===Type and value===
| |
| A variable (data container) has three important attributes: the ''name'', the ''type'' and the ''value''.
| |
| | |
| The ''value'' or the variable is just the contents it currently stores. It can be read and written.
| |
| | |
| Also, a given variable can store only a specific ''type'' of data (floating-point number or integer or text string or boolean), and that is what we call the variable's type.
| |
| | |
| Finally, the ''name'' of a variable is a unique text string that is used to identify the data container within the script. Like [[BSL:Functions|function]] names, variable names are case-sensitive (NOTE: all variables and functions are lower-case). Valid characters are: ''please fill me in''
| |
| | |
| An easy way to get the ''type'' and ''value'' of an existing BSL variable is to enter its ''name'' at the console in [[Developer Mode]]: you typically get console output like "bool: 1" or "int32: 42" or "float: 3.14" or "string: hello"
| |
| | |
| ===Declaration and assignment===
| |
| If you want to use a new variable (data container), you must set it up (''declare'' it) first, with the '''var''' keyword. A declaration statement can look a bit like this:
| |
| var int my_superduper_integer;
| |
| var bool my_totally_awesome_boolean;
| |
| var string my_incredible_text_string;
| |
| var float my_cool_floating_point_number;
| |
| The first word is the keyword "var", next comes the type (keyword), then the name of the variable. The final ";" is required. The name can be any valid name (i.e., not a keyword and not containing invalid characters) | |
| | |
| A declaration is usually seen at "global scope" (i.e., outside all functions). It is recommended to group declarations at the beginning of a BSL file (for readability), but it's not necessary. It is also not necessary (but strongly recommended) to declare a variable ''before'' the context where it is used for the first time.
| |
| | |
| On some occasions you may want to declare a ''local'' variable (i.e., to embed a declaration statement into a [[BSL:Functions|function]]). This feature will be detailed elsewhere.
| |
| | |
| '''Note''': BSL will not complain if you use a nonexistent variable for instance in a if condition. However this cause undefined behavior in your scripts (e.g. for instance I had a real case scenario where chr_wait_health did not work as expected) so make sure you always declare the variables that you are using in your scripts.
| |
| | |
| ===Assignment===
| |
| You can assign a new value to an existing variable with the assignment operator "=". The name of the variable you want to modify is on the left-hand-side (LHS) of the "=", and on the right-hand-side (RHS) you can have any valid expression that evaluates/converts into the variable's type.
| |
| | |
| An assignment can be combined with a declaration (see above). That means the variable will have a definite value right after it is created. If you don't specify/define such a starting value, you should not, generally speaking, assume anything about the value.
| |
| | |
| However, apparently there ''are'' "default" values assigned to every variable even if it hasn't been defined yet. Those values are 0 (i.e., false) for bool, 0 for int and float, and "" (empty string) for string.
| |
| | |
| ==Built-in variables==
| |
| All the built-in BSL variables are listed here, in alphabetical order.
| |
|
| |
|
| | ==Legend== |
| ;Color | | ;Color |
| :White: available on all versions | | :White: available in all versions |
| :Blue: command only exists in Mac Intel build | | :Blue: command only exists in Mac Intel build |
| :Green: command only exists in Windows build | | :Green: command only exists in Windows build |
| Line 57: |
Line 18: |
| :"NO": command is proven not to work | | :"NO": command is proven not to work |
|
| |
|
| | ==Built-in variables== |
| {|border=1 cellspacing=0 cellpadding=2 | | {|border=1 cellspacing=0 cellpadding=2 |
| !Type!!Name!!Default value!!Comment!!Works | | !Type!!Name!!Default value!!Comment!!Works |