BSL:Manual: Difference between revisions

Oni's scripting language is called [[BSL]]. Like any typical scripting or programming language, BSL scripts consist of plain-text files which employ branching logic and various operators according to certain rules of syntax in order to process data using functions that act upon variables. If any of those terms are not familiar to you now, keep reading. If you found that sentence boringly obvious, then you should be experienced enough to get by with [[BSL:Introduction]].

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). The code automatically begins running with the function called "main", regardless of which .bsl file it is found in (Oni's scripts always place it in a file ending in "_main.bsl"). The code then flows through whichever functions are called by "main". 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.

However, besides the "main" entry point in a level's BSL scripting, there are types of game data which store function names that are to be called upon certain events. 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 there will be stranded and only accessible by console unless you edit a function in some level's existing BSL file so that it calls your global function.

As with natural languages such as English, there are rules about punctuation, spacing, and word order in BSL.

All code consists of discrete statements. These statements can be gathered into larger structures to create more efficient programs.

BSL accepts 2 statement separators: the semicolon (;) and the linebreak. The following pieces of code are equivalent:

The third example is in old-style syntax, which is discussed under [[#Old vs. new syntax|Old vs. new syntax]].

Compound statements are groups of statements held together by a pair of curly braces:

  {

  }

The purpose of doing this is to group some statements under either a function declaration (see [[#Declaration|Declaration]]) or an "if" statement (see [[#Conditional|Conditional]]). Such a group of statements is referred to as a block, and is also said to be in a scope. Traditionally in programming, anything inside a certain level of shared braces can be seen from elsewhere within those braces, or from within a scope inside that scope, but not from a scope outside that scope. This allows careful management of which code can alter which data. In BSL's case, there are certain issues with scope not being respected (see the [[#if|if statement]] section). Variables outside of all scopes (such as functions) are referred to as "globals".

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

Do not using trailing comments when not ending statements with semicolons (see [[#Old vs. new syntax|Old vs. new syntax]] for explanation).

In documentation outside of source code or script files, such as this page, comments are sometimes used to tell the reader something in a way that doesn't break the actual code, if the user should type it in exactly as it appears, comments and all.

This dual syntax can make it more complicated to talk about the language, and you can also generate errors if you accidentally mix syntax. For instance, if you try to end a function call with a semicolon, but you don't use a C-style function call...

There are other aspects of the language which are flexible, and yet not connected to the old-style/new-style division. For instance, the quotes around "Hello" can be left out in both syntax versions of the above calls to dprint() and dmsg(). You can also omit stating the type and parameters of a function (with "void" being assumed in their absence). You also do not need to enclose code after an if/else statement in curly braces if there is only a single line. None of these syntax choices are in conflict with the "new style" syntax.

Before using a function or a variable for the first time, you need to declare its name and data type.

See [[#Variables|Variables]] for details on declaring variables.

See [[#Functions|Functions]] for details on declaring functions.

When declaring a variable or defining a function, you need to state what type of data is contained in that variable or what kind the function works with.

Besides "void" (used in function definitions to indicate "no type"), these are the types of data that can be assigned to variables, passed to functions, and returned by functions. See [[#Data types|Data types]] for details on the types.

The condition in the parentheses needs to evaluate to "true" or "false". For examples of operators, see [[#Operators|Operators]].

The condition can technically also evaluate to an int value, which then is converted to true/false:

  if (8 - 8) # evaluates to false because it is zero

  if (8 - 7) # evaluates to true because it is non-zero

Here, "spawn_considered" will be set to true regardless of whether the "if" condition was true and spawn_enemy_at_flag() was run. Though it's nice to save the vertical space, the danger in omitting braces is writing something like this:

That indentation on "spawn_considered" is misleading; when glancing at this code, you might expect that "spawn_considered" only is changed if "a" is greater than zero. It could be that you even intended to add that line to the "if" statement but forgot to add braces. Always using braces around an "if" statement's body will prevent that mistake.

Be aware that, even ''with'' braces, BSL does not always respect scope for blocks of code under "if" statements; for instance, a "return" statement will fire even if the surrounding "if" condition is false (see [[#Flow interrupt|Flow interrupt]] for an example). An even more alarming example of bad scope is this:

One very handy feature that you also won't see in Oni's game scripts is that you can use the logical operators "and" and "or" to string together multiple conditions:

Often, programmers only use "else if" statements to save some CPU cycles. For instance, if you had a long string of "if" statements to handle different possible values for a variable, why should they all be evaluated once you have already found the one that is true? Imagine the above example, but with 30 possible values for "error". In reality, you won't find much benefit in trying to save cycles with BSL. However, "else if" can also simplify logic:

In checking the condition of "n" and "d" in this example, we have to keep checking after the second statement whether "d" is greater than 1; otherwise, multiple "if" statements could evaluate to true and execute their code, but we only want to act on one of these possible situations. Using "else if" allows us to be confident that only one statement can run:

Notice how we can shorten the logical tests without losing anything. "d" is still implicitly required to be above zero in statements 2-4, or else they will not even be evaluated.