BSL:BFW Scripting Language: Difference between revisions

Latest revision as of 02:38, 6 May 2023

BungieFrameWork Scripting Language (simply called BSL) is what Oni's level scripts are written in. Being a game scripting language, BSL is far more limited in scope and usage than a full programming language, as it was designed only to move events forward in the game, not to build complete programs. Specifically, BSL scripts are responsible for managing the player's objectives, directing AIs, creating environmental effects and choreographing cutscenes.

Physically speaking, they are the .bsl files inside the Oni/GameDataFolder/IGMD/ folder. Being in plain-text format, scripts can be edited with any word-processing program, such as the built-in Notepad (Windows) or TextEdit (Mac); the only requirement is that you must use the suffix ".bsl" for scripts instead of ".txt" (in Windows, you may have to turn on the displaying of file extensions to see the suffix).

Getting started

You may wish to first read either the Introduction or the Manual page under "Knowledge database" below. The Introduction is a quick reference, whereas the Manual includes an introductory lesson on programming concepts. It also documents known bugs in BSL and fixes/workarounds when available.
To learn BSL by example, you can read the .bsl files in the IGMD folder or look at some of the mods linked below and draw connections between the scripting commands and the resulting events in the game.
For a primer in writing BSL, see the "Tutorials" section below.

Script mods

Script mods are great examples of what can be achieved simply by editing text files. They replace or add to Oni's .bsl files to spice up the gameplay and provide a more exciting experience to those who have finished the game. However, they can only change the way that game data is used; adding new characters or changing the layout of a level, for instance, would require editing the actual game data. When new levels are created, these naturally require new scripts to be written from scratch to work with the assets and drive events in them.

One ambitious example of a script mod is Oni Team Arena. Based on the desire for a multiplayer mode in Oni and inspired by Unreal Tournament, OTA creates a single-player "multiplayer experience" by adding bots and a scoring system. Other script mods range from free-for-all arenas to objective-based missions and enhancements of the original levels.

Script mods packaged for use with the Anniversary Edition are listed here, and totally new levels with their own BSL files can be found here (these mods are meant to be installed through the AE Installer). Older scripts, which need to be placed manually in IGMD, can be found here and here.

Tutorials

Playing with the developer console: The fastest way to start learning BSL is to load the first level and open the dev console.

New logic from scratch: Create completely new level logic from scratch.

Knowledge database

Introduction: A quick language reference, ideal for those with programming experience.
Manual: The complete language reference on BSL, with more explanations for newbies and details for power users.
BSL:Functions & BSL:Variables: All built-in functions and variables.
BSL:Defunct: Apparently-obsolete commands.
In-game IDs of characters, consoles and doors (for use in scripts).
IGMD/: The directory structure of the game scripts.
BSL:Snippets: Useful snippets of code.
IGMD/global/: A global scripting folder which can be used for patching.
Category:Scripting tasks: Scripting commands grouped by subject (work in progress).
BSL:List: List of all scripting commands (work in progress).

@@ Line 1: / Line 1: @@
-'''[[Modding_Oni#Introduction_to_the_Oni_engine|BFW]] Scripting Language''' (simply called '''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. More specifically, BSL scripts are responsible for managing the player's objectives, directing AIs, creating environmental effects, and driving cutscenes.
+'''BungieFrameWork Scripting Language''' (simply called '''BSL''') is what Oni's level scripts are written in. Being a game scripting language, BSL is far more limited in scope and usage than a full programming language, as it was designed only to move events forward in the game, not to build complete programs. Specifically, BSL scripts are responsible for managing the player's objectives, directing AIs, creating environmental effects and choreographing cutscenes.
-Physically speaking, they are the .bsl files inside the [[IGMD|Oni/GameDataFolder/IGMD/]] folder. Being in plain-text, scripts can be edited with any word-processing program, such as the built-in WordPad (Windows) or TextEdit (Mac); the only requirement is that you must use the suffix ".bsl" for scripts instead of ".txt" (in Windows, you may have to turn on the displaying of file extensions to see the suffix).
+Physically speaking, they are the .bsl files inside the [[IGMD|Oni/GameDataFolder/IGMD/]] folder. Being in plain-text format, scripts can be edited with any word-processing program, such as the built-in Notepad (Windows) or TextEdit (Mac); the only requirement is that you must use the suffix ".bsl" for scripts instead of ".txt" (in Windows, you may have to turn on the displaying of file extensions to see the suffix).
 __NOTOC__
 ==Getting started==
-*You may wish to first look at the "Introduction to syntax" page under "Knowledge database" below.
+*You may wish to first read either the Introduction or the Manual page under "Knowledge database" below. The Introduction is a quick reference, whereas the Manual includes an introductory lesson on programming concepts. It also documents known bugs in BSL and fixes/workarounds when available.
-*To learn BSL by example, you can read the .bsl files in Oni's IGMD folder or look at the "Scripted mods" section below, and draw connections between the scripting commands and the resulting events in the game.
+*To learn BSL by example, you can read the .bsl files in the IGMD folder or look at some of the mods linked below and draw connections between the scripting commands and the resulting events in the game.
 *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.
-==Scripted mods==
+==Script mods==
-Scripted mods are great examples of what can be achieved simply by editing text files. They replace or add to Oni's .bsl files to spice up the gameplay and provide a more exciting experience to those who have finished the game. However, they can only change the way that game data is used; adding new characters or changing the layout of a level, for instance, would require editing the actual [[OBD|game data]]. When new levels are created for Oni, these naturally require new scripts to be written from scratch to take advantage of the new game assets.
+Script mods are great examples of what can be achieved simply by editing text files. They replace or add to Oni's .bsl files to spice up the gameplay and provide a more exciting experience to those who have finished the game. However, they can only change the way that game data is used; adding new characters or changing the layout of a level, for instance, would require editing the actual [[OBD|game data]]. When new levels are created, these naturally require new scripts to be written from scratch to work with the assets and drive events in them.
-One ambitious example of a scripted mod is [[AE:OTA|Oni Team Arena]]. Based on the desire for a [[multiplayer]] mode in Oni, and inspired by Unreal Tournament, OTA augments Oni's hand-to-hand combat and gunplay with a scoring system much like Unreal Tournament's Deathmatch mode. Other scripted mods range from free-for-all arenas to objective-based missions and enhancements of the original levels. Scripted mods can be found [http://mods.oni2.net/mods/Script here], [http://your-mom.oni2.net/Downloads.htm here] and [http://script10000.oni2.net/scripts.html here]. New levels, with their own BSL files, can be found [http://mods.oni2.net/mods/New%20Level here] (mod packages found on the Mod Depot are meant to be installed through the [[AE]]).
+One ambitious example of a script mod is [[AE:OTA|Oni Team Arena]]. Based on the desire for a [[multiplayer]] mode in Oni and inspired by Unreal Tournament, OTA creates a single-player "multiplayer experience" by adding bots and a scoring system. Other script mods range from free-for-all arenas to objective-based missions and enhancements of the original levels.
+Script mods packaged for use with the [[Anniversary Edition]] are [http://mods.oni2.net/mods/Script listed here], and totally new levels with their own BSL files can be [http://mods.oni2.net/mods/New%20Level found here] (these mods are meant to be installed through the AE Installer). Older scripts, which need to be placed manually in IGMD, can be found [http://your-mom.oni2.net/Downloads.htm here] and [[User:Script_10k#Incomplete_.2F_ancient_scripts|here]].
 ==Tutorials==
 ;[[BSL:Tutorial/Console|Playing with the developer console]]
-:The fastest way to start learning BSL is to just load the first level and open the dev console.
+:The fastest way to start learning BSL is to load the first level and open the dev console.
-;[[BSL:Tutorial/Modification|Original logic modification]]
-:There are lots of cool things to do by merely looking at the original scripts and changing a few parameters.
-;[[IGMD/global|Patching]]
-:Want to script a "patch" that's effective in every level?
 ;[[BSL:Tutorial/Scratch|New logic from scratch]]
@@ Line 28: / Line 23: @@
 ==Knowledge database==
-*[[BSL:Syntax|Introduction to syntax]]
+*[[BSL:Introduction|Introduction]]: A quick language reference, ideal for those with programming experience.
-*[[:Category:Scripting tasks|Scripting commands grouped by subject]]
+*[[BSL:Manual|Manual]]: The complete language reference on BSL, with more explanations for newbies and details for power users.
-*[[BSL:Reference|List of all scripting commands]]
+*[[BSL:Functions]] & [[BSL:Variables]]: All built-in functions and variables.
-*[[IGMD|File documentation for game scripts]]
+*[[BSL:Defunct]]: Apparently-obsolete commands.
-*[[BSL:Snippets|Useful snippets of BSL]]
+*In-game IDs of [http://ssg.oni2.net/subfold/charas/charas.htm characters], [http://ssg.oni2.net/subfold/consoles/consoles.htm consoles] and [http://ssg.oni2.net/subfold/doors/doors.htm doors] (for use in scripts).
+*[[IGMD|IGMD/]]: The directory structure of the game scripts.
+*[[BSL:Snippets]]: Useful snippets of code.
+*[[IGMD/global|IGMD/global/]]: A global scripting folder which can be used for patching.
+*[[:Category:Scripting tasks]]: Scripting commands grouped by subject (work in progress).
+*[[BSL:List]]: List of all scripting commands (work in progress).
 [[Category:BSL docs]]