Setting up Campaigns

This article is an attempt to describe the various options mappers need to consider when setting up campaigns or multi-mission packages (I'll refer to campaigns for both of these for the sake of simplicity). Campaign support has been added in TDM 1.06.

Map Files

Regular, single-map TDM missions are packed in PK4 files, campaigns are no different. If your campaign consists of three missions ("red.map", "blue.map" and "green.map"), all three of them still go into the same maps folder in your PK4 file.

The actual order in which the missions are to be played is defined through the tdm_mapsequence.txt file, which should be added to the PK4 (just next to the readme.txt). Following the example of the "red", "blue" and "green" maps above the map sequence file would look like this:

Mission 1: red
Mission 2: blue
Mission 3: green

Looking at that, the syntax of the file is pretty much self-explanatory. The first mission has the number one, the map file is mentioned after the colon and the following space. You don't need to specify the ".map" extension of the map file that is handled automatically. See the main tdm_mapsequence.txt article for further reference, for this article it's enough to have the above lines I suppose.

Briefings

Once the map sequence is defined one needs to take care of the briefing. If you like to keep it simple, just refer to the Briefing article in the Text-only Briefing section. Each map needs its own xdata block with the briefing and you'll be done.

For advanced setups like the "Timed Flowing Briefing" mentioned in the Briefing article there are a few modifications to be made to your GUI code. As the mainmenu_briefing.gui file is the same for the whole campaign your GUI needs to know which map the player is about to play next. For this purpose a new GUI variable gui::CurrentMission has been introduced which can be used in if-else GUI code blocks in the BriefingStateInit windowDef. For single-missions, mappers just called the GUI animation block like this:

windowDef BriefingStateInit
{
	noTime 1

	// Init methods have onTime 10 instead of onTime 0.
	onTime 10
	{
		// ... stuff

		set "BriefingAnimation::visible" "1";
		resetTime "BriefingAnimation" 0;

		// ... stuff
	}
}

For multi-mission setups an if-else block should be added to switch to the correct briefing animation for the current map:

windowDef BriefingStateInit
{
	noTime 1

	// Init methods have onTime 10 instead of onTime 0.
	onTime 10
	{
		// ... stuff

		if ("gui::CurrentMission" == 1)
		{
			set "BriefingMission1Animation::visible" "1";
			resetTime "BriefingMission1Animation" 0;
		}
		else if ("gui::CurrentMission" == 2)
		{
			set "BriefingMission2Animation::visible" "1";
			resetTime "BriefingMission2Animation" 0;
		}

		// ... stuff
	}
}

Of course you'll need to define a BriefingMissionXAnimation block for each mission. You can use the instructions in the Briefing article to learn how to do that, just keep in mind to change the windowDef's name such that you don't end up with duplicate names for your windowDefs (this will lead to warnings in the console at game startup at best).

Starting the correct mission briefing animation is only half the rent, you'll need to stop the correct animation as well when the player proceeds to the objectives screen:

windowDef BriefingStateEnd
{
	noTime 1

	onTime 0
	{
		// ... stuff

		if ("gui::CurrentMission" == 1)
		{
			set "BriefingMission1Animation::visible" "0";
			set "BriefingMission1Animation::notime" "1";
		}
		else if ("gui::CurrentMission" == 2)
		{
			set "BriefingMission2Animation::visible" "0";
			set "BriefingMission2Animation::notime" "1";
		}

		// ... stuff
	}
}

If you don't do that the player might see remnants of the previous mission's briefing when proceeding to the next map briefing.

Briefing Videos

It's possible to define briefing/intro videos for each mission in a campaign. To enable videos mappers need to include a mainmenu_custom_defs.gui file in their PK4 and define a few variables in there. You can look at the default file in the TDM PK4s to get more info and read some comments. I'll include the most important settings briefly here:

Enable SDK-controlled briefing videos by adding this line to your mainmenu_custom_defs.gui file (or uncomment the line if it is present already but commented out):

#define BRIEFING_VIDEO_CONTROLLED_BY_SDK 1

Next you'll need to specify which video to be played for each mission. These are bit more complex:

#define MM_BRIEFING_1_VIDEO_MATERIALS "video/tdm_briefing_video;guis/video/credits/typing_sequence01;"
#define MM_BRIEFING_1_VIDEO_LENGTHS "4000;5000"
#define MM_BRIEFING_1_VIDEO_SOUND_CMD "music video/tdm_briefing_video_sound;"

Easy to see, these three definitions refer to the first mission in the campaign, the prefix is "MM_BRIEFING_1".

The MM_BRIEFING_1_VIDEO_MATERIALS line specifies the various ROQ materials that should be played (in this order). ROQ files have a maximum length of 60 seconds, so TDM added support to a sequence of ROQs to allow for longer videos. The materials should be separated by semicolons. Be sure to define the playback duration of each clip in the VIDEO_LENGTHS line.

The next line MM_BRIEFING_1_VIDEO_LENGTHS corresponds to the MATERIALS line above and contains the playback duration of each ROQ clip. The time is specified in milliseconds, multiple times are separated by semicolons.

The last line in this triple is defining the sound to be played along the video: MM_BRIEFING_1_VIDEO_SOUND_CMD. Sounds don't have a length limit, so there is no need to define multiple sounds like with the ROQ clips. Be sure to include the "music" command in the string and to refer to a valid sound shader.

The original TDM mainmenu_custom_defs.gui file contains a lot of comments about these defs, please take a look there to learn more.

Side note: the SDK-controlled video is also available in ordinary (single) mission packs. You don't need to build a full-blown campaign (with tdm_mapsequence.txt, etc.) to use this option, it's enough to make the correct #DEFINE statements above.

De-Briefing Videos

With TDM 1.06 and upwards it's possible to have a video played back immediately after "Mission Complete", so-called de-briefings.

The mechanism to set these up is very similar to the above "SDK-controlled" briefing videos, all you need is to add the correct #DEFINE lines in your mainmenu_custom_defs.gui file:

#define MM_DEBRIEFING_1_VIDEO_MATERIALS "guis/video/credits/typing_sequence01;"
#define MM_DEBRIEFING_1_VIDEO_LENGTHS "2000;"
#define MM_DEBRIEFING_1_VIDEO_SOUND_CMD "music tdm_mainmenu_background_music;"

This example will play a credits video after "Mission Complete" for 2 seconds (= 2000 milliseconds). Please refer to the above "Briefings" section to learn about the precise meaning of these lines, they are pretty much analogous.

Side note: this option is not exclusive to campaigns, you can have a de-briefing video in single-mission setups just as well.