Oni (folder)/GameDataFolder/IGMD/global - Revision history

Iritscen: removed NOTOC directive

2025-12-26T19:00:08Z

removed __NOTOC__ directive

← Older revision		Revision as of 19:00, 26 December 2025
Line 1:		Line 1:
	'''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 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.
	~~__NOTOC__~~
	==Code reuse==		==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.		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.

Iritscen: correct link for "fork"

2025-11-20T02:16:47Z

correct link for "fork"

← Older revision		Revision as of 02:16, 20 November 2025
Line 15:		Line 15:
	}		}

	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>.		You might be tempted to use <code>[[BSL:Manual#fork\|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>.

	==Code overriding==		==Code overriding==

Iritscen: noted the best use of this folder (setting up macro functions); various wording and formatting tweaks

2023-07-13T12:21:39Z

noted the best use of this folder (setting up macro functions); various wording and formatting tweaks

← Older revision		Revision as of 12:21, 13 July 2023
Line 1:		Line 1:
	'''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.		'''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.
	__NOTOC__		__NOTOC__
	==Code reuse==		==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.		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 <tt>func void main(void)</tt> is declared and modify it as follows :		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 :
Line 15:		Line 15:
	}		}

	You might be tempted to use <tt>[[BSL:Functions\|fork]] some_global_function</tt>, but it's ~~usually~~ better to call the function "inline" (that is, no ~~<tt>~~fork~~</tt>~~) to make sure that it fully executes before the original level logic resumes. You can always ~~<tt>fork</tt> what you want to be <tt>~~fork~~</tt>ed~~ inside your global function. Just be aware that ~~anything~~ you ~~add, such as a <tt>sleep</tt> command,~~ will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.		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>.

	==Code overriding==		==Code overriding==
Line 24:		Line 24:
	{		{
	dmsg "Where's the kaboom?!"		dmsg "Where's the kaboom?!"
	sleep 60		sleep 120
	dmsg "There was supposed to be an Earth-shattering kaboom!"		dmsg "There was supposed to be an Earth-shattering kaboom!"
	}		}
Line 30:		Line 30:
	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....		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....

	'''Big catch''': ~~there~~ may be unpredictable results; for instance, ~~this~~ override causes random problems in the level ~~like~~ changing Konoko's spawn location, though the dmsg will print appropriately when you reach the point where the ramp is supposed to explode.		'''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===		===Built-in overriding===
	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-[[~~wikipedia~~:Hooking\|hook]], like this one:		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:

	# The built-in env_show function takes two ints, so we'll do that ~~here too~~		# The built-in env_show function takes two ints, so we'll match that function signature
	func env_show(int a, int b)		func env_show(int a, int b)
	{		{
Line 41:		Line 41:
	}		}

	Now Oni's level scripts cannot hide objects in the environment by calling <tt>env_show ''x'' 0</tt>, 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! ^_^		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! ^_^

	'''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 a built-in ~~call's effects~~ 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.		'''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.

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

	[[Category:Game directory map]][[Category:Modding tutorials]]		[[Category:Game directory map]][[Category:Modding tutorials]]

Iritscen: /* Built-in overriding */ wording, formatting

2023-05-06T02:22:58Z

Built-in overriding: wording, formatting

← Older revision		Revision as of 02:22, 6 May 2023
Line 41:		Line 41:
	}		}

	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 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! ^_^		Now Oni's level scripts cannot hide objects in the environment by calling <tt>env_show ''x'' 0</tt>, 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. 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 a built-in call's effects using equivalent BSL commands. This is attempted by Gumby's cutscene-skipping script, which ~~attempts to replace~~ [[BSL:Functions#cutscene\|begin_cutscene and end_cutscene]] with its own implementations so it can add a "skip cutscene" key, with somewhat unpredictable results.		'''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 a built-in call's effects 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.

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

	[[Category:Game directory map]][[Category:Modding tutorials]]		[[Category:Game directory map]][[Category:Modding tutorials]]

Iritscen: link fix

2015-12-04T02:39:52Z

link fix

← Older revision		Revision as of 02:39, 4 December 2015
Line 15:		Line 15:
	}		}

	You might be tempted to use <tt>[[BSL:~~Syntax~~\|fork]] some_global_function</tt>, but it's usually better to call the function "inline" (that is, no <tt>fork</tt>) to make sure that it fully executes before the original level logic resumes. You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside your global function. Just be aware that anything you add, such as a <tt>sleep</tt> command, will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.		You might be tempted to use <tt>[[BSL:Functions\|fork]] some_global_function</tt>, but it's usually better to call the function "inline" (that is, no <tt>fork</tt>) to make sure that it fully executes before the original level logic resumes. You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside your global function. Just be aware that anything you add, such as a <tt>sleep</tt> command, will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.

	==Code overriding==		==Code overriding==

Iritscen: preemptive link fix (new page not created yet)

2015-12-02T16:06:06Z

preemptive link fix (new page not created yet)

← Older revision		Revision as of 16:06, 2 December 2015
Line 15:		Line 15:
	}		}

	You might be tempted to use <tt>[[BSL:~~BungieFrameWork_Scripting_Language#Syntax_Overview~~\|fork]] some_global_function</tt>, but it's usually better to call the function "inline" (that is, no <tt>fork</tt>) to make sure that it fully executes before the original level logic resumes. You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside your global function. Just be aware that anything you add, such as a <tt>sleep</tt> command, will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.		You might be tempted to use <tt>[[BSL:Syntax\|fork]] some_global_function</tt>, but it's usually better to call the function "inline" (that is, no <tt>fork</tt>) to make sure that it fully executes before the original level logic resumes. You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside your global function. Just be aware that anything you add, such as a <tt>sleep</tt> command, will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.

	==Code overriding==		==Code overriding==

Iritscen: +cat

2013-05-07T21:55:41Z

+cat

← Older revision		Revision as of 21:55, 7 May 2013
Line 47:		Line 47:
	Thus, the override "feature" is not recommended for use.		Thus, the override "feature" is not recommended for use.

	[[Category:Game directory map]]		[[Category:Game directory map]][[Category:Modding tutorials]]

Iritscen: /* Local overriding */ I totally planned this ;-)

2013-04-27T02:00:28Z

Local overriding: I totally planned this ;-)

← Older revision		Revision as of 02:00, 27 April 2013
Line 28:		Line 28:
	}		}

	~~That~~ function, 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....		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....

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

Iritscen: clarifying

2013-04-27T01:53:13Z

clarifying

← Older revision		Revision as of 01:53, 27 April 2013
Line 1:		Line 1:
	'''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.		'''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.
			__NOTOC__
	==Code reuse==		==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.		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.
Line 15:		Line 15:
	}		}

	You might be tempted to use <tt>fork some_global_function</tt>, but it's usually better to call the function "inline" (that is, no <tt>fork</tt>) to make sure that it fully executes before the original level logic resumes. You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside your global function. Just be aware that anything you add, such as a <tt>sleep</tt> command, will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.		You might be tempted to use <tt>[[BSL:BungieFrameWork_Scripting_Language#Syntax_Overview\|fork]] some_global_function</tt>, but it's usually better to call the function "inline" (that is, no <tt>fork</tt>) to make sure that it fully executes before the original level logic resumes. You can always <tt>fork</tt> what you want to be <tt>fork</tt>ed inside your global function. Just be aware that anything you add, such as a <tt>sleep</tt> command, will delay the execution of the original logic, unless you do decide to use <tt>fork</tt>.

	==Code overriding==		==Code 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</u>. For instance, place this in a global BSL file and play Chapter 4, Airport Assault:		===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:

	func void bomber_boom(string char_index)		func void bomber_boom(string char_index)
Line 27:		Line 28:
	}		}

	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....		That function, 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, 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.		'''Big catch''': there may be unpredictable results; for instance, this override causes random problems in the level like changing Konoko's spawn location, 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 <u>functions declared in BSL override built-in (hardcoded) ones</u>. This means that you can create a pseudo-[[wikipedia:Hooking\|hook]], like this one:		===Built-in overriding===
			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-[[wikipedia:Hooking\|hook]], like this one:

	# ~~Built~~-in function takes two ints, so we'll do that here too		# The built-in env_show function takes two ints, so we'll do that here too
	func env_show(int a, int b)		func env_show(int a, int b)
	{		{
Line 39:		Line 41:
	}		}

	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! ^_^		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 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 [[BSL:Functions#cutscene\|begin_cutscene and end_cutscene]] with its own implementations so it can add a "skip cutscene" key, with somewhat unpredictable results.		'''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 a built-in call's effects using equivalent BSL commands. This is attempted by Gumby's cutscene-skipping script, which attempts to replace [[BSL:Functions#cutscene\|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.		Thus, the override "feature" is not recommended for use.

	[[Category:Game directory map]]		[[Category:Game directory map]]

Iritscen: /* Code overriding */ even better

2013-04-26T20:05:12Z

Code overriding: even better

← Older revision		Revision as of 20:05, 26 April 2013
Line 23:		Line 23:
	{		{
	dmsg "Where's the kaboom?!"		dmsg "Where's the kaboom?!"
			sleep 60
	dmsg "There was supposed to be an Earth-shattering kaboom!"		dmsg "There was supposed to be an Earth-shattering kaboom!"
	}		}