Bully LUA: Tutorial

The following is a PM I sent to someone who wanted to learn how to mod Bully. Due to how informative it was, I have decided to post it here for anyone else who is interested in learning how to mod themselves.

You want to learn how to script huh? Alright well first you'll need a few things. Note that there are other tools you can use, but these are the ones I reccomend and use myself.
Notepad++ (https://notepad-plus-plus.org/download/v6.9.1.html): You will use this to write your source code.
LUA Compiler (http://www.bully-board.com/index.php?action=downloads;sa=view;down=60): This is a special version of the LUA compiler made specifically for Bully (there are other compilers for different versions of LUA). This tool will compile your source code, making it into something that the game will be able to understand.
IMG Toolkit (http://www.bully-board.com/index.php?action=downloads;sa=view;down=159): A tool for editing Bully's IMG archives (an .img file in Bully is a file archive, similar to .rar or .zip). It comes with a lot of extra things but all you will need from this is the file "BullyImgConsole.exe". Run it and type "-help" to get an overview of all the commands you can use. You will use this tool for replacing the game's scripts with your own.

Once you have those tools setup the process of making a script mod is basically like this:
1. Create a new script in notepad++, this is your source code.
2. Compile your source code using LuaC (the LUA compiler) so that the game can read your script (the game cannot run source code). Name the compiled script the same as the script you want to replace in Bully.
3. Open the "Scripts.img" archive using the IMG toolkit and replace one of the scripts with your new script. You can do this using the "-open" command then the -"import" command. After doing that it is also recommended you rebuild the archive using the "-rebuild" command.
4. Close the archive (using the "-close" command) and run the game. If you did everything correctly and your script doesn't contain any errors, you should see your mod.

At this point you probably still have some questions, like what scripts are there, which do you replace, and most importantly how to even write a LUA script.
1. The Scripts.img archive has a lot of scripts in it. Use the "-exportAll" command in your IMG toolkit to export all of them and view them. Remember to use the "-help" command if you need to see how the command works. For this specific one, you first create a folder that you'll export your scripts to (name it "Exported Scripts" or something), then specify that folder in quotation marks when using the command (-exportAll "Exported Scripts"). Now you should have all the scripts in that folder and you may view them as you please. Note that these scripts are compiled, meaning you won't be able to view the source versions of them.
2. You can technically replace any script you want, but a good first one to replace for learning purposes is "ArcRace1.lur". This script is activated when the player uses the arcade machine in the boy's dorm. It is considered to be a "mission script", and for that reason is expected to have at least 3 functions: "MissionSetup", "MissionCleanup", and "main". Bully will first call "MissionSetup" when the script is started, then "main", then "MissionCleanup" when the script ends. You probably don't know what functions are yet and that's okay.

Then with actually learning LUA... this is a big task but if you put time and effort into it, I believe you can succeed. First understand what LUA is: LUA is a scripting language that can be used for a number of things, not just Bully. For learning LUA, I suggest you start by using a version of LUA that simply runs in the command prompt (the command prompt is something in Windows that you can use to start/use applications that run without a GUI and just rely on text). Bully's version of LUA is a modified version of LUA 5.0, so that is the version we will learn. The differences between Bully's version and the official version are pretty small, but still existent. They are the reason why different compilers must be used.

The official version of LUA 5.0 can run source code (unlike Bully which requires you to compile your code), but also gives you the option to compile it (remember using a different compiler). There are 2 files that you will need for compiling/using LUA 5.0. The compiler and interpreter. The compiler you should already know the basics of by now, and the interpreter is what runs your LUA scripts (whether it be from a compiled script file, a source script file, or from code you type right into the command prompt). Download both of those files here (https://www.mediafire.com/?k3d26az7y3wody7). I also included a test script for you to get started with. It includes an explanation of the script and in detail how you can run the script. Open the script using notepad++.

It might be better practice for you to write the scripts out in notepad++ for now, but note that if you ever want to you can run lua.exe without any command line arguments (read the comments I made in test.lua if you don't know what a command line argument is) and be able to type code right there instead of writing it out in a script file first. This is useful for testing small things but again I suggest you get used to writing the scripts out in their own files for now, that way you can save them too.

Once you get those files extracted and successfully run the script, it's time to start learning the language and making your own scripts. This (http://www.lua.org/pil/contents.html) is an official online book for learning how to use LUA 5.0. I also have made tutorials myself in the past but if you really want a good understanding of LUA, that book will do wonders. It may take some time at first for you to get the hang of it but once you got a basic understanding of scripting, it'll start to get a lot easier.

I suggest you only read the first 6 chapters of part 1 of that book. The rest will be useful if you plan to use LUA for things other than Bully, but the chapter 7 and past start to discuss things that you will not need to know for Bully scripting along with things that Bully doesn't even support. When I say "6 chapters" that may sound like a lot but don't get discouraged, they are pretty short and to the point.

After you finish those 6 chapters, skip to part 3 (http://www.lua.org/pil/contents.html#P3) where the standard library is discussed. You do not need to memorize all of these functions but I suggest you do bookmark it as it will serve as a nice reference guide in the future. The standard library is basically a set of functions LUA provides to you to use whenever you like.

Once you think you understand those first 6 chapters well and feel confident using LUA, you should be more than ready to finally start making Bully scripts. Note that a lot of the functions LUA provided you with before will not be available to you in Bully. For example you cannot use "print", any parts of the "io" library, or the "os" library. You can however use the math and table libraries and I believe parts of the string library. Oh but don't feel like you have a shortage of functions now, because Bully provides you with 100s of new functions to use specific to Bully.

For your very first script, we will replace ArcRace1.lur. I explained this file before, hopefully you still remember it (if not scroll back up). Try using this script (http://pastebin.com/AjDn93B6) as an example first. Instructions for compiling and replacement are above.

If the script runs successfully, then that means you compiled and replaced it correctly. So now it is time for you to experiment and make some of your own scripts. Bully has a lot of functions, and they aren't even all discovered yet. I'd love to describe to you every function I know but sadly I don't keep them written anywhere, I just memorize them. I do however have at least a few functions written down in a reference topic I made, along with some ID numbers you will need for certain functions. It can be found here (http://www.bully-board.com/index.php?topic=21325.0). I list some other places for you to find functions as well in the bottom of that post, as I only list around 20 myself. If you ever need a certain functions feel free to PM me as I may know the function you're looking for and just not of written it in that topic. I'd like to continue working on that topic and adding more functions but I haven't yet.

Good luck and have fun!