 |
Blitzkrieg®
Creating a custom chapter
by kaoz | MMXVIII
| Index | ||||||||||
| 1. Folder structure | ||||||||||
| 2. Creating a chapter with the ResEditor | ||||||||||
| 3. Creating a chapter from existing files | ||||||||||
| 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 folder. 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 picture:  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:
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 file. 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. In the 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 double-checked. 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 scenarios\scenariomissions\german\mymission\1. As 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 \Run\mods\mymod\data\scenarios\scenariomissions in 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 the code. 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):
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.
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:
Okay, that's all. Godspeed! |
||||||||||
| Return to index | ||||||||||
