Oni (folder)/GameDataFolder/IGMD/global

global is a sort of secret subfolder of IGMD; a regular installation of Oni doesn't have it at all. But if you create it manually, you'll find it can serve a very special purpose: functions in the global folder can be called from every one of Oni's levels.

Code reuse

One obvious use for this feature is that when writing a script that affects multiple levels, you can place common BSL functions in global instead of duplicating that code in each level's BSL files. However, you are still going to have to modify each level's BSL to call this global function.

Let's say you want Oni to run a function every time you load a level. You have to go in every level's IGMD folder, open the file where func void main(void) is declared and modify it as follows :

func void main(void) {
    some_global_function # <--inserted line
  # ORIGINAL CODE
}

Next you would go to the global folder and create a file by any name with the suffix ".bsl", and the function:

func some_global_function {
    # Code to run at start of every level
}

You might be tempted to use fork some_global_function, but it's usually better to call the function "inline" (that is, no fork) to make sure that it fully executes before the original level logic resumes. You can always fork what you want to be forked inside your global function. Just be aware that anything you add, such as a sleep command, will delay the execution of the original logic, unless you do decide to use fork.

Code overriding

A less obvious "feature" of the global folder is overriding. A normally unseen rule in BSL is that global functions override local ones. For instance, place this in a global BSL file and play Chapter 4, Airport Assault:

func void bomber_boom(string char_index)
{
   dmsg "Where's the kaboom?!"
   sleep 60
   dmsg "There was supposed to be an Earth-shattering kaboom!"
}

That function is what causes the explosion of the ramp in the airport. Now, instead of creating an explosion particle and deleting the ramp, Oni just prints that message. Seemingly one could use this method to "patch" level BSL. However....

Big catch: there may be unpredictable results; for instance, this override causes random problems in the level, though the dmsg will print appropriately when you reach the point where the ramp is supposed to explode.

Here's an even more astounding application of BSL overriding: another rule is that functions declared in BSL override built-in (hardcoded) ones. This means that you can create a pseudo-hook, like this one:

# Built-in function takes two ints, so we'll do that here too
func env_show(int a, int b)
{
   dmsg "Env_show has been disabled."
}

Now Oni's level scripts cannot hide objects in the environment, and as you play a level you will see the effect of this. One obvious change is found in the introductory cutscene in Chapter 2. Ah, that must be the seat the receptionist wanted you to take! ^_^

Big catch: pseudo-hooks like this are of limited value because there's no way to call the original function once you've overridden its name with your own declaration, so you can't add to a built-in function this way; you can only prevent it from running, and run your own code instead. In theory you might be able to reconstruct a built-in call's effects using BSL. This is attempted by Gumby's cutscene-skipping script, which attempts to replace begin_cutscene and end_cutscene with its own implementations so it can add a "skip cutscene" key, with somewhat unpredictable results.

Thus, the override "feature" is not recommended for use.