BSL:BFW Scripting Language: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (→‎Downloads: added the mod depot for download scripts)
(table-fied the kb and hid the incomplete pages; tweaked some wording in "Getting started")
 
(34 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 "real" programming language, as it was designed only to move events forward in the game, not to build programs.
'''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.


==What Are Scripts?==
Physically speaking, they are the .bsl files inside the [[IGMD|Oni/GameDataFolder/IGMD/]] folder. Stored 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).
Scripts are the files that drive level logic, environment effects, and cutscenes. Physically speaking, they are the .bsl files inside the folder [[IGMD|Oni/GameDataFolder/IGMD/]]. 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 {{SectionLink||Knowledge base}}. 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.
*For hands-on tutorials in writing BSL, see {{SectionLink||Tutorials}}.
*To learn BSL by example, you can read the .bsl files in the IGMD folder or look at some of the mods linked from {{SectionLink||Script mods}} and draw connections between the scripting commands and the resulting events in the game.


==Editing Scripts==
==Script 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.
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.


- To learn BSL by example, you can read the .bsl files in Oni's IGMD folder and draw connections to the events in the game that were produced by those scripts.<br>
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.
- 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.<br>
- Typing '''''dump_docs''''' in the game console will generated the file '''script_commands.txt''' listing all BSL commands & variables.


==Scripted Mods==
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]].
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.  
 
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.
 
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.
 
===Downloads===
Downloads of OTA Mods are available at the [[AE:OTA|Oni Team Arena page]].
 
Downloads for other scripted mods can be gathered [http://mods.oni2.net/mods/Script here], [http://your-mom.oni2.net/Downloads.htm here] and [http://script10000.oni2.net/scripts.html here.]


==Tutorials==
==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:
;[[BSL:Tutorial/Console|Playing with the developer console]]
*Wanna make minor (yet cool-looking) changes to the original level logic? [[BSL:Tutorial/Modification|Read this]].
:The fastest way to start learning BSL is to load the first level and open the dev console.
*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:
;[[BSL:Tutorial/airport1_level_logic.bsl|Commented level script from Ch. 4 Airport]] (unfinished)
*[[IGMD|IGMD folder]]
:A commentary explaining how an existing level's logic is scripted.


==Syntax Overview==
==Knowledge base==
{| border="1" cellpadding="5" cellspacing="0" align="center"
{| class="wikitable"
|+'''BSL syntax overview table'''
|-
|-
| align="center" style="border-bottom:3px solid grey;"|
|[[BSL:Introduction|Introduction]]
{| border="0"
|A quick language reference, ideal for those with programming experience.
|+''BSL separators''
|-
|-
| align="center" width="100px" | [[BSL:Statements|<tt>;</tt>]]
|[[BSL:Manual|Manual]]
| align="center" width="100px" | [[BSL:Functions|<tt>,</tt>]]
|The complete language reference on BSL, with more explanations for newbies and details for power users.
| align="center" width="100px" | [[BSL:Comments|<tt>#</tt>]]
| align="center" width="100px" | [[BSL:Data|<tt>"</tt>]]
|-
|-
| align="center" width="100px" | [[BSL:Statements|<tt>{</tt>]]
|[[BSL:Functions|Functions]] & [[BSL:Variables|Variables]]
| align="center" width="100px" | [[BSL:Statements|<tt>}</tt>]]
|All of the engine's built-in functions and variables.
| 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;" |
|[[BSL:Defunct|Defunct commands]]
Click on a separator for details
|Apparently-obsolete commands.
|}
|-
|-
| align="center" style="border-bottom:3px solid grey;"|
|[http://ssg.oni2.net/subfold/charas/charas.htm Characters], [http://ssg.oni2.net/subfold/consoles/consoles.htm Consoles] & [http://ssg.oni2.net/subfold/doors/doors.htm Doors]
{| border="0"
|In-game IDs for each level of the game, useful when writing new scripts for those levels.
|+''BSL operators''
|-
|-
| align="center" width="100px" | [[BSL:Operators|<tt>+</tt>]]
|[[IGMD|IGMD/]]
| align="center" width="100px" | [[BSL:Operators|<tt>-</tt>]]
|The directory structure of the game scripts.
| 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>]]
|[[IGMD/global|IGMD/global/]]
| align="center" width="100px" | [[BSL:Operators|<tt>or</tt>]]
|A global scripting folder which can be used for patching.
| 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>]]
|[[BSL:Snippets|Snippets]]
| align="center" width="100px" | [[BSL:Operators|<tt>></tt>]]
|Useful snippets of code.
| align="center" width="100px" | [[BSL:Operators|<tt><=</tt>]]
<!--|-
| align="center" width="100px" | [[BSL:Operators|<tt>>=</tt>]]
|[[:Category:Scripting tasks|Scripting tasks]]
|Scripting commands grouped by subject (unfinished).
|-
|-
| 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;" |
|[[BSL:List|List of built-in commands]]
Click on an operator for details
|List of all scripting commands (unfinished).-->
|}
|-
| 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
|}
|}
|}
[[Category:BSL docs]]

Latest revision as of 04:03, 19 May 2024

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. Stored 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 base. 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.
  • For hands-on tutorials in writing BSL, see § Tutorials.
  • To learn BSL by example, you can read the .bsl files in the IGMD folder or look at some of the mods linked from § Script mods and draw connections between the scripting commands and the resulting events in the game.

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.
Commented level script from Ch. 4 Airport (unfinished)
A commentary explaining how an existing level's logic is scripted.

Knowledge base

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.
Functions & Variables All of the engine's built-in functions and variables.
Defunct commands Apparently-obsolete commands.
Characters, Consoles & Doors In-game IDs for each level of the game, useful when writing new scripts for those levels.
IGMD/ The directory structure of the game scripts.
IGMD/global/ A global scripting folder which can be used for patching.
Snippets Useful snippets of code.