BSL:BFW Scripting Language

Bungie Scripting Language (or BSL) is what Oni scripts are written in. Being a scripting language, it is far more limited in scope and usage than a "real" programming language, as it was designed only to move events forward in the game, not to build programs.

What Are Scripts?

Scripts are the files that drive level logic, environment effects, and cutscenes. Physically speaking, they are the .bsl files inside the folder Oni/GameDataFolder/IGMD/. By editing scripts, you can alter how the game plays.

Editing Scripts

Scripts can be edited with the simplest of word-processing programs, such as the built-in WordPad (Windows) or TextEdit (Mac). They can be edited simply by typing inside the file. When saving, you must either ensure that the suffix is .bsl or that you use the suffix .txt and afterwards change it to .bsl.

- To learn BSL by example, you can read the .bsl files in Oni's IGMD folder and draw connections to the events in the game that were produced by those scripts.
- For a primer in writing BSL, see the Tutorials section below.
- For a thorough listing of what's possible in BSL (a reference, not a primer), see the Knowledge Database below.
- Typing dump_docs in the game console will generated the file script_commands.txt listing all BSL commands & variables.

Scripted Mods

Scripted mods are great examples of what can be accomplished by editing scripts. They replace or add to Oni's .bsl files to create interesting and often amusing results. They can change everything from the fog to how the characters and level interact. However, they cannot add new characters or change the level layout, as that data is fixed by the Binaries. They are great examples of what can be achieved simply by typing into a text file. The possibilities are simply endless.

Probably the best specimens of scripted mods are the Oni Team Arena scripts. Based on the desire for a multi-player mode in Oni, and inspired by Unreal Tournament, they augment Oni's hand-to-hand combat and gunplay with a scoring system much like Unreal Tournament's DeathMatch.

Other scripted mods range from free-for-all arenas to objective-based missions and enhancements of the original levels. They can spice up the gameplay and provide a more exciting experience to those who have finished the game. They keep the game alive, outside of its original levels.

Downloads

Downloads of OTA Mods are available at the Oni Team Arena page.

Downloads for other scripted mods can be gathered here, here and here.

Tutorials

For the practical minds who don't care (too much) about theory, the BSL:Tutorial page offers the following paths for you to explore:

• Wanna make minor (yet cool-looking) changes to the original level logic? Read this.
• Wanna script a "patch" that's effective in every level but doesn't change the original logic? Then go here.
• Wanna create completely new level logic from scratch? Here you are.

Knowledge Database

• Statements
• Variables
• Functions
• Operators
• Data types
• Inventory management

Documentation that describes the locations that BSL scripts reside in:

• IGMD folder

Syntax Overview

BSL syntax overview table

BSL separators ; , # " { } ( ) Click on a separator for details

BSL operators + - = ! and or eq ne < > <= >= Click on an operator for details

BSL keywords at float if repeat string bool for int return using else fork iterate schedule var every func over sleep void Click on a keyword for details

Code pieces

# and old but useful character setup function by geyser
func SpawnNameFlagHealthReset(string n, int f, int h, int r){
    ai2_spawn(n); chr_teleport(n, f)
    if(h) chr_set_health(n, h)
    if(r) chr_inv_reset(n)
}

# can be like this ...
func wave_setup {
    #note that missing arguments are taken to be 0)
    SpawnNameFlagHealthReset Griffin 23 600
    SpawnNameFlagHealthReset Muro 22 2500
    SpawnNameFlagHealthReset F_Er89 22 80 1
    SpawnNameFlagHealthReset A_S1 24
}