||1. Folder structure
a chapter with the ResEditor
||3. Creating a chapter from existing
||3.1 The 1.xml
||3.2 The script.lua
||3.3 Remaining files
1. Folder structure
First, let's have a look at the directory structure,
which is pretty important to start with. In case you experience game
crashes right after selecting the chapter from the in-game custom
chapter list, you should double-check the directory structure. It
simply needs to be correct.
The following screenshot shows only the maps and
scenarios folders in the Run\data
Of course, this folder contains more, but I have erased those just
to simplify things.
The folder Blitzkrieg\Run\data\maps contains your
actual map, obviously (.bzm + lua).
In case of mod, that would be Blitzkrieg\Run\mods\mymod\data\maps.
(* Path references might be slightly different on the Steam BK version).
The folder Blitzkrieg\Run\data\scenarios\custom\missions\mymission
contains your mission header, settings (1.xml), header
and (mission) descriptions. However, this folder will need to be moved
when coming to the point of building the chapter.
As far as I've understood and correct me if I'm wrong, but within
the BK campaign and chapter structure, one is always obliged to place
the map mission files in one of the three main parties, being allies,
german and ussr. No escape from
this, I'm afraid.
Therefore, at some point, you will need to copy your map mission files
(from \Run\data\scenarios\custom\missions) to the
\Run\data\scenarios\scenariomissions folder. This,
of course, means that all reference paths (xml + lua)
also need to be changed to the correct folder. This will, later on
in this tutorial, be explained in more detail. For now, only remember
the chapter map missions directory tree should look like the following
In case of a mod, the directory path would be \Run\mods\mymod\data\scenarios\scenariomissions\allies\mymap
The third and last, but most important folder \Run\data\scenarios\custom\chapters
contains all the necessary chapter files.
Basically, a chapter folder needs to contain only the following files:
There are more in the screenshot:
- 1.xml containing the actual chapter information
and overall settings
- header.txt showing the chapter title within
the in-game chapter list
- map_h.dss showing the chapter map picture in-game
- a script.lua that is needed to make the chapter
- current.chc is a sort of 'template' only for
building a chapter through the ResEditor. It
is not necessary for the chapter to work.
- description.txt has no real use unless the
chapter is part of a campaign. If so, it will show the chapter
description, but in case of a custom chapter, only the description.txt
files from within the mission folders (\data\scenarios\scenariomissions\allies\mymap)
will be shown. Personally, I keep the file there because there's
a link to it in the 1.xml and I don't want to seek any touble
by deleting it.
- map.tga is the picture file only for building
a chapter through the ResEditor. It is not
necessary for the chapter to work.
- sheader.txt is the subheader file, but honestly,
I have no idea when it becomes shown. Again, keep it there as
it is also linked to from within the 1.xml.
One last thing here that I'd like to point to, is the following recommendation
from bb (brazilian blitzer): use small characters
for all your folder and file names to avoid weird game behavior when
playing the chapter. This only concerns the folder and file names,
not the 1.xml and lua scripts, of course! It may sound strange that
using capitals would make a difference, but it seems it does. Becoming
stuck at some point in a chapter is annoying for players, so this
tip may hopefully serve to your advantage!
|Return to index
2. Creating a chapter with the ResEditor
When you open the ResEditor and select specifically
the Chapter Editor, you'll end up staring at an empty
box with no possibilities or so it seems. In fact, the editor needs
to open some sort of 'template', a 'Project'
file, which in the case of a chapter is called a current.chc
The Resource Kit contains most of the original BK
files (for use in the ResEditor) and offers a broad
variety of these chapter files depending on a certain context setting
(like summer in Africa, spring in Ukraine, winter in the Ardennes).
Having the Resource Kit is a necessity when building
a chapter with the ResEditor, or you would at least
need one current.chc file to start from.
You can download the Resource Kit here. It concerns the original
.exe file, so it will prompt you to install after download.
You only need to download this in case you want to use some standard
current.chc's with the ResEditor.
You do not need them when working with copied files as explained in
the next chapter.
If you have the Resource Kit, go to the Scenarios\Chapters
folder, choose a party and pick a chapter. Copy the folder, so you
can work from a new one instead of overwriting the original. When
a Project/current.chc has been opened in the ResEditor,
you should (more or less) see the following:
Normally, the Basic info in the bottom left pane
should be shown, if not, click on Basic info in the
upper left pane.
The bottom left pane contains Properties and Values.
Obviously, these values can be changed, but it isn't always necessary,
like, for example, if you have loaded the current.chc
from your copied folder, you should only change the
content of the header.txt file itself. Here, in the
ResEditor, the value is only a link
to the header.txt file. Same for some other values
as well, like the SubHeader, Description, Script, Setting
and Context. You might want or need to change the
Interface music, Season and/or Player
side. However, one could still change it again afterwards.
The Map image property links to the .tga
file in the folder and will build the basic _c, _l,
and _h .dds files. With Photoshop
or Gimp, you could change this file to your own chapter picture.
As said, you basically need to change the files that are in your copied
chapter folder. What the ResEditor 'creates' when
exporting it all in the end, is nothing more than a 1.xml
and a map_h.dds. The other (linked) files will be
exported as well, but they are just copies/clones, not 'true creations'.
Back in the left upper pane, under the Basic info, you'll find Missions
and Place holders. Selecting a single Mission
or Place enables the possibility to set the mission
scope/coordinates on the chapter picture. Simply click on the map
or set it in the bottom left Value pane. Notice you
can add a Mission or Place simply
by clicking on the folder and next [Insert]. Right-click
on one to delete it.
When clicking the Value of the Mission Property
at the bottom left, a list with missions will open. It is possible
that your mission isn't listed. When this is the case, it can only
mean that the mission folder (with 1.xml and .txt
files) is not in the correct folder Run\data\scenarios\custom\missions.
No panic however, these paths can later still be edited within the
1.xml (of the chapter).
Clicking the blue cross in the upper left, will show all mission crosshairs
on the map.
The Place holders are still a mistery to me as well.
The only thing I can say about them, is that they are used for random
missions. The F1 Help of the ResEditor
isn't of much help there either. Since I personally never worked with
random missions, my knowledge is scarce on this matter.
And that's pretty much it for the ResEditor. There
isn't really much more to do, for chapter building, that is. Last
phase would be the Export Result of all this.
Most of the time, you will get the following Error:
It is only looking for a gamma.cfg, but if you click
[OK], it will still proceed the export. Sometimes
it even creates a new gamma.cfg.
You could overcome this by changing the Source Directory,
which, I believe, needs to be adressed to the Resource Kit
folder that contains the gamma.cfg. I did it once,
very long time ago, but I'm probably too lazy to reset it each time
I've re-installed BK. The export does work without it, so I never
gave it further attention ever since.
Under File in the menu, you'll notice a few more
things. Like the Mod Settings. The MOD export
directory can be important to set. But admitted, I've hardly
used these settings, because when working with copies, these are already
set. I will explain in the next chapter.
Finally, there's still the Compress current MOD to PAK.
Well, as it says, one could export the whole thing to a .pak
file. Again, I've done it maybe once or twice, but because I'm used
to work with unpacked files, I personally haven't had a great need
for this function, but maybe you'll find it useful.
|Return to index
3. Creating a chapter from existing files
Knowing that one can also start from copied files, may make the previous
chapter on the ResEditor somewhat superfluous. However,
I wanted to give it my respect by explaining it. The ResEditor
is a great tool for a lot of things, but chapters can be build a lot
more easier when working from existing files. If I use the ResEditor,
it will be mostly because of the crosshair coordinates, which I will
then edit myself in the 1.xml (of the chapter).
So, copy a chapter folder from anywhere... you should have more or
less these files:
Some files are necessary, others are not. The two most important being
the 1.xml and script.lua.
Let's go through the 1.xml first.
Use an editor to get decent view of the file!
What I call the first part, is the History
section. This part is in fact not required. Deleting the whole part,
including the tags <History></History>
would not do any harm. During export within the ResEditor,
this part was created and holds a sort of informational 'timestamp'.
The second part, everthing between <RPG></RPG>
is mostly required. It's basically the same Properties
and Values pane as in the ResEditor.
I can't say a lot about the Season, exept that you
set it to one of the four, obviously, ranging from 0 to 3 (0=summer,
1=winter, 2=africa, 3=spring/autumn). However, since the chapter can
consist out of a mixture of all seasons, I don't see a reason to have
this option here. When a mission loads and opens within the game,
it will, thankfully, open the season of the mission! Therefore, someone
else would have to explain to me the logic of this setting.
A KeyName isn't needed, although you need to keep
the tag in the xml. Just leave it like <KeyName/>
or <KeyName></KeyName>. Again, I'm unsure
what it is used for and so far I haven't found a chapter yet that
has set a KeyName.
case of a chapter, the StatsType should, of course,
always be set to Chapter.
The following four tags, HeaderText, SubheaderText, DescriptionText
and MapImage need to refer to your chapter text and
image files that are in your chapter folder. Therefore, their path
should always be: scenarios\custom\chapters\mychapter\header.
This is of course, in the case of a custom chapter. Notice that the
file extensions .txt and .dds are
not included in the paths! Also notice that the MapImage
always has to refer to map. It is possible to rename the title of
the files (exept the map image), but then you also need to rename
it in the path, leaving the tags untouched of course. However, this
is not recommended, simply to not make it unnecessarely more confusing.
And whenever you can't seem to find your (custom) chapter listed within
the game, these reference paths should the first thing to be
The MapImageRect holds the coordinates where the
game will place the chapter map image (when the chapter has been selected
and the chapter information is being shown). You can probably move
it horizontal and/or vertical. Again, I can't say much about these
parameters, because I've always kept these standard, as I've never
felt the need to change these. I might give it a closer look and play
with it to see what it actually does... some day maybe.
Do I need to explain the InterfaceMusic tag? I guess
not, but know that it is only being played in the game's chapter information
screen (that opens when the chapter is loaded). It can point to any
sound file you have in the music folder or even another folder as
long as you keep the reference path correct. In case you don't want
any background music there, keep the tag empty <InterfaceMusic></InterfaceMusic>.
Next, in between the Missions tags, are set the reference
paths to each single mission that is a part of the chapter. Each part
is categorized as an item. In case you wan more or
less missions, simply copy/paste or delete (an) item(s).
Concerning the Difficulty, again I must remain vague,
simply because I haven't changed it so far. It might be the standard
0=easy, 1=medium and 2=hard. There were times that I have written
the difficulty (according to that standard parameters) in the lua
script of the mission, not the chapter. Maybe someone else can tell...
The Mission tag needs to refer to the 1.xml
of the mission. Notice that the path(s) here are being changed to
I have told in the beginning of this tutorial, at this point you need
to have moved your mission folders from \Run\Data\Scenarios\custom\missions
to \Run\Data\Scenarios\scenariomissions\allies (or
case of a mod). Use copy/paste to change all reference paths, if they
still refer to the custom missions folder (or you can start off with
a 1.xml that already has the correct paths). Whenever
one of these paths contain typos and/or can't find the 1.xml,
the chapter will undoubtedly crash the game. Always double-check these
paths, especially in the situation when you are able to load a chapter,
but starting a specific mission makes the game crash.
The PosOnMap holds the x and y coordinates
to which the crosshair for each mission will be set on the chapter
map image. This will be shown in the chapter information screen, at
the start of each single mission. To get these coordinates, you can
load your chapter map image into Photoshop/Gimp or get them from the
ResEditor. In case you don't want a crosshair, try
setting 0 as values or something passed the possible range...
Concerning the MissionBonus and AllBonusses
tags, again, I haven't used these so far. It is possible to award
medals through the chapter lua script, but I'm not sure whether it
concerns the same 'bonus' here. Anyway, keep the empty tags within
Next, there's the PlaceHolders section.
As I said before, I've never worked with random missions and so it
remains a mistery to me as well. I have no clue what the Position
coordinates actually point to.
The Script tag, obviously, needs to refer to the
location of the chapter script.lua file, which is
best to be the custom chapter folder.
Next, we have SettingName and ContextName.
From the screenshot, you can see that they have been turned off here.
A Setting contains a specific FieldSet,
which will be used to create the random maps (I suppose, I haven't
seen it affecting the custom missions so far). You can choose from
a list of standard settings, through the ResEditor
or copy one reference path into the 1.xml.
You should be able to create your own FieldSet through
the Field Composer in the MapEditor.
I have done so to use it for my single maps, but so far, I have never
attached one to a chapter. I guess the random maps can only have one
setting, but i'm unsure about this. From the scenarios\settings
folder, you could, of course, copy a file, rename it, edit it to your
desire and attach it.
The Context should be seen more as period of WWII
(like Typhoon, Market Garden or Bagration) and it allows you to more
or less set the preferred type of units for that period/battle. The
context.xml contains a ChapterUnitsTable
that lists UnitCreation, PlaceHolders, RandomMissionBonus
and such... Again, I've never went so deep in this and so I lack the
experience, but if you like, you can start form a BK original out
of the data.pak (\Run\data\data.pak\Scenarios\Chapters\Allies),
copy that and change it to your wish.
The PlayerSide tag should speak for itself. You have
three options: allies, german or ussr. There might be only one way
to change this: find the original standard text files from the data.pak,
copy them and edit their content, not the name of the file of course,
because I guess that's what the BK engine will be looking for, but
that's an assumption.
The MODName and MODVersion tags
are only used in case the chapter uses a mod. If so, it needs to contain
the exact same information as in the mod.xml
file that you have in your mod's data folder (just above the modobjects.xml).
If no mod needed, leave the tags empty.
Okay, this is it concerning the 1.xml.
Let's have a look at the chapter's script.lua.
It looks a bit like the Mission section in the 1.xml,
having the same reference paths. The difference being that the 1.xml
is used when the chapter loads, where the script.lua
is used to actually run it thoughout the whole chapter game.
The following picture shows a simple example of a chapter that contains
8 missions (iu_91 > iu_98):
||As you can see, the EnterChapter
function enables the first mission. Carefully mind the double
backslashes! The EnableMission reference paths
need to refer to the 1.xml of each mission folder.
If needed, simply copy/paste the folder names in between the
backslashes, to avoid typos in the code.
The MissionFinished function contains 8 conditions
(if > then). After each mission has been finished, it will
enable the next. Notice here that the strMissionName
reference paths have single backslashes and bear in mind the
logic of one mission ending, the next enabling in each condition,
just until the FinishCampaign() (and why not
call it FinishChapter?).
Also notice when mission iu_97 becomes enabled, a condition
GetStatisticsValue becomes launched. In this
case, it will check the number of casualties (3) for player
0. So when the player made less or equel than 555, then he will
be rewarded the medal (AddMedal) 'gcross' and
will put in the first (0) medal container. The medal screen
shows 6 containers, which can each contain a medal obviously,
that are numbered 0, 1, 2, 3, 4 and 5.
There are more GetStatisticsValue's:
GetStatisticsValue(1, 0) = number of kills (1), party (0)
GetStatisticsValue(3, 0) = number of unit loss (3), party (0)
GetStatisticsValue(2, 2) = AIprice ??? war booty???
GetStatisticsValue(4, 2) = AIprice ???
GetStatisticsValue(17, 2) = time elapsed
GetStatisticsValue(19, 0) = ???
Unfortunately, I have only managed to get the first (#kills) and the
second (#unit loss) working so far. I have found these in the original/standard
BK chapter folders, but I have no idea what they do exactly.
||In case you are using core units, the script
allows you to upgrade them inbetween missions. Use AddNewSlot
to create a 'slot' and set a type for each unit. In this example,
it is set in the EnterChapter function, but
it can be put elsewhere in the script also.
||In addition, after any specific mission(s),
you can use AddBaseUpgrade to give the player
the option to upgrade to one of these types.
And there's still more that can be done. Check out the original/standard
BK chapters. Those look very nifty, but way beyond my poor understanding.
But that is basically it for the script.lua.
The remainder of the files in the chapter folder
can be dealt with pretty quick, I think:
||1.xml = explained
context.xml: if you want a specific period context, find a standard,
edit it and refer to it
description.txt: as said, only useful when part of a campaign
header.txt = what appears as title in the in-game custom chapter
list - ensure txt are saved in unicode
script.lua = explained
map_h.dds: find a standard and edit it - save in ARGB8888 format
Okay, that's all. Godspeed!
|Return to index