Scripting Tutorial: Getting Started
From PBnWModdingWIKI
|
[edit] Note from the author
|
Creating the map
We'll need a map to play on! Like, a physical terrain!
- Open the landscape editor.
- In the landscape editor, either create a map or open an existing one. For this tutorial, we'll use the unused level 10 map. (File -> Open -> Land10.bwe).
- Point File -> Save As. Save it as wikitutorial.bwe in the B&W2 map (.\data\landscape\bw2 in the Installation Directory, which is typically at c:\Program Files\Lionhead Studios\Black & White 2) directory.
- Point View -> Land Properties. Set the UNIQUE LAND NUMBER. In this tutorial, we'll use 1337. In the future, you will need to register your unique number otherwise your maps will conflict with other people's maps! For now, just type 1337 and press enter. The land number has been set. If you're going to distribute your map, register your Land Number and use that instead of the 1337 number in this tutorial!
- Save and close the editor!
What did I just do?
Well, besides the obvious, you also set the land number (in this case, 1337!). When Black & White 2 loads up your map, it'll look for a file called LandSomeNumber.chl. That 'SomeNumber' is the landnumber. If you look at Lionhead's maps.. for example.. Land1.
Land1's land number is, surprisingly, 1. Thus, B&W2 will look for a file called Land1.chl when it loads up the map of Land1! So, that's why you need to set an unique landnumber, otherwise B&W2 might load up the wrong script instead!)
Writing the script
Every map _NEEDS_ a script! Always! Otherwise it just won't load!
- Go to the Script Compiler directory of the toolkit (C:\Program Files\Lionhead Studios\Black & White 2\Tools\Script Compiler).
- Create a folder, call it wikitutorial and enter that folder.
- Create a new text file called WikiTutorialScript.txt, use your favorite editor (I just use Notepad)
- Okay, we need to declare our script:
begin script WikiTutorialScript start
- Well, for everything we start, we'll need an end. So we'll just close the command.
end script WikiTutorialScript
- Okay, we declared our script, but we need to give the script a body. So, add this after 'start':
disable load screen set fade in time 1 wait until 1 != 1
- Okay, but when the game reads this script, it'll just think "okay, right. WikiTutorialScript. That's nice" and not do anything with it. So, we'll need to make sure it runs our script. On the first line, add the following:
run script WikiTutorialScript
- Okay, so now your script should look like this:
run script WikiTutorialScript begin script WikiTutorialScript start disable load screen set fade in time 1 wait until 1 != 1 end script WikiTutorialScript
- Save the file and close the editor.
What did I just do?
You just wrote a script with a single method. The method is defined using begin script WikiTutorialScript and is called using run script WikiTutorialScript(first line). Every method has a head (begin script, variable declaration, start) and a tail (end script..). Of course, between the head and the tail is a body which holds the instructions of the script
Compiling the script!
- In your wikitutorial folder, create a file called WikiTutorialChallenges.txt and open it.
- Add the following line:
wikitutorial/WikiTutorialScript.txt
- Be sure that the last line in that file is an empty one.
- Go back to the compiler directory.
- Create a new file called CompileWikiTutorial.bat
- Open CompileWikiTutorial.bat with notepad (right click on it, choose 'edit').
- Add this to the file:
"Script Compiler" -path . -enumfile .\Enums.txt -dbfile .\bw2text.lhts -scriptpath . -inputfile ./wikitutorial/WikiTutorialChallenges.txt .\wikitutorial\NewChallenge.chl pause
a more advanced bat file looks like
"Script Compiler" -path . -enumfile .\Enums.txt -dbfile .\bw2text.lhts -scriptpath . -inputfile ./wikitutorial/WikiTutorialChallenges.txt ..\..\Scripts\BW2\NewChallenge.chl > debug.txt
but please dont use the above untill you get the first one working and you understand how it works.
What did I just do?
We did two things. First we created the ChallengeList file. Each line of this file should have the location of a sourcecode file you wrote. Luckily for the compiler, we only wrote one, but in the future you may have more than one script files. The 2nd thing we did was to create a batch file that starts the compiler for you. We told it where some of the important files were, as well as the location of the file which contains the locations of your script files!)
- Okay, save the file and double click it. The output should look like this:
- Enter the wikitutorial directory, and copy the NewChallenge.chl file.
- Go to the B&W2 scripts directory (Scripts\BW2 in the B&W2 install directory. Typically at C:\Program Files\Lionhead Studios\Black & White 2)
- Paste the file there, and rename it to Land1337.chl. Note the landnumber(1337!)
What did I just do?
You compiled your script code. Compiling is a technique to make it easier for computers (or in this case B&W2) to understand your code. For the techies reading this article, it got compiled to bytecode to run on the LHVM(Lionhead Virtual Machine))
Playing your land!
Remember how you had to set a landnumber? Well, B&W2 uses this landnumber to find the correct script!
Since our landnumber is 1337, it'll look for Land1337.chl, which is our script!
If the landnumber is 1, it'd look for Land1.chl which is Lionhead's tutorial script.
- Go to the B&W2 Scripts folder.
- Open map.txt
- Set the correct landnumber. 1337
- Point the feature script to your map. .\data\landscape\BW2\wikitutorial.bwe
The file should say:
SET_LAND_NUMBER(1337)
LOAD_FEATURE_SCRIPT(".\data\landscape\BW2\wikitutorial.bwe")
- Save the file.
- Start B&W2 and start a new game.
FAQ
- Q: How do I create a batch file?
- A: In the Windows Explorer, right click, point 'New', and then point 'Text Document'. Rename the file so that it ends with .bat. If the icon is still that of a text document, it means that Windows is (still) configured to hide extensions. Point Tools -> Folder Options -> View -> Now disable: Hide extensions for known file types. Now you can give your batch file the extension .bat by renaming it.
- Q: Where did my compiled script go? (the .chl file)
- A: The compiler saved it in the same directory as your source files.
- Q: I did the whole tutorial, but, when I start a new game it doesn't finish loading!
- A: The game cannot find the level script. Be sure to set the correct land number and make sure that you named the .CHL file correctly! Also, be sure that the CHL file ends up in the B&W2 script directory! (Check the article). There should be a bunch of other CHL files in there!
- Q: The compiler gives an error message! "Unable to open file for parsing"
- A: Make sure that the 'list' file(WikiTutorialChallenges.txt) ends with a whiteline. Just press enter! The compiler ignores the last character in the file that lists the scripts (WikiTutorialChallenges.txt). Normally this is the newline character, but if you forget to do this it'll remove the 't' in .txt! You can actually see this by reading the error message, it'll complain about not being able to find a something.tx file! Just make sure that the WikiTutorialChallenges.txt file ends with an empty line.
- Q: I have a question that isn't answered in this FAQ, may I add it?
- A: This is a WIKI, of course you may add it. That is, if you know the answer! Anyway, if you want someone else to answer your question, feel free to ask it on the Talk page of this article!
- Q: How do i get objectives to work? anything with a " crashes the compiler
- A: Ok this is a know bug in the compiler .. any "'s will crash the compiler .. but their is somthing you can do to make it work. First off copy the file
