OniGalore

BSL:Manual: Difference between revisions

BSL Discussion

BSL:Manual (view source)

Revision as of 03:58, 14 December 2023

2,482 bytes added ,  14 December 2023
elaboration on recursion and forking; brought over warning about dprint/dmsg from BSL:Functions
m (uhhhhhh oops)
(elaboration on recursion and forking; brought over warning about dprint/dmsg from BSL:Functions)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
Oni's level scripts are written in BFW Scripting Language, or [[BSL]]. A scripting language allows you to create a set 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 the [[BSL:Introduction|Introduction]] page, a sort of quick reference. This Manual page, by contrast, provides both a thorough and newbie-friendly introduction to the language and also documents every known bug in the language, which a modder writing a complex script will want to know about.
Oni's level scripts are written in {{Hover|BFW|text=BungieFrameWork, the underlying layer of the game engine.}} Scripting Language, or [[BSL]]. A scripting language allows you to create a set 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 the [[BSL:Introduction|Introduction]] page, a sort of quick reference. This Manual page, by contrast, provides both a thorough and newbie-friendly introduction to the language and also documents every known bug in the language, which a modder writing a complex script will want to know about.
{{TOClimit|3}}
{{TOClimit|3}}
==Script files==
==Script files==
Line 38: Line 38:
  dmsg("Statement 2")
  dmsg("Statement 2")


The third example is partly in old-style syntax, which is discussed under the [[#Old vs. new syntax|Old vs. new syntax]] section.
The third example is partly in old-style syntax, which is discussed under {{SectionLink||Old vs. new syntax}}.


===Compound statements===
===Compound statements===
Line 49: Line 49:
  <b>}</b>
  <b>}</b>


The purpose of doing this is to place statements under either a function declaration (see the [[#Declaration|Declaration]] section) or an "if" statement (see the [[#Conditional|Conditional]] section). Such a group of statements is referred to as a "block", and sometimes also defines a "scope". Traditionally in programming, anything inside a certain scope can be seen from elsewhere within that scope, 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, however, there are certain issues with scope not being respected (see the [[#if|if statement]] section). Variables outside of all scopes (including functions) are referred to as "globals".
The purpose of doing this is to place statements under either a function declaration (see {{SectionLink||Declaration}}) or an "if" statement (see {{SectionLink||Conditional}}). Such a group of statements is referred to as a "block", and sometimes also defines a "scope". Traditionally in programming, anything inside a certain scope can be seen from elsewhere within that scope, 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, however, there are certain issues with scope not being respected (see {{SectionLink||if}}). Variables outside of all scopes (including functions) are referred to as "globals".


===Comments===
===Comments===
Line 64: Line 64:
  }
  }


Do not use a trailing comment unless you end the statement with a semicolon (see the [[#Old vs. new syntax|Old vs. new syntax]] section for explanation).
Do not use a trailing comment unless you end the statement with a semicolon (see {{SectionLink||Old vs. new syntax}} for explanation).


In documentation outside of source code or script files, such as this page's BSL samples, comments are sometimes used to tell the reader something in a way that won't break the actual code if the user copies the whole block of text into a script file, comments and all.
In documentation outside of source code or script files, such as this page's BSL samples, comments are sometimes used to tell the reader something in a way that won't break the actual code if the user copies the whole block of text into a script file, comments and all.
Line 96: Line 96:


===Coding style===
===Coding style===
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 (see the [[#Functions|Functions]] section if you need further explanation). You also do not need to use curly braces to enclose code that falls under an if/else statement if there is only a single line of code intended to be in that scope (see the [[#Conditional|Conditional]] section for examples). None of these syntax choices are in conflict with the "new style" syntax.
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 (see {{SectionLink||Functions}} if you need further explanation). You also do not need to use curly braces to enclose code that falls under an if/else statement if there is only a single line of code intended to be in that scope (see {{SectionLink||Conditional}} for examples). None of these syntax choices are in conflict with the "new style" syntax.


Additionally, you can use whitespace and newlines in different ways:
Additionally, you can use whitespace and newlines in different ways:
Line 118: Line 118:


==Variables==
==Variables==
A variable is a storage space in memory for a value that you will want to access at different times, and perhaps change over time as well.
A variable is a named storage space in memory for a value that you will want to access at different times, and perhaps change over time as well. The name of the variable is expected to start with a letter, but it can contain numbers and the underscore (<code>_</code>) at any point after that. A variable name cannot be the same as one of BSL's [[#Reserved words|reserved words]], e.g. an int named "return", and obviously it cannot share a name with any built-in or declared function either.


===Declaring===
===Declaring===
When declaring a variable, the statement must begin with "var" and the type of the variable...
When declaring a variable, the statement must begin with "var" and the type of the variable:


  var int i = 0;
  var int i = 0; # declare a variable named "i" and initialize it to the value zero
 
You don't have to initialize variables (set them to a value when declaring them), but it's usually a good idea. If you don't initialize, the engine will use a default value: "false" for bools, "0" for ints and floats, and "" (an empty string) for strings.


===Accessing===
===Accessing===
...but not when getting or setting its value later:
After a variable has been declared, you don't use "var" or the type of the variable when getting or setting its value:


if (i eq 0)...
  i = 4;
  i = 4;
if (i eq 0)
    [...]


==Data types==
==Data types==
When declaring a variable or a function (more on this under the [[#Functions|Functions]] and [[#Variables|Variables]] sections), you must specify the type of data it contains, accepts, or returns. You can choose from "bool" (can be "true" or "false", but see warning under the "bool" section), "int" (can be any whole number), "float" (a value with a decimal point), or "string" (some text).
When declaring a variable (more on this under {{SectionLink||Variables}}), you must specify the type of data it contains. When declaring a function (more on this under {{SectionLink||Functions}}), you can optionally specify the type of data it accepts and returns. You can choose from "bool" (can be "true" or "false", but see warning under {{SectionLink||bool}}), "int" (can be any whole number), "float" (a value with a decimal point), or "string" (some text).


  var '''int''' x;
  var '''int''' x;
Line 144: Line 147:


===void===
===void===
See the [[#Functions|Functions]] section. Variables cannot be type "void".
See {{SectionLink||Functions}} for the meaning of "void". Variables cannot be of type "void".


===bool===
===bool===
'''(Note: See warning at bottom of this section; the bool type is not recommended for variables.)''' A [[wp:Boolean data type|Boolean]] number has one of two possible states. Thus, a bool can be assigned a value with the keywords "true" and "false".
'''(Note: See warning at bottom of this section; the bool type is not recommended for variables.)''' A [[wp:Boolean data type|Boolean]] number has one of two possible states. Thus, a bool can be assigned a value with the keywords "true" and "false".


  var bool example = true;
  var '''bool''' example = true;
  func bool are_we_there_yet(void)
  func '''bool''' are_we_there_yet(void)
  {
  {
     ...
     ...
Line 160: Line 163:
  if (example eq true)
  if (example eq true)


However, Windows Oni will fail to evaluate bare references to bool variables, and testing indicates the possibility of other bugs existing in Windows Oni's handling of bools. Additionally, Bungie West uses virtually no bool variables in Oni's scripts (though they do use built-in functions that return bool values). Since ints are handled much more reliably, it's recommended to use int for variables instead of bool; the values 1 and 0 can represent "true" and "false".
However, Windows Oni will fail to evaluate bare references to bool variables, and testing indicates the possibility of other bugs existing in Windows Oni's handling of bools. Additionally, Bungie West uses virtually no bool variables in Oni's scripts (though they do use built-in functions that return bool values). Since ints are handled much more reliably, it's recommended to use int for variables instead of bool; the values 1 and 0 can be used to represent "true" and "false".


===int===
===int===
A 32-bit signed [[wp:Integer|whole number]]; that is, it can be positive, negative or zero, with a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648.
A 32-bit signed [[wp:Integer|whole number]]; it can be positive, negative or zero, with a maximum value of 2,147,483,647 and a minimum value of -2,147,483,648.


  var int example = -1000;
  var '''int''' example = -1000;
  func int get_enemy_count(void)
  func '''int''' get_enemy_count(void)
  {
  {
     ...
     ...
  }
  }


Note that the number wraps around, which means that once it passes its maximum or minimum value, it starts over from the other end. For instance, the function...
Note that the value wraps around, which means that once it passes its maximum or minimum value, it starts over from the other end. For instance, the function...


  func void overflow_test(void)
  func void overflow_test(void)
Line 179: Line 182:
  }
  }


...will print "int32: 2147483647" to screen when it runs.
...will print the positive number "int32: 2147483647" to screen when it runs.


Adding a float or a bool to an int yields odd and very high results, even if the float or bool could in theory be seamlessly converted to an int. Assigning a float to an int correctly assigns the truncated integer to the int. Assigning a bool to an int works correctly, the bool being treated as either 0 or 1.
Adding a float or a bool to an int yields odd and very high results, even if the float or bool could in theory be seamlessly converted to an int. Assigning a float to an int correctly assigns the truncated integer to the int. Assigning a bool to an int works correctly, the bool being treated as either 0 or 1.
Line 186: Line 189:
A [[wp:Floating-point arithmetic|floating-point]] number. Bungie West actually never used floats in their scripts for Oni, which explains why there are certain rough aspects to them. For instance, floats are limited to six decimal places of precision:
A [[wp:Floating-point arithmetic|floating-point]] number. Bungie West actually never used floats in their scripts for Oni, which explains why there are certain rough aspects to them. For instance, floats are limited to six decimal places of precision:


  var float good_example = 10.5; # returns as "10.500000"
  var '''float''' good_example = 10.5; # returns as "10.500000"
  var float too_precise = 3.141592653589793; # returns as "3.141593"
  var '''float''' too_precise = 3.141592653589793; # returns as "3.141593"


Thus, adding a value below the sixth decimal place to a float will have no effect, e.g. 3.000000 + 0.0000001 = 3.000000. Additionally, adding an int (or a bool) to a float has no effect:
Thus, adding a value below the sixth decimal place to a float will have no effect, e.g. 3.000000 + 0.0000001 = 3.000000. Additionally, adding an int value (or a bool value) to a float has no effect:


  func float test_float_addition(void)
  func float test_float_addition(void)
Line 208: Line 211:


===string===
===string===
A sequence of textual characters. BSL does not provide any explicit means for manipulating strings (concatenation, trimming, etc.), though see below for a simple trimming hack. It also does not provide a reliable method of string comparison, though perhaps due to a bug rather than an oversight (see [[BSL:String comparison|HERE]] for more information).
A sequence of textual characters. BSL does not have any built-in way of performing the string manipulations that you would expect from a scripting language, such as concatenation and trimming, though see below for a simple trimming hack. It also does not provide a reliable method of string comparison (see [[BSL:String comparison|HERE]] for a detailed examination).


  var string example = "hello";
  var '''string''' example = "hello";


Trying to give a string a non-textual value (bool/int/float) gives the error "illegal type convertion" (sic). Trying to add two strings together simply crashes the game, rather than concatenating them as it would in some other languages. Adding a float to a string crashes too. Bools have no effect whatsoever.
Trying to give a string a non-textual value (bool/int/float) gives the error "illegal type convertion" (sic). Trying to add two strings with a '+' operator crashes the game, rather than concatenating them as it would in some other languages. Adding a float to a string crashes too. Bools have no effect whatsoever.


Trying to add an int value to a string creates some cool and unexpected results. For instance, adding a number between 5 and 11 removes the first character from the string. A number greater than or equal to 12 removes the first two, and so on. Subtraction does not yield the reverse effect, even if you try it with the maximum int value (in which case, Oni crashes). Subtracting numbers can, however, result in printing random strings from Oni's memory, such as BSL function names!
Trying to add an int value to a string creates some cool and unexpected results. For instance, adding a number between 5 and 11 removes the first character from the string. A number greater than or equal to 12 removes the first two, and so on. Subtraction does not yield the reverse effect, even if you try it with the maximum int value (in which case Oni crashes). Subtracting numbers can, however, result in printing random strings from Oni's memory, such as BSL function names!


"(null)" is the value that strings assume when they have not been given a value yet; it cannot be assigned to a string manually.
"(null)" is the value that strings assume when they have not been given a value yet; it cannot be assigned to a string manually.
Line 238: Line 241:
|}
|}


Note that "=" is '''not''' for checking if one entity is equal to another (see "eq" below for that).
Note that "=" is '''not''' for checking if one entity is equal to another (see "eq" under {{SectionLink||Relational}} for that).


===Arithmetical===
===Arithmetical===
These operations do not change the numbers that the operators act upon; they merely provide a resulting number for your use. Note that there is no operator for multiplication or division. Bungie West was only concerned with creating enough scripting power to drive Oni, and they did not need "higher math" for this. See the [[#Data types|Data types]] section to learn the details of how math works between different data types.
These operations do not change the numbers that the operators act upon; they merely provide a resulting number for your use. Note that there is no operator for multiplication or division. Bungie West was only concerned with creating enough scripting power to drive Oni, and they did not need "higher math" for this. See {{SectionLink||Data types}} to learn the details of how math works between different data types.


{| class="wikitable"   
{| class="wikitable"   
Line 279: Line 282:
  }
  }


Alternatively, you can use the sum operator, which doesn't suffer from this issue:
Alternatively you can use the sum operator, which doesn't suffer from this issue:


  if (5+-6 eq -1)
  if (5+-6 eq -1)
Line 300: Line 303:
| eq
| eq
| Equal to
| Equal to
| Tests if two values are equal. (== does not work)
| Tests if two values are equal.
|-
|-
| ne
| ne
| Not equal to
| Not equal to
| Tests if two values are different. (!= does not work)
| Tests if two values are different.
|-
|-
| >
| >
Line 323: Line 326:
|}
|}


Note: These operators are intended for use with numbers; strings cannot make reliable use of comparators, as explained in the [[#string|string]] section.
Note: These operators are intended for use with numbers; strings cannot make reliable use of comparators, as explained under {{SectionLink||string}}.


===Logical===
===Logical===
Line 333: Line 336:
| !
| !
| Not
| Not
| Logical Not. Reverses the result of a test. "!(some_bool eq true)" is the same as saying "some_bool eq false" or "some_bool ne true".
| Logical Not. Reverses the result of a test.
|-
|-
| and
| and
Line 344: Line 347:
|}
|}


See the [[#if|"if" statement]] section to learn how to use the logical operators.
To illustrate the '!' ("not") operator, the following three lines are equivalent:
!(some_bool eq true)
some_bool eq false
some_bool ne true
 
See {{SectionLink||if}} for detailed examples of using the logical operators.


==Reserved words==
==Reserved words==
Line 355: Line 363:
  '''var''' int a = 0;
  '''var''' int a = 0;


After this, you can refer to the variable merely as "a". See the [[#Variables|Variables]] section for details on declaring variables.
After this, you refer to the variable merely as "a". See {{SectionLink||Variables}} for details on declaring variables.


====func====
====func====
Line 363: Line 371:
  }
  }


Besides this, you can call the function merely by writing "spawn_team", but the proper new-style syntax is "spawn_team();". See the [[#Functions|Functions]] section for details on declaring functions.
After this, you call the function merely by writing its name; "spawn_team" would work, but the proper new-style syntax is "spawn_team();". See {{SectionLink||Functions}} for details on declaring functions.


===Type specification===
===Type specification===
Line 375: Line 383:
  }
  }


Besides "void", which is only used in function definitions (indicating that no data is returned), these are the types of data that can be assigned to variables, passed into functions, and returned by functions. See the [[#Data types|Data types]] section for details.
Besides "void", which is only used in function definitions (indicating that no data is returned), these are the types of data that can be assigned to variables, passed into functions, and returned by functions. See {{SectionLink||Data types}} for details.


===Conditional===
===Conditional===
Line 386: Line 394:
  }
  }


For examples of operators, see the [[#Operators|Operators]] section. A typical example would be:
For examples of operators, see {{SectionLink||Operators}}. A typical example would be:


  if (kills < 10)
  if (kills < 10)
Line 409: Line 417:
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 the script's writer really did want that line to be subject to the "if" statement, but he forgot to add braces. Always using braces around an "if" statement's body, even when it's one line long, will prevent that mistake.
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 the script's writer really did want that line to be subject to the "if" statement, but he forgot to add braces. Always using braces around an "if" statement's body, even when it's one line long, will prevent that mistake.


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


  func void broken_if(void)
  func void broken_if(void)
Line 484: Line 492:
Programmers commonly 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 since typical game scripts are not computationally expensive. However, "else if" can also simplify the flow of logic:
Programmers commonly 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 since typical game scripts are not computationally expensive. However, "else if" can also simplify the flow of logic:


  if (d eq 0)
  if (d eq 10)
     ...
     # special-case code for d being 10
if (d eq 1)
  if ((d ne 10) and (d eq 3))
    ...
     # special-case code for d being 3
  if ((n eq d) and (n > 0) and (d > 1))
  if ((d ne 10) and (d ne 3) and (d > 0))
     ...
     # code for handling any other positive value for d
  if ((n eq 0) and (d > 1))
     ...


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, and 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:
In checking the condition of "d" in this example, we have to keep checking after the first statement whether our previous conditions were not true; if we didn't, multiple "if" statements could evaluate to true and execute their code, and 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:


  if (d eq 0)
  if (d eq 10)
     ...
     # special-case code for d being 10
  else if (d eq 1)
  else if (d eq 3)
     ...
     # special-case code for d being 3
  else if (n eq d)
  else if (d > 0)
    ...
     # code for handling any other positive value for d
else if (n eq 0)
     ...


Notice how we can shorten the logical tests without losing anything. "d" is still implicitly required to be non-zero in statements 2-4, or else they will not even be evaluated.
Thanks to the "else" keyword, "d" is implicitly guaranteed to not be 10 if statement 2's code is being run, and to not be 10 or 3 if statement 3's code is being run.


===Flow interrupt===
===Flow interrupt===
Use these keywords to interrupt the execution of BSL. Note that Bungie West also frequently used these built-in commands to halt the execution of a script until the current or previous command finished: [[chr_animate_block]], [[chr_envanim_block]], [[chr_playback_block]], [[cm_anim_block]], [[cm_interpolate_block]], [[cm_orbit_block]], [[env_anim_block]], [[env_setanim_block]], [[sound_dialog_play_block]].
Use the keywords below to interrupt the execution of BSL. Note that Bungie West also frequently used these built-in commands to halt the execution of a script until the current or previous command finished: [[chr_animate_block]], [[chr_envanim_block]], [[chr_playback_block]], [[cm_anim_block]], [[cm_interpolate_block]], [[cm_orbit_block]], [[env_anim_block]], [[env_setanim_block]], [[sound_dialog_play_block]].


====return====
====return====
Line 523: Line 527:
  }
  }


Yes, "return" is also subject to the scope bug discussed in the [[#Conditional|Conditional]] section above. The statements under "else" will never run. The "return" will actually kick in and the function will exit, even though the surrounding control statement did not evaluate to true.
Yes, "return" is also subject to the scope bug discussed under {{SectionLink||Conditional}}. The statements under "else" will never run. The "return" will actually kick in and the function will exit, even though the surrounding control statement did not evaluate to true.


However, "return" is still useful at the end of a function for returning data to the function that called that one; see the section on [[#Returning|returning function values]].
However, "return" is still useful at the end of a function for returning data to the function that called that one; see {{SectionLink||Returning}}.


====sleep====
====sleep====
Line 537: Line 541:


===Loop===
===Loop===
It is generally desirable in any program to be able to run the same code over and over, such as repeatedly spawning enemies. This is one of BSL's biggest limitations, as it has no conventional loop statement like C's "for" or "while", but there are two indirect methods for looping: (1) use "fork" on a function (see the section on [[#Looping|looping functions]]), and (2) "schedule-at"/"schedule-repeat-every" (see the [[#Concurrency|Concurrency]] section).
It is generally desirable in any program to be able to run the same code over and over, such as repeatedly spawning enemies. This is one of BSL's biggest limitations, as it has no conventional loop statement like C's "for" or "while", but there are two indirect methods for looping: (1) use "fork" on a function (see {{SectionLink||Looping}}), and (2) "schedule-at"/"schedule-repeat-every" (see {{SectionLink||Concurrency}}).


===Multi-threading===
===Multi-threading===
====fork, schedule-at, schedule-repeat-every====
====fork, schedule-at, schedule-repeat-every====
See the [[#Concurrency|Concurrency]] section for the use of these keywords.
See {{SectionLink||Concurrency}} for the use of these keywords.


===Obsolete===
===Obsolete===
Line 551: Line 555:


==Functions==
==Functions==
A function is a block of code that can be accessed repeatedly whenever you want to perform a certain task. As in mathematics, functions can be passed input and can return output, though unlike in mathematics, they do not need to do either of those things in order to be useful, as BSL functions can affect external data by modifying global variables and by calling built-in functions which affect the game environment (see the [[#Built-in commands|Built-in commands]] section).
A function is a block of code that can be accessed repeatedly whenever you want to perform a certain task. As in mathematics, functions can be passed input and can return output, though unlike in mathematics, they do not need to do either of those things in order to be useful, as BSL functions can affect external data by modifying global variables and by calling built-in functions which affect the game environment (see {{SectionLink||Built-in commands}}).


===Defining===
===Defining===
When beginning to define a function, you must begin the line with "func"...
When beginning to define a function, you must start the line with "func"...


  func int prepare_fight(int count, string enemy_name)
  func int prepare_fight(int count, string enemy_name)
Line 582: Line 586:


===Calling===
===Calling===
When you call a function it will execute its statements from top to bottom or until it hits a "[[#Returning|return]]" statement. This means that when you call a second function from inside another function, the second function will be executed until its end and then the rest of the first function will be executed.
When you call a function it will execute its statements from top to bottom or until it hits a "[[#Returning|return]]" statement. This means that when you call a second function from inside another function, the second function will be executed until its end and then the rest of the first function will be executed. You can think of the function calls as nested parentheses, where the innermost statement must close before the next-innermost level can close, and so on. (For example, here is a parenthetical statement (and another one (and one more!) inside of it)).


You do not use "func" when calling a function. You simply use its name:
You do not use "func" when calling a function. You simply use its name:
Line 601: Line 605:


===Recursive calling===
===Recursive calling===
A function can call itself, which is useful for various looping behavior, but a function can only call itself recursively up to about four times. Note that this limit is bypassed if you use "[[#fork|fork]]" to call a function from within itself, but this no longer counts as recursing because the logic will not complete in a predictable inside-to-outside order. For a non-recursive way to loop a function, see the [[#Looping|Looping]] section.
A function can call itself by invoking its own name:
 
var int global_iterator = 0;
func void bad_loop_idea(void)
{
    global_iterator = global_iterator + 1
    dmsg("Calling myself...");
    bad_loop_idea();
}
 
This might seem useful for producing a loop, but a function can only call itself recursively about four times before you hit a limit in BSL and the script fails silently. Open a level with the above code placed in its level script and call bad_loop_idea() from the dev console. After you stop seeing the "Calling myself..." messages, run the command "global_iterator" to query its value and you'll probably get "5", meaning the recursion failed between the fourth and fifth levels.
 
This limit can be bypassed if you use "[[#fork|fork]]" when calling a function from within itself, though this is not technically recursing: the logic will not complete in a predictable inside-to-outside order like our nested parentheses example in the previous section; instead it will run concurrently through all of the forked function calls. This can be very bad if you're trying to get reliable results, however there are ways to mitigate this. For a discussion of looping reliably with "fork", see {{SectionLink||Looping}}.


===Returning===
===Returning===
As mentioned under the [[#Flow interrupt|Flow interrupt]] section, "return" exits the function at that point. Because of the bug documented in that section, you cannot exit early from a function under some logical condition. Since "return" can thus only be placed at the end of a function, there is no point in using it at all unless you are going to pass back a value by placing a variable name after "return":
As mentioned under {{SectionLink||Flow interrupt}}, "return" allows you to exit the function at that point. But because of the bug documented in that section you cannot use "return" conditionally, that is, exit early from a function depending on some logical condition ("if"). Since "return" can thus only be placed at the end of a function, there is no need to use it at all unless you are passing back a value with it like so:


  func int add_ten(int input)
  func int add_ten(int input)
Line 612: Line 628:
  }
  }


You would then use this function to set a variable, as follows:
When a function returns a value, you can use the function to set a variable as follows:


  some_number = add_ten(enemy_count);
  some_number = add_ten(enemy_count);


Function return values can also be used in "if" statements to provide a true/false condition. If you have a function that returns a bool...
Function return values can also be used in "if" statements. If you have a function that returns a bool...


  func bool is_it_safe(void)
  func bool is_it_safe(void)
Line 627: Line 643:
...then it could be called this way in some other function:
...then it could be called this way in some other function:


  if (is_it_safe())
  if (is_it_safe() eq true)
     dprint("It is safe.");
     dprint("It is safe.");
  else
  else
     dprint("It is not safe.");
     dprint("It is not safe.");
Bizarre bug warning: Calling dprint() and dmsg() more than once within a function will produce unexpected results. One of the dprint()/dmsg() calls may become the return value for the function (even if it it's type "void"), or create a return value of 0, and more than two calls also might be ignored.


===Looping===
===Looping===
Line 650: Line 668:
  }
  }


Note that calling the same function again before it finishes running the first time can have undesired effects. Using "sleep" before each call can prevent this overlapping execution. A short function like the example above should not need a "sleep" statement, as the remainder of the function after the "fork" call will complete in the same tick. But the more complex the function, the more ticks you will need to allow for it to complete, requiring "sleep(1);", "sleep(3);", etc. before the "fork" call.
Note that calling the same function again before it finishes running the first time can have undesired effects. Imagine if you have another thread in the code accessing "counter" while increment() is still running in a loop; what value will it have at that moment? Real-world scripting scenarios will be more complex and thus more problematic if multiple concurrent calls to a function are in play at the same time. Using "sleep" before each fork call can prevent this overlapping execution. A short function like the example above should not need a "sleep" statement as the remainder of the function after the "fork" call will complete in the same tick. But the more complex the function, the more ticks you will need to allow for it to complete, requiring "sleep(1);", "sleep(3);", etc. before the "fork" call.
 
An alternate looping method: See the two variants of the "schedule" keyword under "Concurrency" below.


===Concurrency===
===Concurrency===
Line 677: Line 697:
  }
  }


As you can see, you can use forked functions to perform delayed actions without holding up the rest of the script; this not only allows the use of "sleep", but also any built-in functions that hold up BSL by design, like [[chr_wait_animation]].
As you can see, fork-called functions can delay actions within themselves without holding up the rest of the script; this not only allows the use of "sleep" without affecting outside functions, but also any built-in functions that hold up BSL by design, like [[chr_wait_animation]].
 
Also be aware that accidentally calling a nonexistent function using "fork" will crash Oni; when "fork" is not used, BSL will not recognize that the unknown function name represents a function, and thus will not attempt to call it and end up crashing.


Below are two types of uses for the "schedule" keyword. By scheduling a function call that operates on global variables and doesn't run unless a condition is true, you could simulate a slow-acting loop with these keyword sets.
Be aware that accidentally calling a nonexistent function using "fork" will crash Oni; when "fork" is not used, BSL will successfully recognize it as an unknown function and thus will not attempt to call it.


====schedule ... at ...====
====schedule ... at ...====
Line 700: Line 718:
  schedule dprint("Is this annoying yet?") repeat 50 every 20;
  schedule dprint("Is this annoying yet?") repeat 50 every 20;


This is equivalent to the following loop in a C-style programming language:
This is equivalent to the following loop in a C-style language:


  int i = 0;
  int i = 0;
Line 714: Line 732:
  schedule dprint("Is this annoying yet?") repeat 0 every 20; # repeats forever
  schedule dprint("Is this annoying yet?") repeat 0 every 20; # repeats forever


"schedule-repeat-every" can be used in place of recursive functions that call themselves ''n'' times using "fork". For example,
"schedule-repeat-every" can be used in place of recursive functions that call themselves ''n'' times using "fork". For example…


  func void hey(void)
  func void hey(void)
Line 728: Line 746:
  }
  }


can be replaced by:
…can be replaced by…


  func void hey(void)
  func void hey(void)
Retrieved from "https://wiki.oni2.net/Special:MobileDiff/39699...42069"