Difference between revisions of "BSL:BFW Scripting Language"

From OniGalore
Jump to: navigation, search
m (wording fixes; "real" in quotation marks doesn't really mean anything, does it?)
m (changed windows suggested edit program from wordpad to notepad, the later doesn't include any formatting data so should be preferable to edit plain text data)
 
(27 intermediate revisions by 5 users not shown)
Line 1: Line 1:
'''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 full-fledged programming language, as it was designed only to move events forward in the game using pre-made commands, not to extend Oni's functionality.
+
'''[[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.
  
==What Are Scripts?==
+
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 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).
Scripts are the files that drive level logic, environment effects, and cutscenes. Physically speaking, they are the .bsl files inside the folder Oni/GameDataFolder/IMGD/. By editing scripts, you can alter how the game plays.
+
__NOTOC__
 +
==Getting started==
 +
*You may wish to first read either the "Introduction" or the "Manual" page under "Knowledge database" below.
 +
*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.
 +
*For a primer in writing BSL, see the "Tutorials" section below.
  
==Editing Scripts==
+
==Scripted mods==
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.
+
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.
  
- To learn BSL by example, you can read the .bsl files in Oni's IMGD folder and draw connections to the events in the game that were produced by those scripts.<br>
+
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 [[User:Script_10k#Minor_Scripts|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]]).
- For a primer in writing BSL, see the Tutorials section below.<br>
 
- For a thorough listing of what's possible in BSL (a reference, not a primer), see the Knowledge Database below.
 
  
==Scripted Mods==
+
==Tutorials==
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 [[OBD|Binaries]]. They are great examples of what can be achieved simply by typing into a text file. The possibilities are simply endless.  
+
;[[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.
  
Probably the best specimens of Scripted mods are the [[AE:OTA|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.
+
;[[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.
  
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.
+
;[[IGMD/global|Patching]]
 
+
:Want to script a "patch" that's effective in every level?
===Downloads===
 
Downloads of OTA Mods are available at the [[AE:OTA|Oni Team Arena page]].
 
 
 
Downloads for other scripted mods mave been gathered here: [http://your-mom.oni2.net/Downloads.htm here] and [http://script10000.oni2.net/scripts.html 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? [[BSL:Tutorial/Modification|Read this]].
 
*Wanna script a "patch" that's effective in every level but doesn't change the original logic? [[IGMD/global|Then go here]].
 
*Wanna create completely new level logic from scratch? [[BSL:Tutorial/Scratch|Here you are.]]
 
  
==Knowledge Database==
+
;[[BSL:Tutorial/Scratch|New logic from scratch]]
*[[BSL:Statements|Statements]]
+
:Create completely new level logic from scratch.
*[[BSL:Variables|Variables]]
 
*[[BSL:Functions|Functions]]
 
*[[BSL:Operators|Operators]]
 
*[[BSL:Data|Data types]]
 
*[[BSL:Inventory|Inventory management]]
 
  
Documentation that describes the locations that BSL scripts reside in:
+
==Knowledge database==
*[[IGMD|IGMD folder]]
+
*[[BSL:Introduction|Introduction]] (a quick reference, ideal for those with programming experience)
 +
*[[BSL:Manual|Manual]] (the complete reference on BSL, with more details and explanations for newbies)
 +
*[[:Category:Scripting tasks|Scripting commands grouped by subject]] (work in progress)
 +
*[[BSL:List|List of all scripting commands]] (work in progress)
 +
*[[IGMD|File documentation for game scripts]]
 +
*[[BSL:Snippets|Useful snippets of BSL]]
  
==Syntax Overview==
+
[[Category:BSL docs]]
{| border="1" cellpadding="5" cellspacing="0" align="center"
 
|+'''BSL syntax overview table'''
 
|-
 
| align="center" style="border-bottom:3px solid grey;"|
 
{| border="0"
 
|+''BSL separators''
 
|-
 
| align="center" width="100px" | [[BSL:Statements|<tt>;</tt>]]
 
| align="center" width="100px" | [[BSL:Functions|<tt>,</tt>]]
 
| align="center" width="100px" | [[BSL:Comments|<tt>#</tt>]]
 
| align="center" width="100px" | [[BSL:Data|<tt>"</tt>]]
 
|-
 
| align="center" width="100px" | [[BSL:Statements|<tt>{</tt>]]
 
| align="center" width="100px" | [[BSL:Statements|<tt>}</tt>]]
 
| align="center" width="100px" | [[BSL:Functions|<tt>(</tt>]]
 
| align="center" width="100px" | [[BSL:Functions|<tt>)</tt>]]
 
|-
 
| align="center" colspan="4" style="border-top:1px solid red; border-right:1px solid red; border-bottom:2px solid red; border-left:1px solid red;" |
 
Click on a separator for details
 
|}
 
|-
 
| align="center" style="border-bottom:3px solid grey;"|
 
{| border="0"
 
|+''BSL operators''
 
|-
 
| align="center" width="100px" | [[BSL:Operators|<tt>+</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>-</tt>]]
 
| align="center" width="100px" | [[BSL:Variables|<tt>=</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>!</tt>]]
 
|-
 
| align="center" width="100px" | [[BSL:Operators|<tt>and</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>or</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>eq</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>ne</tt>]]
 
|-
 
| align="center" width="100px" | [[BSL:Operators|<tt><</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>></tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt><=</tt>]]
 
| align="center" width="100px" | [[BSL:Operators|<tt>>=</tt>]]
 
|-
 
| align="center" colspan="4" style="border-top:1px solid red; border-right:1px solid red; border-bottom:2px solid red; border-left:1px solid red;" |
 
Click on an operator for details
 
|}
 
|-
 
| align="center" style="border-bottom:3px solid grey;"|
 
{| border="0"
 
|+''BSL keywords''
 
|-
 
| align="center" width="75px" | [[BSL:Keywords|<tt>at</tt>]]
 
| align="center" width="75px" | [[BSL:Data|<tt>float</tt>]]
 
| align="center" width="75px" | [[BSL:Statements|<tt>if</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>repeat</tt>]]
 
| align="center" width="75px" | [[BSL:Data|<tt>string</tt>]]
 
|-
 
| align="center" width="75px" | [[BSL:Data|<tt>bool</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>for</tt>]]
 
| align="center" width="75px" | [[BSL:Data|<tt>int</tt>]]
 
| align="center" width="75px" | [[BSL:Functions|<tt>return</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>using</tt>]]
 
|-
 
| align="center" width="75px" | [[BSL:Statements|<tt>else</tt>]]
 
| align="center" width="75px" | [[BSL:Functions|<tt>fork</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>iterate</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>schedule</tt>]]
 
| align="center" width="75px" | [[BSL:Variables|<tt>var</tt>]]
 
|-
 
| align="center" width="75px" | [[BSL:Keywords|<tt>every</tt>]]
 
| align="center" width="75px" | [[BSL:Functions|<tt>func</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>over</tt>]]
 
| align="center" width="75px" | [[BSL:Keywords|<tt>sleep</tt>]]
 
| align="center" width="75px" | [[BSL:Data|<tt>void</tt>]]
 
|-
 
| align="center" colspan="5" style="border-top:1px solid red; border-right:1px solid red; border-bottom:2px solid red; border-left:1px solid red;" |
 
Click on a keyword for details
 
|}
 
|}
 

Latest revision as of 15:52, 27 February 2017

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.

Physically speaking, they are the .bsl files inside the Oni/GameDataFolder/IGMD/ folder. Being in plain-text, 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.
  • 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.
  • For a primer in writing BSL, see the "Tutorials" section below.

Scripted 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 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.

One ambitious example of a scripted mod is 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 here, here and here. New levels, with their own BSL files, can be found here (mod packages found on the Mod Depot are meant to be installed through the AE).

Tutorials

Playing with the developer console
The fastest way to start learning BSL is to just load the first level and open the dev console.
Original logic modification
There are lots of cool things to do by merely looking at the original scripts and changing a few parameters.
Patching
Want to script a "patch" that's effective in every level?
New logic from scratch
Create completely new level logic from scratch.

Knowledge database