A tutorial by Agrajag of Fan Made Fallout, found at http://www.fanmadefallout.com.
Intro[]
At the initiative of Stevie D, the short tutorial I wrote, purely as a "for noobs, by noobs" thing a few months back, is now posted in public. In fact, you're looking at it. While the following is not a tutorial for how to go from complete ignorance to expert scripter, it should indeed be enough to take you from complete ignorance to noob scripter. It's not so much a tutorial on how to script, but rather a tutorial on how to start to script - how to set everything up with the compiler, how it all works, that kind of stuff.
Please note that I'm pretty new to this whole scripting business myself, so don't kill me if there are errors in what is to follow - it seems to have worked for a couple of FMF members already, and it worked for me, but that still doesn't necessarily mean that it has to work for you. It's an attempt, nothing more. If you don't like it, go away. Now, we begin.
At the request from Bloodlust, I have written down aaaall I know about fallout 2 scripting. That's not much. Hopefully it is enough to get started for those who are interested. I personally found that the first stages - getting started - was the hardest of them all. Where do I start?? What do I have to do to get the things working? It's not exactly user friendly, it takes a while to get used to it, but it's really not that hard once you get past the initial stages. That's the purpose of this thread - to get you past the initial stages in a way that anybody can follow. No more trying to piece together all the (often conflicting) bits of information that are spread around in the myriads of forums and threads out there, everywhere. No more reading "tutorials" on how to get started, which in fact does nothing at all to get you past the very first, most cruicial problem - to compile the script and get it into the game.
I'm of course fully aware of my own ignorance here. I don't know a lot at all, quite the contrary. I only know what worked for me, and the truth is that it might not work for you at all. If it does however, if I had read this a few weeks ago (edit: this was written some time ago), it would have got me started a lot faster. Still, I had the advantage of live help from Dj_Unique. Without that, I would have gotten nowhere. At least I wouldn't have gotten there in any reasonable time frame. Anyway, what I'm trying to say is that the following just might be totally worthless to some of you. It might also be precisely what you needed to get started. Let's hope it's more of the latter.
Level up your scripting skill in 10 easy steps[]
As has been stated elsewhere, it really helps to have some basic understanding of programming before you start.
Getting started[]
- First, you need a compiler. There's probably a lot of different ways to do it, but I'm using the open watcom compiler, and it works. That's all I care about, really. Download it from here: http://www.openwatcom.org/index.php/Main_Page (it's free!).
- Install the compiler.
- Update the file called P.BAT in your Fallout 2 Mapper\SCRIPTS\ directory. Right click on it, press edit and exchange the text in it to the following (OBS: MAKE A BACKUP FIRST):
@echo off
@if not exist %1.ssl goto DONE
@copy %1.ssl temp.c
@G:\WATCOM\binnt\wcc386.exe temp.c /pc /fo=temp.i /w4
@rem Microsoft Visual Studio 6 users uncomment the following line:
@rem cl /P temp.c
@copy temp.i temp.ssl
@..\dos4gw ..\compile temp.ssl
@if %errorlevel% neq 0 goto ERROR
@rem The path in the following two lines should point to the Fallout 2 folder:
@copy temp.int G:\FalloutStuff\CompiledBIS\%1.int
@del temp.c
@del temp.i
@del temp.ssl
@del temp.int
@goto DONE
:ERROR
@echo ERROR: %_CWDS%%1.ssl >> ..\err.log
:DONE
4. Paths needed[]
4. Before you close the P.BAT, you will probably have to edit a few things. Instead of "G:\WATCOM\binnt\wcc386.exe", type the location of your wcc386.exe file. It's probably not on drive G, as mine is. The line "@copy temp.int G:\FalloutStuff\CompiledBIS\%1.int" will put the compiled file (the .int file) in the directory "G:\FalloutStuff\CompiledBIS\". If you don't have such a directory, or want your file to be put elsewhere, then type the location of choice there.
NOTE: Watcom doesn't seem to create the output directory itself, the first time you compile a script. If it doesn't exist already, you'll need to make the G:\FalloutStuff\CompiledBIS\ folder (or wherever you want your finished *.int files to go) before running the compiler. Otherwise, you'll get an error message in the DOS window and no compiled script.
Stevie D, 23-06-2006
5. Editing scripts[]
5. Now you need to either create a new script, or edit an existing one. Editing a script is easier, so we'll start with that. Rather than decompiling the scripts from the real game, you can use the script files (.ssl files) found in the Fallout 2 Mapper\SCRIPTS\ folder. You can use notepad, or any text editor, to open and edit them. A recommended starting script is the one called ACKLINT.SSL, found in the ARROYO folder. It is the script that controls the guy named Klint, who is the NPC standing at the first temple map in Arroyo.
Take ACKLINT.SSL, copy it to a new folder and edit it a little. Let's just start out with something very simple, to see if things work. Example: scroll down to the procedure called "look_at_p_proc", and change the line "display_msg(mstr(100))" to "display_msg(mstr(101))". That should make the short description and the long description of Klint be the same - not very fancy, but easy enough to see if it worked when you compiled it.
Once you're done with your changes, save the ssl file. I prefer to have a separate folder for my own scripts (edited or new), so I don't have to overwrite the existing scripts. They can be useful to have as a reference. Wherever you put the file you want to compile though, you need to make sure that there is a copy of P.BAT in it's parent directory. So if you have your own script in the folder SCRIPTS\MyOwn\, then you need to have P.BAT in the folder SCRIPTS\.
6. Compiling[]
6. To compile the script, open up the command tool (Start->program->accessories) and change the directory to the directory of your script. To change the directory, type "cd <new directory>", without the quotation marks, and the desired directory instead of "<new directory>". Now, type "..\p <scriptname>", where "<scriptname>" is the name of the script, without the extension. So if you want to compile ACKLINT.SSL, type "..\p ACKLINT" in the command tool. If the syntax of the code is correct, and everything is set up correctly, there should be no warning messages, and the file should be compiled. There should now be a file called ACKLINT.int in your output directory (which is, if you followed my example, in the folder called FalloutStuff\CompiledBIS\).
7. Installing[]
7. Finally, you will have to move (or copy) your newly acquired ACKLINT.int to your Program Files\BlackIsle\Fallout2\DATA\scripts\ folder. If you already have a file called ACKLINT.int there, you will have to overwrite it for the changes to take effect. Now, to see your changes, you can either start a new game of fallout 2 and go to the map where Klint is (which is convenient, since he's on the first map of the game), or you can start the mapper and load the map where Klint is (It's the map called "ARTEMPLE.MAP"), press f8 and see if it worked. Hopefully, the detailed description of Klint will now be the same as the brief description (if you followed my example above). Happy days.
8. New scripts samples[]
8. It rather quickly gets boring to just edit existing scripts, so lets get moving, shall we? While you could write new scripts from scratch, it is a lot easier to just take an existing script which is similar to the one you want to make, and then edit it as you see fit. To make it into a new script, as opposed to a script which is already used in fallout 2, you will have to give it a new name. I know little about the naming conventions of fallout 2 scripts, but it seems as though the script files shouldn't be longer than 8 characters. I don't know why that is, and I don't know what happens if they are, but to play it safe, just give the scripts a short name.
To make this "tutorial" as easy as possible, let's just take the ACKLINT.ssl and give it a new name, thus technically making it a new script, while it really is the same as before. A bit boring, but it would show the process of how to do it. Let's open up ACKLINT.SSL and save it as AACKLINT.SSL. Now, before you can compile it, you will have to open up the file called SCRIPTS.H, which is found in the Fallout 2 Mapper\scripts\headers\ folder. Open it, scroll to the bottom, and add the following line:
Code:
#define SCRIPT_AACKLINT (1304) // AACKlint.int ; Test
Save. Now it should be possible to compile AACKLINT.SSL. We're not done yet though, there's one last thing to do. You will have to get yourself some kind of program that can export .DAT files. I'm using DatExplorer, and it's working fine. There's plenty of others though, just do a search at no mutants allowed.
So, use your dat explorer to explore the file master.dat, found in your fallout2\ directory. Go to the folder "scripts", and find the file called SCRIPTS.LST. Extract it. Now, open it up (notepad works fine), and add the following line at the bottom:
Code:
AACKlint.int ; Modified version of ACKlint.int # local_vars=10
Save the file, and put it in the Program Files\BlackIsle\Fallout2\DATA\scripts\ folder. Now you should be able to use your new script in the mapper. To do so, open up the mapper, load a map (or make a new one), add a new critter (or make a new one), select that critter, press the edit button, press the "New script" button, find your script in the list and press okay. Press f8 to test it.
9. Text[]
9. If you've played around with the scripts for a while, you have probably noticed that the actual text that is displayed is nowhere to be found in the ssl files. Instead, all the text is stored in .msg files. If you want to look at the .msg files used in fallout 2, open up DatExplorer and explore the master.dat again. Most msg files are stored in the folder text\english\dialog\. Extract it and have a read, if you want to. Notice that you can now edit the msg files as you please, using any text editor. For example, if you want to edit the dialogue for Klint, find the file ACKLINT.MSG and edit it, then save. All the files in the Program Files\BlackIsle\Fallout2\DATA\text\english\dialog\ directory will override the files in the master.dat, so any changes you save to ACKLINT.MSG will appear in the game. Don't worry about editing the existing files though, as you can always retrieve a fresh copy from master.dat.
You can of course make your own msg files to go with your new scripts. Just make a msg file with the same name as the script (for example AACKLINT.msg), and type in whatever you want in it. Use the following syntax:
Code:
{<number>}{}{<text>}
Where <number> is a unique number (ie, you can't have the same number twice in a msg file), and <text> is anything you like.
Now, in order to access the text in your msg file, you need to use the function called "message_str". It returns a string from a selected msg file that corresponds to a selected number. For example, message_str(SCRIPT_AACKLINT,100) would return the string that corresponds to number 100 in the AACKLINT.msg file. To print a text in the text area, use the function display_msg. Examples: display_msg("Hello world."); prints "Hello world." in the text area. display_msg(message_str(SCRIPT_AACKLINT,100)); displays the text that corresponds to number 100 in AACKLINT.msg.
Rather than typing "SCRIPT_AACKLINT" each time, the most common thing is to make a new macro at the beginning of the code, so that you only have to type "NAME". If you go to the top of AACKLINT.ssl, supposing you've left it somewhat similar to ACKLINT.ssl, you will find the following line:
Code:
#define NAME SCRIPT_ACKLINT
What this does is simply making it possible for you to type NAME insteaed of SCRIPT_ACKLINT. So change that line to this:
Code:
#define NAME SCRIPT_AACKLINT
and you are done. As you may remember from above, the script ACKLINT uses "display_msg(mstr(x));" to display descriptions from it's msg file. Where is the definition of mstr()?, you might ask. Scroll to the top and notice the lines
Code:
#include "..\headers\define.h" #include "..\headers\command.h" #include "..\headers\ModReact.h"
What these lines do is simply adding all the definitions that are made in these header (.h) files, so that you may use them in your script. To see what's in them, go to the Fallout 2 Mapper\SCRIPTS\HEADERS\ folder and open them up. You will find a lot of definitions all around the place. In the file command.h you will find this line:
Code:
#define mstr(x) message_str(NAME,x)
This means that you can, if you include command.h in your code as is done in ACKLINT.ssl, write mstr(100) instead of message_str(SCRIPT_AACKLINT,100). Pretty handy. As you might have noticed here, you will have to define NAME in your ssl file, otherwise the mstr() definition will not work. NAME is used quite frequently, so it's generally a good idea to include it in your code, and have it point to the script that you're working with.
10. Other information sources[]
10. I don't have a lot of things left to teach you, but if you got this far, you should be able to figure out the rest on your own. I did (actually, that's not true. I got a lot of help from Dj_Unique - thanks a lot for that). Next, I'll try to write up how to get your own dialogue into the game, although you should be able to figure it out on your own. Basically it just amounts to exporting the .fmf file to .msg and .ssl files (which the dialogue tool can do), compiling the ssl file, adding the stuff you need to add to SCRIPTS.H and SCRIPTS.LST, and then you're done.
Anyway, in order to get anywhere, you should know about the following resources of information: the COMMANDS.DOC. If you looked around, you might have found it already. It's included with the mapper, and lies in the folder Fallout 2 Mapper\SCRIPTS\DOCS\. It includes a list of all the core functions that are available to you, together with a description of each one. Learn to use it, learn to love it - believe me when I tell you that it is your #1 place to look if you're unsure about how to script something. Everything that is possible to do with conventional means of scripting, can be done with a cunning use of the functions on that list.
If you didn't get my ramblings about macros, worry no more. It is all explained in numerous more or less incomprehensible "tutorials" out there. I found this one to be slightly useful at some rare occasions (it's not really anything you go back to for reference, but it's stuff you oughta know): http://koti.mbnet.fi/dsjoblom/scrtut.htm
The following is a very useful FAQ, which answered a lot of my noobish questions: http://modguide.nma-fallout.com/
Finally, here's a very short, but also very user friendly set of tutorials, covering some of the basics: http://www.coljack.pwp.blueyonder.co.uk/fallout/
Notes[]
NOTE: You may encounter problems if you are using the patched version of fallout 2. If that is the case, check out this page to see if you can get past the first stages of setting up the compiler and all that (it can be a headache, I know).
http://www.duckandcover.cx/forums/viewtopic.php?t=4855
Thanks for reading. Hope it will be of use to somebody. Now you are ready for Scripting - macros
NOTE: Any scripter who hasn’t discovered the joys of one of the various bespoke script editing utilites on the net is working with one hand tied behind his back. Once you've completed Agra's tutorial, above, download and install the Fallout Script Editor. It is extremely user-friendly compared to the business of scripting via text editor. Its many benefits to you as a scripter quickly become evident. Stevie D, 09-07-2006.