A Simple Scripting Exercise

  • The Freedom Force Editor is a powerful tool for making new mods for the game. However, without scripting, the maps you build, the characters you define and the bad guys you create stand around simply adding to the scenery. For the purpose of this tutorial I will assume you are familiar with the editor. If you are NOT, please refer to that section to get yourself started.
  • Freedom Force uses Python as its scripting language. Python is powerful and fairly simple as languages go, and any experience with other porgramming laguages will certainly be of use here. If you have never scripted before in your life – Fear Not! I had absolutely NO idea what I was doing in the beginning either… My very first suggestion is that you download a freeware Python Editor. I use PythonWin, but there are a few others out there. In a pinch, you can create Python scripts in Notepad in windows, but formatting is VERY important and use of an editor will help TREMENDOUSLY! If you have no editor, make sure you use a wordprocessing program that has no special formatting.

– Ok, scripting. It is very confusing at first, and teaching it is like teaching someone to ride a bike – say what you want, they have to learn by trying. Let me start with something simple as an example of the type of thing you see in a script:

nKO = Mission_GetAttribute(‘thugKO’)

Great, you say, looks like a drunk guy got ahold of a keyboard. (I resent that – I had 1 drink dammit!) It is not as terrible as it looks. It is fairly common statement in freedom Force scripts, in fact. We will look at it piece by piece and see what it means and what it is doing.
nKO is a variable. A variable is what it says it is, a item that is assigned various values as we see fit. Teh actual term ‘nKO’ is chosen at random. You can name it whatever you want. I chose ‘nKO’ because this variable will represent a (n)umber of (K)nock (O)uts. I am so clever, aren’t I? No? Ah well…
(=) is next. It does not mean what you might think it means. Think of it as meaning ‘is now equal to’ instead of ‘does equal’. We are used to 2+2=4. Or – 2+2 is equivalent to 4. In python we say 2+2 is NOW equal to 4. It may not have been before. So if nKO=4, whatever value nKO HAD is NOW 4. nKO may have previously been 300. Now it is 4.Mission_GetAttribute this is a predifined python function that is hardcoded into the game. In other words, the developers created a bit of code that performed a cerrtain action and we are using it to get what we want. In this case, we are using it to get an attribute – or value – that we have previously defined. We would have done this with a call to Mission_SetAttribute somewhere in our code. It is important now only to know that Mission_GetAttribute retrieves a previously stored value.thugKO is the Attribute that Mission_GetAttribute is looking for. At some point, we have assigned value to thugKO. We are retrieving that value with Mission_Get Attribute. thugKo is set off by apostrophes because it is a string (basically a word or set of letters) rather than a number.

Ok, so what is this little function doing? It is retriveing the value of thugKO with Mission_GetAttribute and assigning that value to nKO. Well and good you say. Why would I want to do that? Well, that’s what we are here to find out.
Consider this:

def On_Thug_KO(event):
nKO = Mission_GetAttr(‘ThugKO’) + 1
Mission_SetAttr(‘ThugKO’, nKO)
if nKO == 7:
Objective_Complete(‘ms_m1_p2’)

Ok another drunk guy you say. Anything look familiar? The first thing you may notice is that Mission_GetAttr is not the Mission_GetAttribute I had up top. I simply spelled out ‘attribute’ hoping it would make more sense. Another thing you’ll notice is that the second line is almost exactly like the example i gave above. Now we have 5 lines here instead of 1 and a few things happening. Let’s see if we can use what we know to see what is happening…

def On_Thug_KO(event):
This line is a definintion. We are defining an event named On_Thug_KO.
nKO = Mission_GetAttr(‘ThugKO’) + 1
This line is the familiar one(I hope). We are assigning the value of ‘thugKO’ to nKO. Notice we are also adding 1 to it.
Mission_SetAttr(‘ThugKO’, nKO)
Ok, remember I mentioned Mission_SetAttr? Here, we are assigning thugKO the value of nKO. In other words, we have grabbed the value of thugKO above, added 1 to it and assigned it to nKO. Now we are making that value the new value of thugKO. If it still makes no sense, see below.
if nKO == 7:
This ‘if’ statement is simple. It says ‘if nKO’s value is 7 (the == checks equality. it does not assign value like the single equals sign.) do the following. If it is NOT 7, the script will simply terminate.
Objective_Complete(‘ms_m1_p2’)
This is another precanned function in Freedom Force. We are Completeing an objective depending on the value of nKO.

Confused? well, let’s try to use it in context of a game and see if it makes sense. Let’s say there is a very simple map with Minute Man and 7 thugs on it. An objective tells you that you must defeat 7 thugs. Now, behind the scenes, you set an attribute called thugKO to 0. You also setup a function (not important at the moment) to track every time a thug gets knocked out by Minute Man. That function is called On_Thug_KO. So everytime a thug gets knocked out by Minute Man, the code above goes into action. So what does it do?

Assuming the first thug is defeated, the script fires:
nKO is given the current value of thugKO (which is 0 remember?) and 1 is added to it. therefore, nKO now equals 1.
ThugKO is now set to nKO’s value – also 1. At this point, nKO and ThugKO both equal 1.
Now, the value of nKO is checked against 7. If it equal 7, the Objective Complete command fires. If not, the script exits.

If a second thug is defeated by Minute Man:
nKO is given the current value of thugKO (which is 1 now, because of the 1st thug being defeated) and 1 is added to it. therefore, nKO now equals 2.
ThugKO is now set to nKO‘s value – also 2. At this point, nKO and ThugKO both equal 2.
Now, the value of nKO is checked against 7. If it equal 7, the Objective Complete command fires. If not, the script exits.

This continues until 7 is reached or Minute Man dies and the game ends. Essentially, that 5 line code above simply acts as a counter for all of the thugs Minute Man is defeating and completes an objective when he knocks out all 7 of them. In order to esure that the thugs are counted, a command called regDeath (yet another hardcoded Freedom Force function) is used like so:

regDeath(‘thug_with_bat’, ‘On_Thug_KO’)

notice that the function ‘On_Thug_KO‘ is the same one in the first line of our function above. This means that whent he character named thug_with_bat is knocked out, the function On_Thug_KO is called. To ensure all 7 thugs cause this to happen, the follwing would all have to be added to the script:

regDeath(‘thug_with_bat’, ‘On_Thug_KO’)
regDeath(‘thug_with_bat_002’, ‘On_Thug_KO’)
regDeath(‘thug_with_bat’_003, ‘On_Thug_KO’)
regDeath(‘thug_with_bat_004’, ‘On_Thug_KO’)
regDeath(‘thug_with_bat_005’, ‘On_Thug_KO’)
regDeath(‘thug_with_bat_006’, ‘On_Thug_KO’)
regDeath(‘thug_with_bat_007’, ‘On_Thug_KO‘)

Seems like alot of typing eh? Irrational Games was nice to us, they gave us a function to help out.

regDeaths is the answer to our problem. Note the (s) at the end of Death. It is a different function. regDeaths will register the deaths of characters of the same template type. so:

regDeaths(‘thug_with_bat’, ‘On_Thug_KO’)

will catch the deaths of any character with the thug_with_bat template.

The regDeath or regDeaths commands must be called AFTER the characters to be counted are spawned. IF they exist as the mission starts, you can call them from OnPostInit(): if not, the functions can be called immediately after the characters are spawned.

For more information on OnPostInit see my upcoming scripting basics tutorial.

The above should illustrate the use of simple functions in the game to do something basic to like count fallen foes. The code was taken from a real script (Mission 1 of my Metal Storm mod) and remains representative of the scripts used throughout the mod.