Creating a campaign

by kaoz | MMXXIV

  1. Folder structure  
  2. Overwriting a original BK campaign  
  3. Creating a custom campaign  


1. Folder structure

As with the older guide Creating a Custom Chapter, again I need to underscore the importance of understanding the directory structure, especially in case of a custom campaign. In this guide, next section, I will first go through the process of replacing an original BK campaign, which is easier to understand and causing less work and certainly less confusion.

I guess I also need to point out that most of the following examples are based upon a mod's point of view, because that's the result of my personal experience so far in this matter.
The next screenshot shows what folders we are going to need in the Run\data\scenarios folder.

Obviously, the folder Data\Maps contains your actual maps, (.bzm and/or .xml + lua) and the Data\Scenarios\scenariomissions folder containing the mission header, settings (1.xml), header and (mission) descriptions for your maps, put under a specific one of the three main parties, being allies, german and ussr. Just pointing at this because the maps (and chapters) need to be well in place for the campaign to work properly.

The Scenarios\campaigns and Scenarios\chapters folders are used to overwrite the original BK ones. However, the Scenarios\campaigns is used also in case of a custom campaign, which I will explain later in this guide. Needless to say that the Scenarios\custom\campaigns and Scenarios\custom\chapters folders contain custom stuff. Do mind the difference here! I can't stress out enough how the path references to these folders need to be correct in the Lua-script and the various 1.xml's (mainly of the chapters). If not, the campaign will cause the game to crash or freeze.

Let's have a quick look what files are in the Scenarios\campaign\german folder. Notice we have to choose one of the three main parties again, in this example german.

Basically, a campaign folder needs to contain only the following files:
  • german.xml contains the actual campaign information, overall settings and references to the (custom) chapters
  • header.txt showing the campaign title in-game
  • map_h.dss showing the campaign map picture in-game
  • description.txt seems useless, as the campaign starts showing the chapter description
  • subheader.txt also seems not being used

In the next section, we'll have a deeper look at the german.xml, which is most important here. Also notice there's no Lua-script needed for a campaign. However, the Lua-scripts within the chapter folders become very important.

Return to index  


2. Overwriting a original BK campaign

When overwriting, remember we only use the Scenarios\campaigns and Scenarios\chapters folders. No custom folders! Make sure your chapter folder(s) need to be in the Scenarios\chapters folder and here again, they need to be put under a specific one of the three main parties, so the coming examples will use the Scenarios\chapters\german folder. Change to allies or ussr if needed.

Let's have that look at the german.xml.

You should know by now the <History> tag doesn't mean much, besides some export information.
The <KeyName> isn't that important either, i guess. Well, I don't know when it could be of any use.
<StatsType> obviously needs to be set to Campaign.
As usual, we then have our path references to the header, map and such. This is also common knowledge, right? Same for movies and music.

The <AllChapters> tag needs to refer to the 1.xml of each chapter. Again, when overwriting the original BK campaign, those paths have to be scenarios\chapters\german\mymission\1 (depending the party).

The PosOnMap holds the x and y coordinates to which the crosshair for each chapter will be set on the campaign map image. This will be shown in the campaign information screen, at the start of each single chapter.

Finally, set the correct party for the <PlayerAllianceSide> and mod settings if needed. And that's it; the german.xml doesn't seem to be that complicated. In case your chapters won't start in-game, double-check your references here.

From this point on, we need to have a look at the chapters Lua-scripts. Each chapter item within the german.xml will load the chapter's 1.xml and the chapter's Lua-script when needed in the progress of a campaign. How to create chapters has been previously explained in Creating a Custom Chapter guide, so I'm not going through that here, but let's have a look at the chapter's Lua-script.

Imagine we have a three chapters for our campaign. 01_alfa, 02_beta and 03_delta. Chapter 01_alfa contains four maps and has the following script:

Starting the campaign, the game will load the first chapter written in the campaign's german.xml, which in this example would be 01_alfa. The Lua-script starts with the EnterChapter function and will enable the first mission (01_mission). Do mind the difference between double and single backslashes! In the following MissionFinished function, conditions are used so that when each mission becomes finished, the next will become enabled. Finally, when the fourth mission (04_mission) becomes finished, we need to enable the next chapter (02_beta). This chapter contains three maps and Lua-script looks like this:

Basically the same. Again, enable each mission and in the end the next chapter (03_delta). This chapter also contains three maps and the Lua-script looks like this:

The only difference here, is that when the last mission is finished, you use the FinishCampaign instead of enabling another chapter.

And that's pretty much it. You can, of course, use more code in the Lua to add medals or unit upgrades and such, but I kept those out here to focus only on the basic, necessary stuff, hoping you will understand. If not, you can download this sort of template with a basic structure to start from. Also check GordonCZ's Achtung Panzer and/or bb's Road to Leningrad that have used this overwriting method. I learned from analyzing their files!

Return to index  


3. Creating a custom campaign

For many, many years, I had tried to create a custom campaign, but always ended up crashing or freezing. I also often tried to use the ResEditor, trying to understand its generated files and parameters. Many times I had copied the ResEditor's export to a Scenarios\custom\campaigns folder and then changed all path references to my custom chapters in Scenarios\custom\chapters of course. Whatever I tried, I couldn't get it working properly and had put this aside for another many years. Last November, it came again to my attention and wanted to give it one last attempt. I couldn't believe this being impossible while the ResEditor being capable of creating and exporting the needed files.

At the point when copying the export to my mod's Scenarios\custom\campaigns, I realized there was still an earlier version inside and started to doubt whether to overwrite this. I chose not to and instead copied it to Scenarios\campaigns as a sort of newer backup before checking out its parameters and references. In this process, I suddenly found my custom campaign working and I was stunned. WTF?

At first, it seemed very confusing as I didn't know which of two campaigns was now working. Therefor I changed header files, descriptions, xml's to see the difference between them and then came to the conclusion that it seems to use both. Now I was even more baffled. I used those changes/differences to follow BK's logic and will try to explain.

When you start up the game and browse your way through the menu to the Custom Campaigns, you get the list of available custom campaigns. Here BK shows the header from my Scenarios\custom\campaigns folder and it knows the exact number of chapters that are listed in the giovani.xml, being 15. BK doesn't use the description, map_h and subheader that can be seen in the folder tree screenshot. Those are just the remnants from my previous export attempt.

Then, when you select the campaign from the list, BK switches to the header, map_h and german.xml from the Scenarios\campaigns folder. That's pretty strange! So even for a custom campaign, BK needs to use and overwrites the standard campaign. And the reason why I never got the custom campaign working, not realizing this. Here BK again, doesn't use the description and subheader. The folder tree structure in the screenshot contains the (latest attempt) exported files from the ResEditor.

I consider myself lucky here that BK does find my chapters within the Scenarios\custom\chapters folder, because they are not stored in a allies, german or ussr folder. I'm surprised this isn't causing any crash! This only being possible because I set the path references to the chapters correct in the german.xml. In my testing here, I had put 15 chapters in the giovani.xml and only 3 in the german.xml so I could see which xml BK would be using throughout the game. It appears to be the german.xml. I hadn't renamed this because it got exported that way. I guess if I would rename it, the game will probably crash again. For the custom chapters folder you can see renaming it (to giovani), doesn't harm, but then the giovani.xml seems only to be used in the first step (the custom campaigns list), which of course, I never could have imagined.

Let's have look at that german.xml:

We're looking at an xml exported by the ResEditor. Notice the ResEditor has set some standard tags like Intro and Outro movies and music. You can of course, disable them (as I will) or refer to your own stuff.

Most important however here, are the path references to your chapters. As mentioned before, I had used only 3 in the german.xml. Truly, I can't remember if I was able to select these in the ResEditor or if I changed them manually. But anyway, this is the big difference between overwriting or custom, I think. When overwriting, we are obliged to use the Scenarios\chapters\german folder, where as with custom we are somewhat 'free' to refer to any other folder (containing the chapter files). In this example Scenarios\custom\chapters. I didn't even create a german folder. (*edit* Who knows I might regret this later. So far, the campaign is working, but maybe it's better to use a party folder, simply not to challenge the BK logic.)

Okay, when we move on further in-game, we get to the (first) chapter screen.

We should be familiar with this and know how to create custom chapters. If not, check the Creating a Custom Chapter guide. I only want to mention here, that it is kinda sad that this screen displays the mission description instead of the chapter description. I would expect to see a campaign description in the campaign screen, a chapter description in the chapter screen and a mission description in the mission screen. But sadly, no. That piece of BK structure was invented on a monday morning, right?

In this example, you can see that I've put the missions into the standard scenarios\scenariomissions\german folder. Changing this might work as long as you keep the path references correct, but I've never tried it, not to awaken any sleeping dogs. On the other hand, I believe it might be needed for the custom chapter to work properly, so again, better not mess with BK's logic. In the end, that logic always seems to come down to need of having to choose one of the three parties.

Then finally, further in-game, we get to the mission screen where we can start it.

One last thing maybe, concerns the Lua-script for a custom chapter. It's not that different from the one overwriting the original BK campaign.

This example shows only 1 map in the chapter, but no matter how many maps, after the last one, be sure to have the correct path reference to the next chapter.

So, the custom campaign demands a little more work and a sharper focus on your reference paths. At this moment however, I see no real advantages here in comparison with the overwriting method. A bit naive maybe, but I always wanted to use the custom way just because I thought this was the way to go. With one of the hopes being, to be able to create multiple campaigns for the same party. Logically, this seems impossible if BK still switches to the german.xml and uses that. Somewhat disappointing, because one can only create three campaigns, one for each party. I guess, it is what it is.

Hope this made sense!

Return to index