Scripting Guide

[TCK 2,164]

This tutorial is available as an rtf for distribution or more convenient reading: http://www.mediafire.com/download/q75239pqlf9iff3/Script+tut.rtf

 

 

Scripting for Halo 1

Scripting is necessary for any singleplayer mission you plan to make, from the basic firefight to the full-fledged campaign. Scripting can also be useful for multiplayer maps, and though this tutorial mentions singleplayer missions now and again, the content doesn't cover anything specific to singleplayer missions; so if you're planning to script multiplayer maps, this is still the tutorial for you. Halo uses a scripting language called Blamscript. If you've scripted for a game before, you've likely used a variant of Lua, which is common for modern games to include; in that case, for you the hardest part of learning Blamscript will be getting acquainted with the parenthetical syntax of Lisp, the language of which Blamscript is a variant. If you've never scripted before, that's okay - you're in a good place to start. Download the attached PDF to follow along with commands used in examples, as well as to study on your own in order to see what functions are possible and get an idea as to which you need in order to accomplish your goals.

Halo Scripting Keywords list.pdf

 

 

Setting up Your Files

Every scenario will look to its mirror path in data to find a scripts folder. For instance a scenario under the path "tags\levels\b30\b30.scenario" will search for the folder "data\levels\b30\scripts" and look inside for script files. If this folder does not yet exist for your scenario, create it; inside that, you need to create a new text file (you may optionally have up to four different script files for the same scenario) and save it as a .hsc file (be sure to select "all file types" before saving, or it will save as .hsc.txt). The name does not matter.

 

Now simply open the .hsc file with your favorite code editor (notepad will suffice if you don't have one). Of course remember not to use any sort of style formatting such as bold, italics, etc. (Though I can't imagine a code editor that allows such things, as notepad surely doesn't.)

 

Every time you make a change to your script file, you need to save it, then in Sapien go to "File>Compile Scripts" (Ctrl+Shift+S is the key shortcut) and it will attempt to compile your script files. It will print any errors to the window, and also to debug.txt for more permanent reference.

 

Now you're ready to learn how to write your script.

 

 

Parenthetical Syntax and Block Form

It's important to remember that everything is inside a set of parentheses. A set of parentheses is called a list, and the list structure is the base for the entire language of Lisp (Lisp was in fact named for "LISt Processing"). I will use the phrase "open a list" to refer to typing a beginning parenthesis. After opening a list, there are three things that may immediately follow: a declaration, a function, or a static call. This is my own terminology, as Halo does not specify the terminology to be used with Blamscript. Let's go over what I mean by each term respectively.

 

Note the following: first, that the brackets "[ ]" are not part of any Blamscript code; anything contained in these brackets is simply a description of what should go there. Second, that a space is always seen as the end of one list element and beginning of another, unless it is contained within quotation marks. Last, that the semicolon ";" is used to denote comments in the code and any line starting with a semicolon will not be compiled as code. Use the semicolon to write yourself notes and remind yourself what different parts of your code are there to accomplish.

Declaration:
This is what you need to begin any block of code. When you open a list outside of any other lists, you are beginning a type of list which I will refer to as a block and you will make either 2 or 3 declarations to specify how to treat this particular block. Your first declaration will nearly always be either "script" or "global" to define the block type; a script is of course a series of commands to be executed in sequence, and a global is a variable. Your second declaration depends on your first. If you declare a script, you will then declare a script type. If you declare a global, you will declare a value type. We will go over both of these in later sections. As I said, the opening parenthesis before these declarations is the first parenthesis in any block; likewise the closing parenthesis denotes the end of the block. Here are examples of both block types:

(global [value type] [global name] [value])

(script [script type] [script name]
    [functions and arguments]
)

The names of globals and scripts can be anything as long as they are unique, meaning they do not represent another function, global, or script. They must also be self-contained, meaning they either need to have no spaces (dashes or underscores are common substitutes) or be contained in quotation marks if they do have spaces. You'll notice that global blocks tend to be much shorter than script blocks. This is because a global only needs to hold one value, while a script may execute hundreds of commands. Also notice that the global is defined above the script. This is a convention that is needed for scripts to be able to "see" globals; typically you should define all your globals at the very top of your .hsc file before any script blocks. In more advanced situations, a global might need to reference another global in order to get a derived value; the latter must be above the former in the document just the same.

Function:
Functions will be used at the beginnings of lists contained in sequence in a script block once the block has been thoroughly declared, as demonstrated in above examples. A function is any built-in way that Halo provides for manipulating arguments. An argument is a single element of data contained within a list after a function is called in the list. To demonstrate both of these concepts, we'll use some of the most basic functions; which will be addition, subtraction, multiplication, and division respectively: + - * /

(script [script type] math_and_more_math
    (+ 3 8)
    (- 8 2 1)
    (* 80 6)
    (/ 38 2)
)

The arguments in the above examples are the numbers, plain and simple. A list that begins with a function as its first element will always look for arguments as the remaining elements. What is demonstrated by the subtraction list is that the number of accepted arguments may be exact, or may vary, depending on the function. These mathematical functions can accept any amount of arguments with a minimum of two arguments. This script would do nothing in-game, as these numbers do not mean anything relating to the scenario and are not applied to anything in the scenario. The mathematical operations would simply be processed and the results, for lack of use by any other functions, discarded. Let's look at a function that would relate to some concept in the scenario.

(script [script type] doing_stuff_now
    (object_create_anew box)
    (object_teleport box spot)
)

When executed, this script would cause the object named "box" in the scenario to spawn, destroying it first if it already exists. It would then teleport "box" to the cutscene flag named "spot." The order of these two lists reminds us that scripts are sequential. For instance, consider the following script:

(script [script type] doing_stuff_wrong
    (object_teleport box spot)
    (object_create_anew box)
)

This script would cause an exception error, assuming "box" did not already exist for some other reason. It would attempt to teleport "box" before creating it. If "box" did already exist, it would teleport "box" and then immediately destroy and respawn it. Functions are executed sequentially at a rate of 30 per second, meaning the delay between consecutive functions is negligible, and so at most you would see perhaps a flicker if the second situation were to occur, or more likely nothing at all.

Static call:
A static call is when a script is called to be executed like a function. "Static" is a script type, and we will discuss how to construct and use static scripts later on.

 

 

Nesting

Now that you understand parenthetical syntax and block form structuring of lists, we can move on to another crucial structuring technique: nesting. Nesting means to use a list as an element inside another list; indeed, block form is actually nesting, though we don't view it as that since lists are intended to be the elements of a list that has been declared a script.

 

To better understand why nesting works, think about the order of operations in ordinary math; lists have an order of operations as well, better thought of as an order of evaluation. The order is simply to evaluate the deepest list before moving up to the next level. Consider this line:

(= (ai_living_count cov1) 6)

"=" is a function that, as implied, will return true or false depending on whether the two arguments given are equal. Knowing that two arguments are being compared, we can understand that this list:

(ai_living_count cov1)

is treated as one argument. The one argument that this list reduces to is whatever the living number of actors is in the encounter cov1. So if there are 8 actors alive in this encounter, the line is simply the "=" function comparing 8 and 6, and it would return false. This also shows us what is meant by "deepest." The concept isn't so confusing when you think of it this way: every time a function encounters a new beginning parenthesis, whatever is contained inside the set will be reduced to one value before any more arguments are considered. The depth to which you may need to nest in order to get desired values will vary greatly depending on what you are trying to accomplish. Repeatedly nesting lists to great depth can become tiring, and is one good use for globals. Look how a global may reduce the need to retype nested expressions:

(global [value type] patrol_alive (ai_living_count cov1))

(script [script type] check_if_equal
    (= patrol_alive 6)
)

The global "patrol_alive" evaluates to whatever the living count is of cov1, eliminating the need to nest the function "ai_living_count" and its argument inside of the "=" function.

 

The "if" function is a good example of a function built around nesting. "If" tests its first argument, then executes the second if the first is true. Additionally, it may be given a third optional argument which it will execute if its first is false. Here it is in action:

(if (= (ai_living_count cov2) 4) (ai_erase cov2))

As you can see, this would not be possible without nesting. The argument being tested is the result of "=" comparing the living count of the encounter "cov2" and the number 4. If they are found to be equal, it becomes true, and "if" executes the next argument which is to delete the encounter. Otherwise, it does nothing. If we gave it a third argument, it would perform the third argument upon finding a false in the first.

 

Some functions are built not just to support nesting, but to be nested themselves. The function "not" reverses its true or false input. So we can see that "not" wouldn't be very useful unless it's nested within another function as a value, as well as having a test nested within it as a value.

 

 

Value Types

There are lots of different value types, many of which you may never need. The most fundamental ones are described here.

Short:
A short is a plain number with no decimal places. Examples include 2, 3, -4, or even 393. Most of the values you will use are going to be shorts until you begin writing more advanced script. This value type is limited to 32,768 in either direction from 0.

Long:
A long is a number without decimal places which can be far bigger than a short. The range from 0 on a long is 2,147,483,648.

Real:
A real is a floating point value. All that means is that real is the value type needed to process decimals, up to 6 decimal places out. 9.000000 and -8.283 are both reals.

Boolean:
A boolean is either true or false. This value type is common to practically all coding languages.

String:
A string is a set of up to 32 characters contained within quotation marks. "I have all the guns" is a string, and it's important to know that strings are the only way spaces can be included within one element.

 

 

Script Types

The type of script determines when it executes. The names are mostly self-explanatory.

Startup:
A startup script runs at the start of the map, immediately, starting even before the player's view has loaded.

Dormant:
A dormant script does not run until another script (somewhere below it) wakes it, using the "wake" function and the dormant script's name as an argument, as shown below:

(script dormant spawn_boxes
    (object_create_anew box1)
    (object_create_anew box2)
)

(script startup go_ahead
    (ai_place cov)
    (wake spawn_boxes)
)

The above script "go_ahead" will place the encounter "cov" and then wake the script "spawn_boxes" which will spawn two objects.

 

Startup and dormant scripts only execute once, waking them again will not do anything.

Continuous:
Continuous scripts will cycle constantly, starting at the top again when they reach the bottom. These are the only scripts that can repeat themselves.

Static:
Static scripts, as mentioned earlier, are similar to functions. They can be executed any number of times, but do not execute themselves. They are called anywhere a function would be called. They are also the only script type that should be declared with three elements. In addition to the normal first two, these scripts should have a "return type" declared, which just means the value type returned by the script. The reason for this is that static scripts can be used as a different sort of global (which will be covered in my "Advanced Scripting" tutorial). The important thing to know is that it's good form to use a return type even if the static script is for doing things rather than finding a value; the return type "void" means there is none. Consider the following:

(script static void place_vehicles
    (object_create_anew hog1)
    (object_create_anew hog2)
)

(script startup map_setup
    (object_create_anew box)
    (place_vehicles)
)

The script "map_setup" places "box" as its first function. Then its next function is the script "place_vehicles" meaning it executes that script. In this way, one use of static scripts is that they can take processes that are tedious to retype, but need to be done several times in different places in the script, and make it easy to reference all of it at once.

 

 

Scripting Practically

Knowing this new information, it's easy to see how dynamically you can make your scripts interact. Look at this basic example:

(script dormant remove
    (object_destroy hog1)
    (object_destroy hog2)
)

(script startup go_ahead
    (object_teleport hog1 spot1)
    (if (volume_test_object area1 hog2) (wake remove))
)

In the above example, the dormant script "remove" will not be woken unless "hog2" is found to be inside the trigger volume "area1." This means you can conditionally control entire sections of the script according to what's happening in the game. The most fun missions aren't scripted to be entirely straightforward.

 

Keep in mind all of the different ways you can test for conditions, and don't be afraid to write large portions of script that are optional. The more ways a map can react to the player, the better. Anticipate everything that the player might do.

 

 

Conclusion

This concludes my basic scripting tutorial. I believe a beginner will have everything they need to get started by now. Once you've spent enough time practicing the concepts here, I hope you'll move on to my next tutorials for singleplayer maps: "Perfecting Your Encounters" which will tell you everything you need to know about making groups of AI work together; and "Advanced Scripting" which is full of anything I know about scripts that can be quite exciting but wasn't relevant to get you started.

[DeadHamster 954]

Bah, all this time I've never understood how to use static scripts properly. I've always ran a continuous script, flipped a bit and then forced it to sleep until another script flipped the bit back over.

Good writeup, appreciate it for certain.

[TCK 2,164]

I thought that we should have an original tutorial by OC members for every part of modding.

[NeX 1,756]

Holy shit man, do you think you can add a bit relating to mp as well? This is....a really good write up. Fantastic even.

[Takka 13,376]

Fantastic!

 

This has been added to the Tutorials Shortlist.

[TCK 2,164]

Holy shit man, do you think you can add a bit relating to mp as well? This is....a really good write up. Fantastic even.

Thank you and I'll see what I can do on that, I haven't done a lot of MP scripting myself.

 

If there was a tutorial on MP scripting specifically, it seems like it should be a new tutorial so that the one on the shortlist can stay generalized. Still, I don't know if I'd have enough that I can say on it to write about it.

Edited November 14, 2014 by TCK

[Takka 13,376]

Since this tutorial covers singleplayer scripting, I'd suggest changing the title to something that reflects that, like 'SP Scripting Guide' or something. At least for now, unless you add MP content.

[TCK 2,164]

Since this tutorial covers singleplayer scripting, I'd suggest changing the title to something that reflects that, like 'SP Scripting Guide' or something. At least for now, unless you add MP content.

Well the only thing that's actually singleplayer is the fact that I mention singleplayer missions, but everything else is scripting basics. If I replaced the parts about singleplayer with parts about multiplayer, the rest of the tutorial wouldn't change; you still gotta know everything covered in order to script multiplayer.

 

I'll be sure to add that to the introduction though.

 

Updated:

Scripting is necessary for any singleplayer mission you plan to make, from the basic firefight to the full-fledged campaign. Scripting can also be useful for multiplayer maps, and though this tutorial mentions singleplayer missions now and again, the content doesn't cover anything specific to singleplayer missions; so if you're planning to script multiplayer maps, this is still the tutorial for you.

Edited November 14, 2014 by TCK

[TCK 2,164]

Here's the RTF version of this tutorial if anyone would like it or would like to distribute it: http://www.mediafire.com/download/q75239pqlf9iff3/Script+tut.rtf

 

It's a bit easier to read too. Added to OP.