18,700
edits
BSL:Manual: Difference between revisions
moved up intro text to lede; tweaked section names; added Files section
(new idea: merge all BSL syntax documentation onto one long page; this should be easier than browsing around several interconnected pages) |
(moved up intro text to lede; tweaked section names; added Files section) |
||
| Line 1: | Line 1: | ||
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]]. | |||
{{TOClimit|3}} | {{TOClimit|3}} | ||
==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). 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). Only other functions that are called by main() (and the functions it calls) 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. | |||
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. | |||
==Syntax== | ==Syntax== | ||
As with natural languages such as English, there are rules about punctuation, spacing, and word order in BSL. | |||
===Statements=== | ===Statements=== | ||
All code consists of discrete statements. These statements can be gathered into larger structures to create more efficient programs. | |||
====Statement separators==== | ====Statement separators==== | ||
BSL accepts 2 statement separators: the semicolon (;) and the linebreak. The following pieces of code are equivalent: | BSL accepts 2 statement separators: the semicolon (;) and the linebreak. The following pieces of code are equivalent: | ||
dmsg("Statement 1"); dmsg("Statement 2"); | [[dmsg]]("Statement 1"); dmsg("Statement 2"); | ||
and | and | ||
| Line 107: | Line 114: | ||
See "Functions" below for details on using functions. | See "Functions" below for details on using functions. | ||
=== | ===Type specification=== | ||
:''See [[BSL:Types]] for details.'' | :''See [[BSL:Types]] for details.'' | ||
void, bool, int, float, string | void, bool, int, float, string | ||
| Line 155: | Line 162: | ||
Though "else" is not used in Oni's existing BSL scripts, it seems to work fine. | Though "else" is not used in Oni's existing BSL scripts, it seems to work fine. | ||
===Flow | ===Flow interrupt=== | ||
There is no "goto" statement in BSL, nor any loop controls like "continue" or "break" (since there are no proper loops!). There are, however, "return", and, arguably, "sleep". | There is no "goto" statement in BSL, nor any loop controls like "continue" or "break" (since there are no proper loops!). There are, however, "return", and, arguably, "sleep". | ||
| Line 173: | Line 180: | ||
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. | 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 for returning data to a calling function; see "Functions" below. | |||
====sleep==== | ====sleep==== | ||
| Line 181: | Line 190: | ||
Note that you cannot have a sleep statement in a function that returns a value, probably to avoid variables being changed at unexpected times. | Note that you cannot have a sleep statement in a function that returns a value, probably to avoid variables being changed at unexpected times. | ||
=== | ===Loop=== | ||
BSL has no "for" or "while" statement, but "schedule-repeat-every" (see "Multi-threading" below) can be used as a poor-man's loop (as long as you realize that there's no way to exit early). | BSL has no "for" or "while" statement, but "schedule-repeat-every" (see "Multi-threading" below) can be used as a poor-man's loop (as long as you realize that there's no way to exit early). | ||
| Line 228: | Line 237: | ||
You'll note that there is no 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. | You'll note that there is no 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 "Data types" to learn the details of how operators work between different data types. | |||
===Relational=== | ===Relational=== | ||
| Line 413: | Line 422: | ||
some_function(num_heroes, enemy); | some_function(num_heroes, enemy); | ||
==== | ====Concurrency==== | ||
When you call a function, all the code inside that function will finish running before giving control back to the calling function; that is, unless you use one of the following keyword sets to run parallel "threads" of BSL at the same time. Unlike robust programming languages, there is very little control over BSL's version of "multi-threading", so see the caveats at the end of the "fork" section. | When you call a function, all the code inside that function will finish running before giving control back to the calling function; that is, unless you use one of the following keyword sets to run parallel "threads" of BSL at the same time. Unlike robust programming languages, there is very little control over BSL's version of "multi-threading", so see the caveats at the end of the "fork" section. | ||