Jump to content

BSL:Introduction: Difference between revisions

BSL:Introduction (view source)

Revision as of 00:10, 4 February 2024

145 bytes removed ,  4 February 2024
m
wording and section link improvements; don't link to the unfinished BSL listing project
(this was moved to modding errors)
m (wording and section link improvements; don't link to the unfinished BSL listing project)
 
Line 1: Line 1:
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]].
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 full [[BSL:Manual|BSL Manual]].
{{TOClimit|2}}
{{TOClimit|2}}
==Files==
==Files==
Line 6: Line 6:
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.
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.
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==
==Syntax==
===Statements===
===Statements===
BSL supports strong and weak syntax in some ways. Here's a typical statement:
BSL offers the choice of a strong and weak syntax in some contexts. Here's a typical statement…


  dmsg("Hello");
  dmsg("Hello");


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


  dmsg Hello
  dmsg Hello
Line 44: Line 44:
  }
  }


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).
Notice that parentheses are always needed with "if" statements and semicolons are always needed on variable declarations. You will probably find the strong syntax to be more consistent and safe to use than the weak syntax. Be aware that that mixing strong and weak syntax in one file can cause errors (see {{SectionLink|BSL:Manual|Old vs. new syntax}} for details).


===Comments===
===Comments===
Line 61: Line 61:


===Type specification===
===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.
BSL does not support weak typing. You need to specify the type 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===
===Conditional===
Line 79: Line 79:
  }
  }


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.
Beware of a bug in BSL where variable assignments under an "if" statement will fire even when the "if" condition is false. See {{SectionLink|BSL:Manual|Conditional}} 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 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).
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. Thus you can only use "return" to return data at the end of the function, not to exit early (see {{SectionLink||Functions}}).


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 89: Line 89:


===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 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.
There's no loop keyword like "for" or "while" in BSL, but you can create 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. 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:
Second, you could use schedule-repeat-every:
Line 102: Line 102:
  ...
  ...


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.
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===
===Multithreading===
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.
BSL doesn't have a robust solution, but you can perform a certain amount of multithreading using "fork" or "schedule". Please see {{SectionLink|BSL:Manual|Concurrency}} for examples.


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


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


Line 118: Line 119:
  and or !
  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.
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==
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.
You can choose from "void", "bool", "int", "float", and "string" (but "void" is 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;
  var int a = 1;
  # see the "Functions" section below on how to use a data type keyword when defining a function
  # 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 [[BSL:Manual#Data types|Data types]] section to learn about various limitations on math between different data types in BSL.
The "int" type is signed 32-bit. See {{SectionLink|BSL:Manual|Data types}} to learn about various limitations on math between different data types in BSL.


==Functions==
==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:
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);<br />
  a = get_enemy_count(0);<br />
Line 138: Line 139:
  }
  }


Once again, please see the Manual's [[BSL:Manual#Functions|Functions]] section to learn about concurrent and recursive calling.
Once again, please see {{SectionLink|BSL:Manual|Functions}} section to learn about concurrent and recursive calling.


==Variables==
==Variables==
Line 154: Line 155:


==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 alter the game environment. They are listed on [[BSL:List]], and grouped by common task in the [[:Category:Scripting tasks|Scripting tasks]] category.
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:Functions]] and [[BSL:Variables]].


[[Category:BSL docs]]
[[Category:BSL docs]]
Retrieved from "https://wiki.oni2.net/Special:MobileDiff/42277"