BSL:BFW Scripting Language: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (link fixes)
(rewrite; made page more concise; reorganized knowledge database; moved useful code snippets to BSL:Snippets)
Line 1: Line 1:
'''[[Modding_Oni#Introduction_to_the_Oni_engine|BFW]] 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.
'''[[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, 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 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).
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.
 
==Editing Scripts==
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. In Windows, you may have to turn on the displaying of file extensions to see the suffix.


==Getting started==
- 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>
- 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>
- For a primer in writing BSL, see the Tutorials section below.<br>
- 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>
- 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 generate the file '''script_commands.txt''' listing all BSL commands & variables.
 
==Scripted Mods==
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==
==Scripted mods==
For the practical minds who don't care (too much) about theory, the [[BSL:Tutorial]] page offers the following paths for you to explore:
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 create interesting and often amusing results. 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 a new level is created for Oni, these also require new scripts to be written from scratch to take advantage of the new game assets.
*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==
One ambitious example of a scripted mods 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. 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. 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].
*[[BSL:Statements|Statements]]
*[[BSL:Variables|Variables]]
*[[BSL:Functions|Functions]]
*[[BSL:Operators|Operators]]
*[[BSL:Types|Data types]]
*[[BSL:Inventory|Inventory management]]


Documentation that describes the locations that BSL scripts reside in:
==Knowledge database==
*[[IGMD|IGMD folder]]
*[[BSL:Syntax|Introduction to syntax]]
*[[BSL:Tutorial|Beginner and advanced tutorials]]
*[[:Category:Scripting tasks|Scripting commands grouped by topic]]
*[[BSL:Reference|List of all functions and variables]]
*[[IGMD|Documentation of script files in game installation]]
*[[BSL:Snippets|Useful snippets of BSL]]


==Syntax Overview==
==Syntax overview==
{| border="1" cellpadding="5" cellspacing="0" style="margin-left:auto; margin-right:auto;" align="center"
{| border="1" cellpadding="5" cellspacing="0" style="margin-left:auto; margin-right:auto;" align="center"
|+'''BSL syntax overview table'''
|+'''BSL syntax overview table'''
Line 118: Line 98:
|}
|}
|}
|}
==Code pieces==
===Character setup===
# an old but useful character setup function by geyser
func '''SpawnNameFlagHealthReset'''(string n, int f, int h, int r){
    ai2_spawn(n); chr_teleport(n, f)
    if(h) chr_set_health(n, h)
    if(r) chr_inv_reset(n)
}
# can be like this ...
func wave_setup {
    # note that missing arguments are taken to be 0
    SpawnNameFlagHealthReset Griffin 23 600
    SpawnNameFlagHealthReset Muro 22 2500
    SpawnNameFlagHealthReset F_Er89 22 80 1
    SpawnNameFlagHealthReset A_S1 24
}
===Follow me===
var bool follow_me = 1;
### begin of the journey
func follow_me_TV
{
# ai2_spawn charname # or somewhere else
chr_lock_active charname
fork follow
}
func follow
{
if (follow_me eq 1)
{
ai2_followme charname
ai2_setmovementmode charname run
sleep 180
fork follow
}
}
### events
func dont_follow_me_TV_enter
{
follow_me = 0
}
func dont_follow_me_TV_extit
{
follow_me = 1
fork follow
}
### player orders
func main
{
# ...
fork do_follow_me
fork dont_follow_me
}
func do_follow_me
{
chr_wait_animation 0 ORDERbk_fw_kick
follow_me = 1
follow
# for the case he/she is passive right now
ai2_passive charname 0
# sleep until anim finished
sleep 60
fork do_follow_me
}
func dont_follow_me
{
chr_wait_animation 0 ORDERbk_fw_punch
follow_me = 0
ai2_idle charname
# sleep until anim finished
sleep 60
fork dont_follow_me
}


[[Category:BSL docs]]
[[Category:BSL docs]]

Revision as of 04:44, 3 December 2015

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, 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 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).

Getting started

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

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 create interesting and often amusing results. 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 a new level is created for Oni, these also require new scripts to be written from scratch to take advantage of the new game assets.

One ambitious example of a scripted mods 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. 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. Scripted mods can be found here, here and here.

Knowledge database

Syntax overview

BSL syntax overview table
BSL separators
; , # "
{ } ( )

Click on a separator for details

BSL operators
+ - = !
and or eq ne
< > <= >=

Click on an operator for details

BSL keywords
at float if repeat string
bool for int return using
else fork iterate schedule var
every func over sleep void

Click on a keyword for details

Retrieved from "https://wiki.oni2.net/w/index.php?title=BSL:BFW_Scripting_Language&oldid=24747"