Series Tutorial

Introduction :

This tutorial will explain the inner workings of series files, as well as the other items associated with series - the missions, and the file game\cdlayout.iff. It will also briefly mention the file menu\splashfn.iff, which is used in relation to splash screens. Although you need to edit the EXE in order to specify the name of the series file you want the game to use, this is not covered here - refer to the EXE editing tutorial instead.
Missions will only be discussed very briefly, and only from the point of view of series files. Also, parts of the series file itself will be given only a general description - namely, the parts that deal with room files, which are a subject for a different tutorial. At the bottom of this tutorial, there is a link to a WCP Pascal version of WCP's original series file - it is a good idea to examine it closely after reading the tutorial.
A note about terminology - for clarity's same, whenever I refer to a 'function', this means a set of commands joined together in a function structure like this: function <name>; begin <commands> end;
On the other hand, 'command' means just that - a one-line WCP command. 
All (known) WCP commands are listed inside lib\wcp.pas. While these two 
terms are generally used interchangeably, it is a good idea to 
distinguish between one and the other because their names are frequently 
very similar.
               First, game\cdlayout.iff. This file is a sort of database 
               of all the MIS files that the game uses (apart from 
               the sim missions). If a mission is not in here, it cannot
               be used in the series.
               The structure of the file is very simple. It contains 
               the form LOUT, which in turn contains one VERI chunk, 
               and one LIST chunk. The LIST chunk contains the data 
               about the missions (six lines for each mission), while 
               the VERI chunk contains just one line of data. This line 
               contains the number of missions in the LIST chunk. I am not 
               sure, but I do not believe the game actually checks the 
               VERI chunk, so this entry probably does not make any 
Here is a sample mission data entry inside the LIST chunk, with a basic 
description next to each entry:
// unknown enemy intro
               long 0 //mission number - you'll refer to this in the 
               series file
               long 1 //CD number - do not change, unless you intend to 
               use more than one :)
               cstring "intro.mis" //mission file to be used
               cstring "silence" //music file to be used in mission
               long 0 //number of mission name string, from language\
               long 15 //unknown - 15 seems to work, so...
That is all there is to be done for cdlayout.iff. The series file
The next, and obviously most important stage is the series file itself. 
You can call it whatever you like, just remember to edit the EXE 
appropriately (see EXE editing tutorial for details). 

In this section, I will be using examples drawn from the WCP series file. 
However, because of differences between the language originally used to 
build the series file, and Thomas Bruckner's WCP Pascal, what you will 
see here is not the  original WCP series file, but rather a 
reconstruction of this file in WCP Pascal. Although I have checked this 
reconstruction quite  thoroughly, it is possible that there are some 
mistakes in it as far as the mission branches go; nonetheless, the code 
itself works properly.
The file begins with all the usual stuff that appears in one form or another 
in most WCP Pascal files:
series prophecy; // the name of the SRS file after compilation
               #include wcp;
The next stage is to add all the constants, and in particular, a 
constant for each mission. For example:
               //Series B
               MISSION_B1 = 0,
               MISSION_B2 = 1,
               MISSION_B3A = 2,
               MISSION_B3B = 3,
               MISSION_B4A = 4,
               MISSION_B4B = 5,
               SFX_RandomPavo_ENG_09 = 209,
               SFX_RandomPavo_ENG_10 = 211;
Why bother with constants for every mission? It is simply easier later 
on refer to missions using a constant rather than trying to remember 
what mission number 56 in cdlayout.iff was. Similarly, it's easier to 
declare constants for sound effects than trying to remember what each 
of WCP/SO's 233 sound effects (plus whatever sounds you add) is. As a 
general rule, use constants as much as possible, in any situation possible. 
A series (or indeed, a mission) with declared constants is no different in 
functionality to one which uses numbers directly, but the code is much more 
Next are the variables. The difference between a variable and a constant 
is (obviously) that the value of a variable can change during execution 
of the code, while a constant is, uh, constant. The WCP series file uses 
many, many variables. A variable can be declared with a particular initial 
value, but this is not necessary. Here is just two or three to give you 
an idea of what they are used for:
               g_B1_WON = 0,
               g_B2_WON = 0,
               g_B3a_WON = 0,
               g_Attaboy = 0;
Of the above, perhaps the most significant variables are those first three 
- g_B1_WON and the like. These sort of variables are used as a means of 
communication between the series and the individual missions. Having 
declared the variable in the series file, you then declare it inside the 
relevant mission file, using the "external" form of declaration:
Having thus declared it, the mission can now alter this variable. Here 
is an example of how this is done in one of the Unknown Enemy missions:
if (m_Failed) then begin
               g_UE_1_Won := false;
The above code is called at the player's home navpoint after the player 
returns from the mission, if the mission's internal variable "m_Failed" is 
true (ie., equal to 1). Once triggered, the code declares the mission's 
objective (the constant "mobj_locate_fralthi") as failed, and then sets 
the value of the external variable "g_UE_1_Won" as false (ie., equal to 0).
On the other hand, had the "m_Failed" variable been false, the 
"g_UE_1_Won" variable would have been set to true.
Having gotten the hang of modifying these variables, let us now take a 
look at how they are used in the series file. The most important part of
the series file is the "MCP" function. This function controls the campaign's 
flow; it plays certain movies (but not all - most movies in WCP are triggered 
by the missions), triggers the "get callsign" screen, the end credits, and
the individual missions. Here are a few extracts from the WCP series file, 
with comments included directly in the code:
function MCP;
               // We begin by playing the intro movie
               // And then we get the callsign
               // Series B
               // Despite its misleading name, Series B is the first series 
               of WCP.
 // The first mission branch. If the "g_B2_WON" variable is true,
               // that is, if the player fulfilled B2's win conditions, 
               mission B3A
               // is played. If this is not the case, we go to B3B
               if (g_B2_WON) then
We now skip a bit and go to Series C. There is an interesting type of branch 
there. Mission C1 sets two external variables - "g_C1_ENGINES_DAMAGED" and 
"g_C1_BRIDGE_DAMAGED"  depending on the state of the Midway at the end of 
the mission. These variables are then used to determine what mission is 
played next, showing you just how endless the possibilities are for mission
branch triggers. If you really wanted to, you could have a mission branch 
triggered if the player has exactly 95% damage and had killed an alien 
ship named Fred during the mission. Take a look:
               //SERIES C
               // Run c2a if completely successful
               // Run c2b if bridge damaged
               // Run c2c if engines damaged
               // End of game if both the engines and the bridge are damaged
               // (this is handled internally by mission C1)
               if ((g_C1_BRIDGE_DAMAGED <> 1) and (g_C1_ENGINES_DAMAGED 
               <> 1)) then
               if (g_C1_BRIDGE_DAMAGED) then
               if (g_C1_ENGINES_DAMAGED) then
Now we will skip a big chunk of the MCP function, and go to Series H. We 
want to take a look at WCP's fighter-selection missions there. In 
particular, we will be interested in "MISSION_H1_choos". Take a careful 
look at this section of the campaign, and then I will explain what is 
going on.
               //SERIES H
               // Allow the player to choose between H1y and H1z, 
               // based on the ship he chooses.
               MCP_ShipSelector (ShipId_C_vampire, ShipId_C_devastator);
               if (MCP_GetSelectedShip = ShipId_C_vampire) then
               // Player chose Vampire
               // Player chose Devastator
So, what is this MISSION_H1_choos? If you remember WCP, the first mission 
in Series H was the Vampire/Devastator mission... yet, the series contains 
the additional MISSION_H1_choos. This mission is very unusual - it contains 
no spaceflight section. It's only gameflow. Let's take a quick trip to 
the mission files to figure out what that means.
Gameflow, being the opposite of spaceflight, is the part of the game when
you are onboard the Midway and can choose, for example, to go to the 
Rec Room. This gameflow element is triggered by the MS_RunGameflow command 
inside individual missions, usually prior to the MS_RunSpaceflight command 
(which launches the spaceflight section). This is all done inside the 
mission's MAIN function. For example, like this:
function MAIN;
               MS_RunGameflow(0); // gameflow
               MS_RunBriefing; // pre-mission ICIS-style briefing
               MS_RunSpaceflight(0); // spaceflight
               MS_RunDebriefing; // post-mission debriefing
A MAIN function does not need to contain MS_RunGameflow or MS_RunBriefing:
function MAIN;
In this case, following the end of the previous mission, the player 
would find himself in the cockpit. However, since he would not have the 
opportunity to move around the Midway, he would not have the opportunity 
to save the game; nor would the game be able to autosave - autosaving is 
only done in missions with gameflow.
The MAIN function can contain any of the commands that begin with "MS_". 
Those, however, will not be covered inside this tutorial. And what about 
H1_choos? Well, its MAIN function contains this:
function MAIN;
               SYS_PlayMovie (1560);
 //everyone gets promoted to Wolf Pack
               MS_ChangePilotSquadron (Pilot_Player_1, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_2, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_3, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_4, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_5, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_6, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_7, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Player_8, SN_wolf_pack);
 MS_ChangePilotSquadron (Pilot_Maestro, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Stiletto, SN_wolf_pack);
               MS_ChangePilotSquadron (Pilot_Zero, SN_wolf_pack);
 //briefing start
Note the MS_ChangePilotSquadron command, by the way. The MAIN function 
plays movie 1560, then promotes the player, Maestro, Stiletto and Zero to 
WolfPack... but it promotes eight players! Is this perhaps evidence that 
WCP had been supposed to have a cooperative multiplayer campaign mode? 
Anyway... after the promotions, the function runs the gameflow, giving 
the player an opportunity to autosave. Then, when the player is ready 
to proceed, he goes to the briefing room, and watches briefing movie 2220. 
And then the mission ends.
So, what is the point of Mission H1_choos? Originally, I thought that 
the choice of ship was done inside this gameflow-only mission. As you 
can see above however, this is not the case - the ship selector is 
triggered after H1_choos is finished, but before either of the two 
fighter-based missions are started. So, H1_choos does not influence the 
fighter choice, and it doesn't contain a spaceflight section. At first 
glance, it seems that the series would work exactly the same if this 
"mission" didn't exist at all - those movies and promotions could be placed 
in the next mission, after all.
The reason for H1_choos' existence becomes more obvious if we study how 
the MCP_ShipSelector command works. This command presents the player 
with a choice of two fighters. The choice is then memorised and triggered 
in the very next mission. The choice can also be checked using the command 
MCP_GetSelectedShip, and used to trigger a different mission depending 
on what fighter the player is flying.
The problem with this is that MCP_ShipSelector is only a single command.
It's not a mission, so it cannot have a gameflow element. Therefore, 
you can't autosave prior to making the choice. What's more, once the 
choice is made, the only way to choose again is to complete the mission 
that came just before the choice. Thus, MCP_ShipSelector used by itself 
only works fine if you have no need to restart. What happens if you choose 
a ship, go out on the mission, die and then try to restart? There are two
1. If this mission has a gameflow element (ie., after choosing the ship, 
you go back to roaming the Midway, Cerberus, or wherever else you are), 
you will restart the mission WITHOUT making the choice again. So, when you 
play the mission the second time, instead of flying your chosen fighter, 
you will use whatever ship the mission assigns the player by default. 
Obviously, this is not an acceptable option.
2. On the other hand, if this mission has no gameflow element (after 
choosing the ship, you DON'T roam the Midway, you go straight into 
space or into the pre-mission briefing/movie/whatever), restarting will 
take you back to the start of the previous mission. You will be able to 
make the choice, but first you will need to complete the previous mission 
again. This is also not an acceptable option, unless... the previous mission 
has no spaceflight. It's dead easy to complete a mission when you don't 
need to get into the cockpit to do it, right? :)
So, that's the reason for the gameflow-only H1_choos. The mission is 
there to give you an opportunity to save prior to going into H1y or H1z, 
both of which contain an ICIS briefing and spaceflight, but no gameflow. 
An additional bonus is that in the History mission list, we do not 
see separate name entries for H1y and H1z - we only see a name for 
H1_choos. This suits us just fine, since the idea is to make the player 
think that H1y and H1z happen at the same time (and therefore, only one 
can be chosen).
The above also explains what happens during WCP's only real double mission 
- Defang The Beast. These are of ourse two missions. Like the H1_choos and 
H1y/H1z combination above, the first mission of Defang The Beast contains 
gameflow, while the second doesn't. The difference is that in this case both
missions also contain spaceflight. So, upon dying in the second mission of
the Defang The Beast duet, you have to go back to the start of the first 
One more thing to note before we move on - MCP_GetSelectedShip. In the 
series H code we saw earlier, the player actually played a different 
mission depending on what ship he chose. This is not actually necessary 
- you could give the player the option of playing the same mission in two 
different ships. The series H code would then look like this:
               //SERIES H
               // Allow the player to choose the ship,
               // then go into mission H1 regardless of the choice.
               MCP_ShipSelector (ShipId_C_vampire, ShipId_C_devastator);
Of course, in this case you could make the series code even simpler - 
you could get rid of H1_choos and MCP_ShipSelector, and instead add 
MS_ShipSelector to H1's MAIN function, since MS_ShipSelector is 
identical in effects to MCP_ShipSelector. The downside of this would 
be that the player's wingmen (and the rest of the mission, obviously) 
would be unaffected by the fighter choice (there is no 
MS_GetSelectedShip). You'd be flying a Vampire for example, while they'd 
be flying the Devastators assigned to them by the mission code. Using 
separate missions depending on the player's choice gives you much more 
We are just about finished with the MCP function. The last thing left to do 
is to explain the several "MCP_" commands which were not used in the examples 
above, but which can be very important for us.
MCP_EscapeMenu - this command triggers the options menu (usually 
triggered by the Escape key). It's really only useful at the end of the 
campaign, since at other times the player can trigger the menu by himself.
MCP_Exit - very self-explanatory. This command exits the game. Useful 
at the end of the campaign. Can also be used in the middle of a campaign, 
if you want the player to exit the game after the loss of a particular 
mission (and after seeing some sort of losing scene, of course). 
MCP_ShowSplashScreen(num, sec) - this command shows a splash screen. 
The first variable (num) determines the number of the splash screen 
(drawn from menu\splashfn.iff, which will be explained in a moment), while 
the second determines the length of time in seconds that the screen will be 
displayed if the player doesn't skip it manually.
MCP_WinningEndgame - shows the winning end game. In WCP, this is the bit 
where the credits scroll by on one half of the screen while the other half 
plays a mission file called wendgame.mis. In SO, it's identical to WCP's 
losing endgame, with credits scrolling by on top of an image (called 
Splash Screens
               Before we go on to the rest of the series file, let us 
               take a quick look at the structure of the file 
               FORM "SPSN"
               CHUNK "FILN"
               cstring "splash_one"
               cstring "splash_two"
...It's as simple as that. The FILN chunk contains a list of all the 
splash screen filenames. These images are stored inside the menu directory, 
and all have the extension IFF. For example, "splash_one" is actually 
menu\splash_one.iff. The first variable of the MCP_ShowSplashScreen command 
mentioned above is nothing more than a reference to a line number inside 
splashfn.iff. These numbers begin with 0. So, for example, 
MCP_ShowSplashScreen(0, 30) would display menu\splash_one.iff for 30 seconds.

The Room-related Commands
               The main section of the series file is usually followed 
               by the room-related functions (though of course, you could 
               place these anywhere in the series file, as long as they're 
               outside of the MAIN function). These functions basically 
               tell the game how to react to the player's interaction 
               with the room that he's in, between the missions. They use 
               the set of commands that start with "GF_".
The name of the function for each 'hotspot' in the room is set in the room 
file itself (room files will be discussed in a separate tutorial). Each 
hotspot should, but doesn't need to, have references to three different 
functions, activated under different circumstances (mouse click on the 
hotspot, mouse moving over the hotspot, and mouse moving away from the 
hotspot). Note that while not every hotspot needs to have all three functions 
in the room file, all the functions specified in the room file MUST be 
present and accounted for in the series file.
As an example, we will take a look at WCP's "rec.rom" room file. This 
file contains a hotspot which refers to a function called 
G_RunTrainingSimulator (no prizes for guessing what this hotspot does, 
folks). So, in WCP's series file, we find the corresponding function...
function G_RunTrainingSimulator;
Pretty simple, isn't it? All it does is run one of WCP's "GF_" commands, 
which we'll go over in a moment. First, however, let's take a look at 
another function from WCP's series file. Although there's no limit to how 
complex room-related functions could get, WCP's room-related functions 
generally do not get more complex than this one:
function G_Simulator_Hover;
               if (GF_GetRoomVar(12)) then
               SYS_PlaySFX (SFX_SimDoorOpen);
               if (GF_HotspotCurrentFrame > 8) then
               GF_SetRoomVar (13, 1);
What's going on above? This is the function which is activated when the 
player moves his mouse over the simulator hotspot (as opposed to moving 
away from the simulator hotspot - that's handled by G_Simulator_Fidget).
This function, in spite of its apparent complexity, in fact does almost 
nothing. First, it checks if the room variable number 12 is true (the 
GF_GetRoomVar(x) function, explained in further detail below). This 
variable is set true by the G_Simulator_Fidget function - in other 
words, if the player has just moved the mouse away from the simulator 
hotspot, variable number 12 is true (of course, you could use any other 
variable for this purpose). So, assuming that this is the case, the Hover 
function does two things - it plays the sound effect of the sim door opening,
and sets the room variable 12 to false, so that if the player continues 
to hover over the sim, it won't happen again.
Regardless of whether the room variable 12 is true or not, the function 
then goes on to set the room variable number 13 to false (this variable 
is another link to the G_Simulator_Fidget function, which plays the sim 
closing sound effect if 13 is true). This is followed by one more IF 
statement, which checks if the sim hotspot's animation frame is greater
than 8. If this is the case, it sets the room variable number 13 to true.
It is interesting that the function would set 13 to false, only to 
immediately set it back to true depending on how far the hotspot's 
animation has proceeded. The idea behind this is to ensire that if the 
player moves the mouse over the simulator hotspot for only an instant, 
the game will know that it shouldn't play the sim closing sound effect 
when the G_Simulator_Fidget function goes into effect. For clarity's sake, 
here's G_Simulator_Fidget. No explanations of what it does, since it is 
essentially the reverse version of G_Simulator_Hover.
function G_Simulator_Fidget;
               GF_SetRoomVar(12, 0);
               if (GF_HotspotCurrentFrame = 0) then
               GF_SetRoomVar(12, 1);
 if (GF_GetRoomVar(13)) then
               SYS_PlaySFX (SFX_SimDoorClose);
               GF_SetRoomVar (13, 0);
The WCP series file contains many other hotspot functions, but it would be 
pointless to examine them right now. You may want to take a look at them 
later, however. For now, let's quickly go over all the "GF_" commands to 
see what these things can do.
GF_Exit - this command exits the gameflow, taking the player into 
whatever mission is up next.
GF_ExitGame - exits the game, plain and simple.
GF_GetRoomVar(variable) - this command checks the value of a specific 
room variable. It is used exactly the same way as any "SF_Get" commands.
GF_HotspotCurrentFrame - checks the number of the frame currently being 
displayed by the active hotspot. Used the same as GF_GetRoomVar above.
GF_HotspotDisable - I have not used this command yet. Presumably, however, 
it disables the active hotspot until further notice.
GF_HotspotEnable - Haven't used this one either, but it's probably the 
'further notice' to the command above ;).
GF_LoadRoom(num) - This command switches the player to a different room. 
Note that the rooms are referred to not by name but by number, starting 
from 0. In order to use this command at all, you must declare at least 
two rooms in the current mission - the first one will become room number 
0, the second will be 1, and so on. If you try to switch to a room which 
has not been declared in the current mission, the game will crash. To 
declare rooms inside a mission, use the "#SetRooms" command.
GF_QuickLoad - This command allows the player to load a previously-saved 
GF_QuickSave - This command allows the player to save the game.
GF_RunBriefingComm(series, comm) - This is the command used during the 
Hhrass Relay Station mission to play Dekker's briefing. Essentially, the 
command simply plays a special comm with a fancy computer-terminal background 
around it.
GF_RunMainTerminal - This command allows the player to access the history 
GF_RunKillboard - If you can't guess the meaning of this one, why  are you 
reading this? :)
GF_RunObjectViewer - Runs the object viewer.
GF_RunStellarMap - Runs the stellar map. Or at least it would, had the 
stellar map been implemented. As it is, the command leads you to a useless 
place-holder screen.
GF_RunTrainingSimulator - Hmmm...
GF_SetRoomVar(variable, TrueorFalse) - This command allows you to change 
the value assigned to a particular room variable. Presumably, you can 
assign any value to it; however, I have not seen any function where it 
would be worthwhile to assign a value other than true (1) or false (0).
This essentially concludes the room-related functions, which are the last 
'compulsory' element of any series file. It is worth noting however that you 
can include other functions in the series file - these functions can then 
be accessed in your missions, provided you use the "#include" command.
And that's the end of the series tutorial. It is my hope that this 
tutorial covers everything that's needed for series files. However, 
keep in mind that I wrote this tutorial over a fairly lengthy period - as 
I write this, I can only vaguely remember the beginning of this file. 
Thus, it is quite possible that I skipped something or made a mistake 
somewhere. It is therefore a very good idea to take a close look at the 
WCP series file.
WCP series file
SO series file

Tutorial by Quarto