19,127
edits
BSL:Introduction: Difference between revisions
correcting info on "else if"; comments info belongs under "Syntax"; +links to sections mentioned in Manual and this page; added warning about scope bug
(Introduction is now explicitly aimed at the experienced coder who just wants the short story, not the long story at BSL:Manual) |
(correcting info on "else if"; comments info belongs under "Syntax"; +links to sections mentioned in Manual and this page; added warning about scope bug) |
||
| Line 1: | Line 1: | ||
This page gives a brief look at BSL for those with scripting or programming experience. For those familiar with a typical procedural language like C, BSL's syntax and concepts will be very familiar, but BSL's feature set is stripped down to a degree that is simpler than even most scripting languages. For details on any aspect of the language, look at | This page gives a brief look at [[BSL]], Oni's scripting language, for those with scripting or programming experience. For those familiar with a typical procedural language like C, BSL's syntax and concepts will be very familiar, but BSL's feature set is stripped down to a degree that is simpler than even most scripting languages. For details on any aspect of the language, look at [[BSL:Manual]]. | ||
{{TOClimit|2}} | {{TOClimit|2}} | ||
==Files== | ==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 (Oni's scripts always place it in a file called *_main.bsl). | 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 (Oni's scripts always place it in a file called *_main.bsl). | ||
Note that the optional [[IGMD/global|global]] folder is also loaded for all levels, but any function found in a .bsl file | 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 you edit a function in some level's existing BSL file so that it calls your global function. | ||
==Syntax== | ==Syntax== | ||
===Statements=== | |||
BSL supports strong and weak syntax in some ways. Here's a typical statement: | BSL supports strong and weak syntax in some ways. Here's a typical statement: | ||
| Line 46: | Line 42: | ||
} | } | ||
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 (see the Manual's | 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 (see the Manual's [[BSL:Manual#Old vs. new syntax|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== | ==Reserved words== | ||
| Line 61: | Line 62: | ||
===Conditional=== | ===Conditional=== | ||
BSL supports standard if/else statements, and you can use "and" and "or" to test compound conditions: | |||
if ((a < b) and (c > d)) | if ((a < b) and (c > d)) | ||
{ | { | ||
... | |||
} | |||
else if (a < 0) | |||
{ | |||
... | |||
} | } | ||
else | 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 [[BSL:Manual#Conditional|Conditional]] section for details. | |||
===Flow interrupt=== | ===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 you can't use it except at the end of the function because of a bug in BSL that will fire a "return" inside of an "if" statement regardless of whether the statement evaluates to true or false. So you only use "return" to return data, not to exit early (see | 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 you can't use it except at the end of the function because of a bug in BSL that will fire a "return" inside of an "if" statement regardless of whether the statement evaluates to true or false. So you only use "return" to return data, not to exit early (see the [[#Functions|Functions]] section). | ||
There's also a "sleep" command that pauses BSL execution; you pass it a number in ticks: | There's also a "sleep" command that pauses BSL execution; you pass it a number in ticks: | ||
| Line 82: | Line 87: | ||
===Loop=== | ===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 by | 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 multiply operator in BSL. | ||
Second, you could use schedule-repeat-every: | Second, you could use schedule-repeat-every: | ||
| Line 88: | Line 93: | ||
schedule some_function() repeat 50 every 20; | schedule some_function() repeat 50 every 20; | ||
Just be aware that the BSL will continue executing without waiting for this loop to | Just be aware that the BSL will continue executing without waiting for this loop to finish. | ||
===Multi-threading=== | ===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 section | 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. | ||
==Operators== | ==Operators== | ||
| Line 104: | Line 109: | ||
and or ! | and or ! | ||
But you'll note that there is no operator for multiplying or dividing. | 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== | ==Data types== | ||
| Line 112: | Line 117: | ||
var int a = 1; | var int a = 1; | ||
The "int" type is signed 32-bit. See the Manual's | The "int" type is signed 32-bit. See the Manual's [[BSL:Manual#Data types|Data types]] section to learn about various limitations with math between types in BSL. | ||
==Functions== | ==Functions== | ||
| Line 121: | Line 126: | ||
{ | { | ||
... | ... | ||
return count; | return(count); | ||
} | } | ||
Once again, please see the Manual's | Once again, please see the Manual's [[BSL:Manual#Functions|Functions]] section to learn about concurrent and recursive calling. | ||
==Variables== | ==Variables== | ||
| Line 135: | Line 140: | ||
var int y; | var int y; | ||
In the second case, "y" is | In the second case, "y" is automatically initialized to zero. | ||
Variables can have global scope, if declared outside of a function. | Variables can have global scope, if declared outside of a function. | ||
==Built-in functions and variables== | ==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 write level scripts. They are listed [[BSL:Reference | Like any game, Oni provides access to a number of hardcoded functions and global variables that can be used to write level scripts. They are listed on [[BSL:Reference]], and grouped by common task in the [[:Category:Scripting tasks|Scripting tasks]] category. | ||
[[Category:BSL docs]] | [[Category:BSL docs]] | ||