Oni (folder)/GameDataFolder/IGMD/global: Difference between revisions

From OniGalore
Jump to navigation Jump to search
(noted the best use of this folder (setting up macro functions); various wording and formatting tweaks)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Oni global script folder==
'''global''' is a sort of secret subfolder of [[IGMD|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. This can be used to set up "macros" which you can call from the [[Developer Mode]] console. Some extended applications are considered below.
"global" is a "secret subfolder" of [[OSL:IGMD|IGMD]] : a regular installation of Oni doesn't have it at all.
__NOTOC__
==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 if you want it to run automatically.


But you can create it and use it and it's actually very rewarding. It's a very special folder.
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 <tt>func void main(void)</tt> is declared and modify it as follows :
func void main(void) {
    some_global_function # <--inserted line
  # ORIGINAL CODE
}


==What's so special about it?==
Next you would go to the '''global''' folder and create a file by any name with the suffix ".bsl", and the function:
The global folder is visible from every one of Oni's levels. Rather, the scripts (files with extension BSL) in the global folder are always processed at the same time as the level logic of a particular level, when that particular level is loaded.
func some_global_function {
    # Code to run at start of every level
}


You might be tempted to use <code>[[BSL:Functions|fork]] some_global_function</code> in <tt>main()</tt>, but it's probably 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 specific code from inside your global function. Just be aware that any commands you insert into the level scripting will delay the execution of the original logic unless you do decide to use <tt>fork</tt>.


==How do I use it?==
==Code overriding==
Is there really a short way to describe it? Oh well...
===Local overriding===
-----------
A less obvious "feature" of the '''global''' folder is overriding. A normally unseen rule in BSL is that <u>global functions override local ones by the same name</u>. For instance, place this in a global BSL file and play Chapter 4, Airport Assault:
Let's say you want Oni to do the exact same thing every time you load a save point. Like, you've just learned about how the [[OSL:Oni Scripting Language/functions/built-in/dmsg|<tt>dmsg</tt>]] command works, and you want the message "Thank you for playing Oni!" to be displayed after a level loads. Then the trivial solution is to go in every level's folder, open the file where <tt>func void main(void)</tt> is declared and modify it as follows :
 
  func void main(void) {
  func void bomber_boom(string char_index)
    dmsg "Thank you for playing Oni!"
{
#  WHATEVER ELSE THERE IS
    dmsg "Where's the kaboom?!"
    sleep 120
    dmsg "There was supposed to be an Earth-shattering kaboom!"
  }
  }
OK. You've done that for all 14 levels. But now, let's say you've learned about how to add colors to debug messages, and you want the whole message to be red, except for the word Oni which shall be blue.


What then? Open every level's "main file" again and replace "Thank you for playing Oni!" with "[r.Thank you for playing ][b.Oni][r.!]"? 14 times?
The original function by that name, [[BSL:Tutorial/airport1_level_logic.bsl#func_bomber_boom|found here]] in airport1_level_logic.bsl, 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....


No. You use the global folder
'''Big catch''': There may be unpredictable results; for instance, the above override causes random problems in the level such as changing Konoko's spawn location, though the dmsg will print appropriately when you reach the point where the ramp is supposed to explode.


==<tt>func pre</tt>==
===Built-in overriding===
Go to the global folder and create a file called <tt>pre.bsl</tt>. Open it and give it the following content :
Here's an even more astounding application of BSL overriding: you can replace Oni's [[BSL:Functions|built-in functions]]. This is because another BSL rule is that <u>functions declared in BSL files override built-in (hardcoded) ones by the same name</u>. This means that you can create a pseudo-[[wp:Hooking|hook]] like this one:
  func pre {
 
    dmsg "[r.Thank you for playing ][b.Oni][r.!]"
# The built-in env_show function takes two ints, so we'll match that function signature
  func env_show(int a, int b)
{
    dmsg "Env_show has been disabled."
  }
  }
Then go and open the 14 files where you had <tt>dmsg "Thank you for playing Oni!"</tt>, and replace that line with <tt>pre</tt>, getting :
func void main(void) {
    pre
#  WHATEVER ELSE THERE IS
}
This is an inline call to the <tt>pre</tt> function we have just set up in the global folder. The function <tt>pre</tt> is "globally recognized".


===Why call it <tt>pre</tt>?===
Now Oni's level scripts cannot hide objects in the environment by calling <code>env_show ''x'' 0</code>, and as you play a level you will see the effects 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! ^_^
Because everything in <tt>func main</tt> is level-specific settings and/or logic, so if you want something to happen exactly the same way every time you load a level, the only place to add that something is at the very start of <tt>func main</tt>, that is, ''before'' all the level-specific content. Which is why it's called "pre".
 
'''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. Therefore, you can't add code to the beginning or end of a built-in function as you should be able to with a true hook; you can only prevent the built-in function from running, and run your own code instead. In theory you might be able to reconstruct the whole built-in function using equivalent BSL commands. This is attempted by Gumby's cutscene-skipping script, which replaces [[BSL:Functions#cutscene|<tt>begin_cutscene</tt> and <tt>end_cutscene</tt>]] with its own implementations so it can add a "skip cutscene" key, with somewhat unpredictable results.


Should still work if you name it anything else though. <tt>pre</tt> just makes the most sense.
In light of the above considerations, the override "feature" is not recommended for use.


===Why make it inline? (WARNING : EXPERT STUFF)===
[[Category:Game directory map]][[Category:Modding tutorials]]
Because in that case, it's as if the content of <tt>func pre</tt> got pasted at the start of <tt>func main</tt> which is perfectly OK for some purposes (like the <tt>dmsg "[r.Thank you for playing ][b.Oni][r.!]"</tt> call in the example above). Three things to consider :
#You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside <tt>func pre</tt>. And it will be exactly the same as if you placed the <tt>fork</tt>ed call directly inside <tt>func main</tt>.
#If you put <tt>fork pre</tt> instead of <tt>pre</tt> in <tt>func main</tt>, you can no longer consider that you're "just adding stuff to the beginning of <tt>func main</tt>". You can make an inline call into a forked call, but not the other way round.
#In some cases, you may want to be sure some part of <tt>func pre</tt> is executed ''rigorously before'' <tt>func main</tt>. And that's something you can not guarantee with a <tt>fork</tt>ed call.
Sure you can't put anything you want in an inline-called <tt>func pre</tt>, like a <tt>sleep</tt> statement, or a call to <tt>chr_wait_animtype</tt>.
It's up to you to bear in mind that what you're looking at is in fact just a part of every level's <tt>func main</tt>.

Latest revision as of 12:21, 13 July 2023

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. This can be used to set up "macros" which you can call from the Developer Mode console. Some extended applications are considered below.

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 if you want it to run automatically.

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 in main(), but it's probably 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 specific code from inside your global function. Just be aware that any commands you insert into the level scripting will delay the execution of the original logic unless you do decide to use fork.

Code overriding

Local overriding

A less obvious "feature" of the global folder is overriding. A normally unseen rule in BSL is that global functions override local ones by the same name. 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 120
   dmsg "There was supposed to be an Earth-shattering kaboom!"
}

The original function by that name, found here in airport1_level_logic.bsl, 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, the above override causes random problems in the level such as changing Konoko's spawn location, though the dmsg will print appropriately when you reach the point where the ramp is supposed to explode.

Built-in overriding

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

# The built-in env_show function takes two ints, so we'll match that function signature
func env_show(int a, int b)
{
   dmsg "Env_show has been disabled."
}

Now Oni's level scripts cannot hide objects in the environment by calling env_show x 0, and as you play a level you will see the effects 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. Therefore, you can't add code to the beginning or end of a built-in function as you should be able to with a true hook; you can only prevent the built-in function from running, and run your own code instead. In theory you might be able to reconstruct the whole built-in function using equivalent BSL commands. This is attempted by Gumby's cutscene-skipping script, which replaces begin_cutscene and end_cutscene with its own implementations so it can add a "skip cutscene" key, with somewhat unpredictable results.

In light of the above considerations, the override "feature" is not recommended for use.