Airfix DogFighter Programmer's Manual

Tutorial

3.1.1: Coordinates.

I think it would be wise at this point to give some explanation about coordinates. For both objects you will see definitions for two sets of coordinates, three in each set. Why? The first set defines the 3D location of the object in the house along the X-, Z- and Y- axes (in that order!) In other words, the first value defines the position East/West, the second gives the Height and the third gives the North/South coordinate. These will be more fully explained in a later chapter.

The second set might look a bit more mysterious, especially since only the middle value is non-zero. They stand for PYB, or Pitch / Yaw / Bank. Think of an aircraft: Pitch means nose up or down, Yaw is Rotate and Bank is Tilt Left/Right. Think of our PSP (the Yellow Arrow in the Dining Room). In the preceding screenprint it is lying flat underneath the Dining Room Table. If the Pitch would have a positive value instead of zero, the “nose” would tilt more or less upward, depending on the value. Likewise, if the Bank-value would be unequal to zero, one of the tips would be at a higher position than the other. Finally, the middle one (Yaw) is more commonly known (and will make more sense) as Rotation. In the coordinate-definitions of both objects they are the only ones unequal to zero, because they define the position on the compass the object has. If you have already played with the House Editor, you know that you can spin each object round to point in any direction. In doing so you will define the middle value of the second set of coordinates.
ÿr> More about that later, let’s first finish the rest of the block…

SetPickupType( m_uidModel0, "" ) defines the type of Pickup that the model will yield when it is destroyed. Think of stars, ammo-boxes etc.
An empty string doesn’t mean there is no pickup, instead it means the type of pickup is undeclared, i.e it will be generated at random.
SetSquad( m_uidModel0, 0 ) sets the Squad for the Unit. We will discuss this property later.
SetTeam( m_uidModel0, 0 ) sets the team or side the Unit belongs to. As mentioned, 0 means Neutral so anyone can have a go at it… (and yes, it does shoot back…)
SetRank( m_uidModel0, 0 ) Sets the Rank for the Unit
AIActivate( m_uidModel0 ) AI stands for Artificial Intelligence, and setting this value to true (any value other than 0) will make this unit give a life of its own…
AISetStayRoom( m_uidModel0, 1 ) When this value is set to true the model will not leave the room it is located in, even if it is following you in hot pursuit.
Having said that, you might find that this setting will not always work…
AISetAggression( m_uidModel0, 50 ) This value determines the aggression of the model. As you can see the default value is 50 which is sort of half-way. A value of 0 will render the model a pacifist…

AISetPickupPrio( m_uidModel0, 50 );

AISetAttackPrio( m_uidModel0, 50 ) These two seem to set the priorities for picking up items and attack. The AttackPrio seems to work, when I set this to 0 the Fw190 will not attack no matter how I provoke it, but I haven’t seen it pick up items , no matter what setting you give it…

As we shall see later, this list is standard for any unit that you place in your level.

Except one…

You might remember that we saw three variable declarations in the .afs-file. We have seen that model0 is the tank and model1 is the Fw190, but what about model2? You might remember we also dropped a PSP, or Player Start Position, under the dining room table. We find this back in the .afs-file as the definition of the Start Position. It doesn’t mention model2, but it has inherited all its coordinates. Remember I told you try not to rotate it when placing it in the room? Depending on how accurate you were in that, the value for the Rotation (middle one of the second set of 3d-coordinates) will not be far off from 0.000000…

3.2: the .level-file

3.2.1: General Structure of .level-files.

This pretty much is the standard structure of a .level file:

FHOU- is the file header, followed by 4 hex characters that contain the total length of the entire file, excluding the first 8 characters;

HOUS- header of the world-descriptor, followed by 4 hex characters containing the length of the HOUS-block and a string containing the reference to the .world-file that describes the part of the Villa the level is situated in;

GCCS- will be explained later;

MODL- this block occurs once for every Unit that you place on the map. No matter what the Unit is, the block has a uniform structure which will be explained below.

OBJE- this block occurs for every Static and Dynamic Object, like chairs and urns, that you place on the map. This Block is smaller than the MODL-block, but uniform as well.

IAOB- the InterActive OBject block. This block describes the behaviour of interactive objects that are not contained in the Objects-subfolders. These objects are mainly Lightswitches and Doors. This block will also be explained below.

3.2.2: the HOUS-block.

We will leave the FHOU- and CCS blocks for what they are at the moment, and first have a look at the HOUS-block. You will remember that the first thing we did in building our level was selecting the environment: the Livingroom, Diningroom, Kitchen. If you look at the first three lines you will see that the following string is present: HOUS!...Game\Worlds\Dogfights\df_1.world. As mentioned earlier, the four positions after HOUS represent the length of this block in Hexadecimal. If we substitute the values in the string then we get:

HOUS 21 00 00 00 Game\Worlds\Dogfights\df_1.world 00,

in which the hexadecimal values are printed in bold. If we count the positions in this block, we find a total of 41. So what’s the difference? Well, the length-descriptor gives the length of the string After the descriptor, which means only the underlined, blue-coloured part of the string. Don’t forget that the bold pairs count for only one position each. That would still make it a total of 33, so what’s the difference? When we count the length of the string we automatically do that in decimal values. The four positions between HOUS and the underlined string are Hexadecimal however, and hex(21) is equivalent to 2x16 + 1x1 = 32 + 1 = 33!!!

But why is 21 the first hex value, followed by three times 00?

3.2.3: Reverse Hex Notation (RHN).

This seems to be a standard format in ADF-files, not only in .level-files but in others as well.
The way it is programmed is that the 4 positions are in reverse order. It is a bit like writing 2500 as 0052…
We would expect the Most Significant Bit on the left-hand side and the Least Significant Bit on the right, but in the ADF-files it is just the other way around. In the rest of this document, I will refer to this as RHN.

3.2.3: the MODL-block.

Let’s have a look at the third MODL-block and substitute the nonsense-chars for their Hex-equivalents straight away: (Hex in bold)

MODL 63 00 00 00
8A 2D 58 42 0D 2D 50 40 CD F9 5E 40
00 00 00 00 D8 0F C9 3F 00 00 00 80
dining_room 00
Game\Objects\Units\GuChurchill.object 00
model0 00
00 00 00 00
00
01 00
00 00
00
01 00 00 00
32 00 00 00

Why have I, seemingly at random, grouped the data this way? Let’s take it line for line…

MODL 63 00 00 00 Just like in the HOUS-block, the MODL-block starts with the 4-character Block-header (MODL) followed by the block length descriptor in RHN. This means that the rest of the block is hex(63) characters long, which in decimal is 6x16 + 3x1 = 99 positions.

8A 2D 58 42 0D 2D 50 40 CD F9 5E 40
00 00 00 00 D8 0F C9 3F 00 00 00 80 The next two lines contain 3 groups of 4 positions each. The first of these two contains the values for the X-, Z- and Y coordinates that we saw earlier in the .asf-file, the only difference being that here they are given in hexadecimal values (and yes, in RHN).

The second of these two lines, of course, contains the values for Pitch, Rotation and Bank that we discussed earlier with the .asf-file, also in RHN.
Notice that the value for bank isn’t 00 00 00 00 , but 00 00 00 80 ! This seems to be a standard default value for any object you drop into the level under construction...
Notice also, that the Hexadecimal values in the level-file bear absolutely NO resemblance to the Decimal ones as mentioned in the .asf-file....

Game\Objects\Units\GuChurchill.object 00 Next up is the string that refers to the definition file for the actual model, in this case the (Ground Unit-) Churchill tank. Like the string that refers to the .world-file, this string is closed by a 00 End Byte.

model0 00
Next line gives the Object Label, the name that the Model will be referred by in the House Editor and in the .asf-file. The House Editor will give them names automatically, starting with model0 and incrementing by 1 each time you add a model to the map.

00 00 00 00 These positions set the value for the Team the model belongs to. As you see, the default value that the House Editor enters is 0. Why it needs four hex positions I don't know.

00 This Byte is a bit of an odd one, as on this line the Squad is set, but in a rather different way.
This will be explained more fully a bit later on, suffice for now to say that this single byte is an End Byte, just like the one after the Descriptor String for the .world-file and the Churchill tank reference file name. ÿtd?

01 00 These two bytes set the AIActivate value for the model. See the .afs-file earlier in this chapter.

00 00 Haven't been able to figure out what these bytes do?

00 This is another End Byte, this time for the SetPickUpType (see below)

01 00 00 00 This is the setting for the AISetStayRoom-parameter, in RHN

32 00 00 00 This is the setting for the AISetAggression parameter, also in RHN.
By the way, Hexadecimal 32 = 50 in Decimal…

A word about the SetPickupType-parameter.

Anyone who has ever flown a Mission in ADF (and I assume that's everyone who reads this Document!) knows that when you destroy a breakable or a model, a Pickup appears. Most of the time these are completely random, but a Breakable or a Model can be set a specific Pickup-item. If you want to see the names of the range available, have a look in the Game\Objects\Units-folder. All names of Pickups start with pu, e.g. puBomb is the name of the Pickup Bomb Pack. So how do we set the Fw190 to cough up a Repair Kit when it dies? The name we are looking for is puRepairs.

In the Hex-Editor, we simply insert the string "puRepairs" in front of the SetPickupType End Byte, as will be shown after a discussion about the SetSquad-Parameter.

A word about the SetSquad-parameter.

In the Blocks described so far, most numerical settings are done in Hexadecimal values.
Not so the SetSquad-parameter. In the MODL-block above there is only the 00 of the End Byte.

First, what does the SetSquad-parameter do?
As we have seen in the discussion about the .asf-file, there are three possible sides: Neutral (0), Allied (1) or Axis (3). A Squad is just a subset of one of these forces that comes in handy as a single unit for programming purposes. Anyone who has played the Allied level "Attic Raid" (level 4) knows that when you kill off all three German bombers that fly into the attic you will get the message "Bombers are eliminated". That is because they are programmed to belong to the same Squad, and when all three are killed, no matter in what order, the Squad ceases to exist. So, in our simple Sample1 the Squad-property is not very important, but it will become later on so we will set it to, let's say, 21.

As mentioned, the way the setting is done is a bit different from the other settings. Just like the SetPickupType value, the Squad-value is entered as a string, but with a numerical value. What that means is that you either insert the string "21" in the right-hand side of the Hex-Editor (as ASCII-characters) or in the middle as the Hexadecimal values 32 31 (= ASCII-char "2" followed by ASCII "1"). And while we're at it, why not change the Object Label for the Focke-Wulf from "model1" to "Fw_190"? This won't cause much trouble, as it has the same string-length....

<< Page 2 Tutorial Page 4 >>