BSL:Introduction: Difference between revisions

From OniGalore
Jump to navigation Jump to search
(→‎Functions: let's give an actual sample function)
(this was moved to modding errors)
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{TOCfloat}}
This page gives a brief look at [[BSL]], Oni's scripting language. For those with scripting or programming experience, BSL's syntax and concepts will be very familiar, but BSL's feature set is simpler than most scripting languages. For details on any aspect of the language, as well as documentation of potentially-serious quirks in certain features of the language, read the [[BSL:Manual|BSL Manual]].
Like any typical scripting or programming language, BSL scripts consist of [[#Files|plain-text files]] which use [[#Logic|branching logic]] and [[#Operators|various operators]] to process [[#Types|data]] with [[#Functions|functions]] that act upon [[#Variables|variables]]. Click one of those words to jump to the brief explanations of those terms below, but if you are new to programming, you'll also want to read the "Details" pages that are linked to.
{{TOClimit|2}}
==Files==
When Oni loads a level, it also loads and parses all .bsl files in the folder in [[IGMD]] which contains that level's scripts (the name of this folder being specified by the level's [[ONLV]] resource). Like C, the code automatically begins running with the function called "main" at the time of level-load, regardless of which .bsl file it is found in (the convention in Oni's scripts is to place it in a file called *_main.bsl).
 
Unlike C, there are other "entry points" in the code. For instance, characters can call script functions upon death and trigger volumes can call functions when they are entered or exited. See [[CHAR]], [[OBD:BINA/OBJC/CONS|BINA CONS]], [[OBD:BINA/OBJC/DOOR|BINA DOOR]], [[NEUT]], and [[TRGV]] for all known places in the game data that can trigger BSL functions.
 
Note that the optional [[IGMD/global|global]] folder is also loaded for all levels, but any function found in a .bsl file in global/ will be stranded, only accessible by [[Developer Mode|developer console]], unless it is called by a function in a level script or by one of the above types of game data in that level.
 
==Syntax==
===Statements===
BSL supports strong and weak syntax in some ways. Here's a typical statement:


For those familiar with C, the syntax is similar and you will feel at home in BSL, but BSL's feature set is stripped down to a degree that is simpler than even most scripting languages. Fortunately, this makes BSL fast to learn.
dmsg("Hello");
{{clearall}}
==Files==
When Oni loads a level, it also loads and parses all .bsl files in the folder in [[IGMD]] which contains that level's scripts (the name of the folder being specified by the level's [[ONLV]] resource). Like C, the code automatically begins running with the function called "main", regardless of which .bsl file it is found in.


From that point on, only other functions that are called by main() will run on their own, though you can also manually call any of those functions from the [[Developer Mode|developer console]] (however, you cannot actually define variables or functions through the console). Thus, to see how the script for a level will flow, you must locate the main() function and read from there.
You can omit the semicolon, parentheses, and also the quotes if your string doesn't have any spaces in it:


Note that the optional [[global]] folder is also loaded for all levels, but this code cannot run on its own unless you edit another function that does run automatically so that it calls a function in a global BSL file.
dmsg Hello


==Logic==
Similarly, here's the formal syntax for a snippet of code:
:''See [[BSL:Statements]] for details.''
In order to react to various conditions, you need branching logic, which basically boils down to an if-else statement in this form:


  if (value1 operator value2)
  func void some_function(void)
  {
  {
      
     var int a;
}
    a = 4;
else
    sleep(60);
{
    if (a eq 4)
      
    {
      dprint("Hello");
     }
  }
  }


To explain the above:
The same code would look like this in the weak syntax:
*The arrangement of braces and whitespace is somewhat flexible, but this is the standard style used in most places and is considered to be the most readable style.
*You may not need the "else" statement, in which case simply omit it.
*<tt>value1</tt> and <tt>value2</tt> can be variables or constants. <tt>operator</tt> refers to one of the relational operators in BSL (see "Operators" below). A typical "if" statement would look like...


  if (counter eq 3) # "if counter's value is equal to three, do this..."
  func void some_function(void)
  {
  {
     # some code here
     var int a;
    a = 4
    sleep 60
    if (a eq 4)
    {
      dprint "Hello"
    }
  }
  }


...where counter is a variable declared beforehand (see "Variables" below). You can also test multiple conditions at once in an "if" statement.
Notice that parentheses are always needed with "if" statements and semicolons are always needed on variable declarations. Note that using the strong syntax avoids certain weird aspects of BSL, and that mixing aspects of strong and weak syntax can cause errors (see the Manual's [[BSL:Manual#Old vs. new syntax|Old vs. new syntax]] section for details).


==Operators==
===Comments===
:''See [[BSL:Operators]] for details.''
Comments are marked with the pound sign:
We're all familiar with the four basic arithmetical operations: addition, subtraction, multiplication and division. Well, BSL only has the first two :-) They're the "+" and "-" symbols, as you would expect. Example:


  counter = counter + 1 # increases counter's value by one
  var int a = 0; # this global is also modified in my_cutscenes.bsl


To compare two values, you use relational operators, like this:
==Reserved words==
===Declaration===
You always need to use "var" when declaring a variable and "func" when defining a function:


  if (counter < 3)
  var int a = 0;
func int get_enemy_count(void)


==Types==
Functions do not need to be defined or declared above the place in the code where they are called, unlike in C.
:''See [[BSL:Types]] for details.''


When declaring a variable or a function, you must specify the type of data it contains or returns:
===Type specification===
BSL does not support weak typing. You need to specify your types when making declarations, as seen in the above examples. You can choose from "bool" (buggy, so not recommended), "int", "float" (rarely useful because of BSL's limited math operations), and "string". As with C, you use "void" to mean "no type" when defining functions.


var int x;
===Conditional===
func int my_func(void)
BSL supports standard if/else statements, and you can use "and" and "or" to test compound conditions:
{...}


You can choose from "bool" (can be true/false or 1/0), "int" (can be any whole number), "float" (a value with a decimal point), or "string" (some text).
if ((a < b) and (c > d))
{
    ...
}
else if (a < 0)
{
    ...
}
else
{
    ...
}


==Functions==
Beware of a bug in BSL where variable assignments under an "if" statement will fire even when the "if" condition is false. See the Manual page's [[BSL:Manual#Conditional|Conditional]] section for details.
:''See [[BSL:Functions]] for details.''
 
Unlike C, functions do not need to be declared or defined before they are called. Functions are defined by starting with the keyword "func", then giving the type of data (see "Types" above) that the function returns, then the name of the function. After that, any parameters it receives should be listed within parentheses. Finally, the actual code for the function should be given within curly braces, like so:
===Flow interrupt===
There is no "goto" statement in BSL, nor any loop controls like "continue" or "break" (since there are no proper loops!). There's a "return" keyword in BSL, but a "return" inside of an "if" statement will fire regardless of whether the statement evaluates to true or false. So you only use "return" to return data at the end of the function, not to exit early (see the [[#Functions|Functions]] section).


func int my_awesome_function(int some_input)
There's also a "sleep" command that pauses BSL execution; you pass it a number in ticks:
{
    var some_output = some_input + 5;
    return some_output;
}


Now that it is defined, we can call it from anywhere in the BSL for the same level by using this invocation:
sleep(60); # wait for one second


var result = my_awesome_function(counter); # sets "result" to the the value of "counter" plus 5
===Loop===
There's no loop keyword like "for" or "while" in BSL, but you can kind of get a loop using one of two methods. First, you can call a function recursively, but BSL has a short stack, so don't expect to get more than four levels deep. If you just want a loop and not recursion, then you can avoid recursion and the related stack limitation by "sleep"ing for a tick or more, and then "fork"ing the call that would otherwise be recursive. See [[BSL:Snippets]] for an example that also makes up for the missing multiplication operator in BSL.


Note that (1) we can set a variable to the result (see "Variables below) and then use that value elsewhere, and (2) the name of the variable we pass in to the function does not have any relation the name that the function uses for that value internally. That's because we might simply desire to pass a constant number to the function:
Second, you could use schedule-repeat-every:


  var result = my_awesome_function(3);
  schedule some_function() repeat 50 every 20;


No matter what, the value passed in will be called "some_input" inside the function.
...or schedule-at:


==Variables==
schedule some_function() at 15;
:''See [[BSL:Variables]] for details.''
schedule some_function() at 30;
schedule some_function() at 45;
...


You've already seen some example of variable declaration. One more thing to be aware of is that variables can be initialized upon declaration:
Just be aware that the BSL will continue executing without waiting for this loop to finish.  Also, there is no way to exit the loop early, but some_function() could simply refuse to perform its task if a global variable has changed to false, simulating a loop exit.


var int y = 9;
===Multi-threading===
BSL doesn't have robust multi-threading, but you can sort of hack your own solution using "fork" or "schedule". Please see the Manual's [[BSL:Manual#Concurrency|Concurrency]] section for examples.


or not:
==Operators==
Like some other languages, BSL differentiates between checking for equivalency ("eq") and setting equivalency ("="):


  var int y;
  if (counter eq 3) ...
i = 4;


In the second case, "y" is set automatically to zero.
BSL's operators are pretty standard stuff:
+ -
eq ne < > <= >=
and or !


When declaring variables, it's important to be aware of scope. The scope is the range of the BSL script within which the variable can be referred to. If a variable is declared with global scope...
But you'll note that there is no operator for multiplying or dividing. You'll need to create your own loop with addition and subtraction to perform that kind of math.


func some_function
==Data types==
{...}
You can choose from "void", "bool", "int", "float", and "string" (with "void" only allowed when defining a function). The "bool" type is buggy in Windows Oni, so use of "int" is recommended instead.


  var int y = 0;
  var int a = 1;
# see the "Functions" section below on how to use a data type keyword when defining a function


func another_function
The "int" type is signed 32-bit. See the Manual's [[BSL:Manual#Data types|Data types]] section to learn about various limitations on math between different data types in BSL.
{...}


...then it can be accessed from both some_function and another_function, and any other function in the level's BSL files, for that matter. If it is declared with function scope...
==Functions==
As mentioned above, functions do not need to be declared or defined before they are called. Defining and calling a function looks exactly like C, except for the "func" keyword in the definition:


  func another_function
a = get_enemy_count(0);<br />
  func int get_enemy_count(int count_dead)
  {
  {
     var int y = 0;
     ...
    return(count);
  }
  }


...then it can only be accessed within that function. If it is declared with block scope...
Once again, please see the Manual's [[BSL:Manual#Functions|Functions]] section to learn about concurrent and recursive calling.


  func another_function
==Variables==
{
As usual, variables can be explicitly initialized:
    if (...)
 
    {
  var int y = 9;
      var int y = 0;
 
      ...
or not:
    }
 
}
var int y;
 
In the second case, "y" is automatically initialized to zero.
 
Variables will have global scope if declared outside of a function.


...then only other code inside the "if" block can access it.
==Built-in functions and variables==
Like any game, Oni provides access to a number of hardcoded functions and global variables that can be used to alter the game environment. They are listed on [[BSL:List]], and grouped by common task in the [[:Category:Scripting tasks|Scripting tasks]] category.


[[Category:BSL syntax]]
[[Category:BSL docs]]

Revision as of 14:57, 11 August 2018

This page gives a brief look at BSL, Oni's scripting language. For those with scripting or programming experience, BSL's syntax and concepts will be very familiar, but BSL's feature set is simpler than most scripting languages. For details on any aspect of the language, as well as documentation of potentially-serious quirks in certain features of the language, read the BSL Manual.

Files

When Oni loads a level, it also loads and parses all .bsl files in the folder in IGMD which contains that level's scripts (the name of this folder being specified by the level's ONLV resource). Like C, the code automatically begins running with the function called "main" at the time of level-load, regardless of which .bsl file it is found in (the convention in Oni's scripts is to place it in a file called *_main.bsl).

Unlike C, there are other "entry points" in the code. For instance, characters can call script functions upon death and trigger volumes can call functions when they are entered or exited. See CHAR, BINA CONS, BINA DOOR, NEUT, and TRGV for all known places in the game data that can trigger BSL functions.

Note that the optional global folder is also loaded for all levels, but any function found in a .bsl file in global/ will be stranded, only accessible by developer console, unless it is called by a function in a level script or by one of the above types of game data in that level.

Syntax

Statements

BSL supports strong and weak syntax in some ways. Here's a typical statement:

dmsg("Hello");

You can omit the semicolon, parentheses, and also the quotes if your string doesn't have any spaces in it:

dmsg Hello

Similarly, here's the formal syntax for a snippet of code:

func void some_function(void)
{
   var int a;
   a = 4;
   sleep(60);
   if (a eq 4)
   {
      dprint("Hello");
   }
}

The same code would look like this in the weak syntax:

func void some_function(void)
{
   var int a;
   a = 4
   sleep 60
   if (a eq 4)
   {
      dprint "Hello"
   }
}

Notice that parentheses are always needed with "if" statements and semicolons are always needed on variable declarations. Note that using the strong syntax avoids certain weird aspects of BSL, and that mixing aspects of strong and weak syntax can cause errors (see the Manual's Old vs. new syntax section for details).

Comments

Comments are marked with the pound sign:

var int a = 0; # this global is also modified in my_cutscenes.bsl

Reserved words

Declaration

You always need to use "var" when declaring a variable and "func" when defining a function:

var int a = 0;
func int get_enemy_count(void)

Functions do not need to be defined or declared above the place in the code where they are called, unlike in C.

Type specification

BSL does not support weak typing. You need to specify your types when making declarations, as seen in the above examples. You can choose from "bool" (buggy, so not recommended), "int", "float" (rarely useful because of BSL's limited math operations), and "string". As with C, you use "void" to mean "no type" when defining functions.

Conditional

BSL supports standard if/else statements, and you can use "and" and "or" to test compound conditions:

if ((a < b) and (c > d))
{
   ...
}
else if (a < 0)
{
   ...
}
else
{
   ...
}

Beware of a bug in BSL where variable assignments under an "if" statement will fire even when the "if" condition is false. See the Manual page's Conditional section for details.

Flow interrupt

There is no "goto" statement in BSL, nor any loop controls like "continue" or "break" (since there are no proper loops!). There's a "return" keyword in BSL, but a "return" inside of an "if" statement will fire regardless of whether the statement evaluates to true or false. So you only use "return" to return data at the end of the function, not to exit early (see the Functions section).

There's also a "sleep" command that pauses BSL execution; you pass it a number in ticks:

sleep(60); # wait for one second

Loop

There's no loop keyword like "for" or "while" in BSL, but you can kind of get a loop using one of two methods. First, you can call a function recursively, but BSL has a short stack, so don't expect to get more than four levels deep. If you just want a loop and not recursion, then you can avoid recursion and the related stack limitation by "sleep"ing for a tick or more, and then "fork"ing the call that would otherwise be recursive. See BSL:Snippets for an example that also makes up for the missing multiplication operator in BSL.

Second, you could use schedule-repeat-every:

schedule some_function() repeat 50 every 20;

...or schedule-at:

schedule some_function() at 15;
schedule some_function() at 30;
schedule some_function() at 45;
...

Just be aware that the BSL will continue executing without waiting for this loop to finish. Also, there is no way to exit the loop early, but some_function() could simply refuse to perform its task if a global variable has changed to false, simulating a loop exit.

Multi-threading

BSL doesn't have robust multi-threading, but you can sort of hack your own solution using "fork" or "schedule". Please see the Manual's Concurrency section for examples.

Operators

Like some other languages, BSL differentiates between checking for equivalency ("eq") and setting equivalency ("="):

if (counter eq 3) ...
i = 4;

BSL's operators are pretty standard stuff:

+ -
eq ne < > <= >=
and or !

But you'll note that there is no operator for multiplying or dividing. You'll need to create your own loop with addition and subtraction to perform that kind of math.

Data types

You can choose from "void", "bool", "int", "float", and "string" (with "void" only allowed when defining a function). The "bool" type is buggy in Windows Oni, so use of "int" is recommended instead.

var int a = 1;
# see the "Functions" section below on how to use a data type keyword when defining a function

The "int" type is signed 32-bit. See the Manual's Data types section to learn about various limitations on math between different data types in BSL.

Functions

As mentioned above, functions do not need to be declared or defined before they are called. Defining and calling a function looks exactly like C, except for the "func" keyword in the definition:

a = get_enemy_count(0);
func int get_enemy_count(int count_dead) { ... return(count); }

Once again, please see the Manual's Functions section to learn about concurrent and recursive calling.

Variables

As usual, variables can be explicitly initialized:

var int y = 9;

or not:

var int y;

In the second case, "y" is automatically initialized to zero.

Variables will have global scope if declared outside of a function.

Built-in functions and variables

Like any game, Oni provides access to a number of hardcoded functions and global variables that can be used to alter the game environment. They are listed on BSL:List, and grouped by common task in the Scripting tasks category.