DGen debugging

[vtrelut]

VTrelut’s DGen TROUBLESHOOTING GUIDE for IL-2 Sturmovik 1946 and earlier versions’ users

Version 1.0 - February 25th, 2007

For players of dynamic campaigns add-ons properly installed and with their latest updates. Third party add-ons are very nice to enhance IL-2’s dynamic campaigns, however they can bring their – minor – share of bugs, and sometimes conflict with each other; so even the user who installed correctly all third party DGen add-ons with all the necessary files in the right folders may face some trouble: this guide is for them!


Foreword


Following the publication by EnjoyR of his patches A & B, now all users of IL-2 1946 and earlier versions have the possibility to greatly enhance their experience with dynamic campaigns. To date, it is the most comprehensive and successful attempt to make all dynamic campaigns available from free add-ons or paid add-ons compatible together: more than 170 dynamic campaigns playable without conflicts, in case you have all 3 paid add-ons installed. Even if you have no paid add-ons, the “EnjoyrPatch for no add-ons” installs automatically a large number of free dynamic campaigns which enhance greatly the offline player’s experience: a MUST! Download the patches which fit your requirements from the dedicated page at Mission4Today:

http://mission4today.com/index.php?name=Downloads&c=566

After installing the first version, I faced a couple of - inevitable - bugs and decided to dig into DGen myself, with the aim to solve the problems I noted through careful attention and logic. In fact I love playing Pacific campaigns and would not like to have them bugged, since there are only a few of them anyway, so I wanted to sort out the problems so that my choice of available dynamic campaigns in the Pacific Theatre of Operations be the widest possible. Of course it became also natural to check European campaigns as well.

I must say that I am not a DGen specialist, I never designed any campaign, and I am just a user/player offline. I found no real explanation or documentation about DGen, except in the DGen guide by Amagi. Please download this guide from Airwarfare.com, it is a fantastic mine of information and advice in case you want to enhance your experience with dynamic campaigns:

http://airwarfare.com/guides.htm

Thank you so much Amagi!

I spent countless hours on DGen debugging, and now want to share with other players some of my practice and fixes. Of course I am still learning, so I hope to improve this guide regularly.

General advice


First of all, here are a few pieces of general advice:

• The basic tool for any DGen debugger or modder is built-in Windows: Note Pad. Except the pilots’ portraits, you can open and edit manually with Note Pad all of the files contained in the DGen folder: these are files with extensions .dat, .mis, .DB, .txt. In order to open them and see their contents or edit them, right click on the file you want, then left click “open with”, and select the programme Note Pad. You can then see and change basically the contents of all DGen files with this simple tool! Very simple and handy indeed.

• Then there are - at least - 3 golden rules to follow for the DGen debugger or modder:

1) Always INSTALL SEPARATELY dynamic campaigns DGen add-ons or DGen patches first on a different folder on your hard drive, with all their specific updates, then inspect the contents of the DGen folder created by the add-on or patch, and be careful about overwriting existing files in your main game’s DGen folder, when you copy the add-on’s DGen folder into your main game folder, in order to add the new campaigns.
2) Always BACK UP your original DGen folder immediately after you install your main game, and keep a copy of it in a safe place, such as an IL-2 backups folder in a separate hard drive, or a CD. Never add anything to the game’s DGen folder without making a prior back-up. Also when you install add-ons in a separate folder as advised above, always keep a copy of such add-on’s DGen folder in a separate and safe place. Finally back up at least once a month your Users’ folder.
3) Always TEST your debugged/modded campaigns! When you overwrite or change a certain file in the DGen folder for debugging for instance, make sure you did the right thing by testing the result on the related career/campaign. In order to test, the best way is to disable the setting “no immediate success” within the difficulty options, before you start a career and attempt to generate a campaign. By doing so, you can quickly exit any mission and attempt to generate a new one within the same campaign, by clicking “apply”, without having to wait for completing successfully every mission. By exiting several times every mission even before take-off, and then clicking “apply”, you can quickly check whether the campaign works or not. Of course the only way to evaluate the quality, playability and game play of the campaign is to complete all the missions, but before that stage one must ensure that at least the campaign structure is working properly, without DGen errors, crashes, or other trouble.



DGen basics


My understanding is as follows:

DGen offline dynamic campaigns work based on the dynamic campaign generator programme DGen.exe.

Currently all my work and tests have been made using DGen.exe version 4.0.6.12. If you apply my advice with other versions, do so with your own judgment, I have not tested with other versions.

The DGen.exe campaign generator generates new missions based on a set of data and mission template files, as well as briefing files. These files are all contained in the DGen folder within the game’s main folder.

For it to work, it needs the following combination of files to be available and working in harmony together.
• Briefing files for campaigns and missions: these are “message” .dat files. There are notably pf_messageNA.dat files for Pacific Fighters, messageNA.dat files for Eastern Front IL-2 campaigns, NN_messageNA.dat files for French campaigns, GB_messageNA.dat files for British Western Front campaigns, US_messageNA.dat files for US Western Front campaigns (NA = nationality reference in 2 letters, e.g. “fr” for France). In your DGen folder, you may find more of these files for other nationalities (e.g. Italy, Hungary) or particular careers (e.g. British Hurricanes in Murmansk).
• Career configuration files: these are campaignsXXY_NA.dat files, where XX is the reference to a specific army (e.g. IN for Japanese imperial navy), Y is a specific character for a given career (e.g. A, B, 1, 2, !, $, etc), and NA is the nationality code. The default language being English, the English versions of these files are simply campaignsXXY.dat files. Never delete any campaignsXXY.dat English versions files! If you do so then the related career/campaigns may no longer be available, even if all other necessary files are properly installed. You may nevertheless delete the other specific language versions. In case your language version is not available, the game will use the default version, and display the career’s description and campaigns’ brief descriptions in English. These career configuration files allow the user to select which campaigns he wants to play within a career, which squadron he wants to fly for, and which planes he wants to fly:
• To choose which squadron you will fly for, the available squadrons data are located in a file squadronsXXY.dat for each career.
• The campaignsXXY_NA.dat files are also used in conjunction with planes data files, in the form planesXXY.dat files, which refer to each campaign within the career XXY, and contain names of available aircraft. Within the career menu, click “start” to see the options of available campaigns, and then click the box of the aircraft type to scroll through all options of available flyable aircraft for each campaign.
• When the user configures a given career and chooses which campaign, which squadron and which plane he wants to fly (click “generate”), the DGen.exe works and generates a first mission, based on available operations outlined in an operations data file, opsNAMEOFCAMPAIGN.dat file (e.g. opsSantaCruz.dat), loading a map from a mission template file (.mis file), and a briefing from the message data file relevant to the career chosen. Dgen.exe also uses a data base file specific to each campaign, which contains information about the location/map, type of aircraft used, relative weight/number of each type of aircraft, squadrons, skins, etc. These are NAMEOFCAMPAIGN.DB files (e.g. Bagration.DB). It also needs some information on flying parameters (cruising speed & altitude, loadout, etc) of available flyable aircraft listed in the files planes.dat. There are at least two of these: EuroPlanes.dat for European fronts, and PacificPlanes.dat for Pacific campaigns. There are also specific planes.dat files for specific campaigns (e.g. BurmaD3Planes.dat).
• The file structure above is absolutely critical and if a slight inconsistency or mistake is present in one file vs. others, then the related campaigns may not work!
• DGen also uses ClassesXXY.dat files to specify which planes are able/supposed to do what (e.g. FIGHTER, Jabo, etc), but the use of these files is not systematic for all careers.



Which trouble may you face, and what are the possible fixes?


All of these happened to me recently - do not laugh too loud please -, and I fixed them as per the below. Several of the problems are due to bugs in original files from the add-ons, whether free or commercial ones, even in their latest versions, so in the world of DGen be careful: the latest versions of dynamic campaigns bring in their small choice of bugs, and trouble for all of us, in addition to their expected fun. There is no taboo here, and sometimes one has to modify the files contained in the DGen folder, since even a proper install cannot guarantee bug-free operations. I did my best to provide EnjoyR with fixed/modified files when I could, so his patches are the best bets as far as I am concerned, even if you have perfectly installed and updated paid add-ons and/or free add-ons. EnjoyR has been kind enough to include all my proposed debugged files in his patches, so there is a chance that you may not even worry about the troubles I faced, at least you may experience the trouble on different campaigns or careers.



1st type of problem: nothing happens!


• Description: you go into the pilot’s career menu, choose a career, for example German Fighter South sector, click “start”, and then you go back to the game’s main menu, and that is all, good bye! Career listed but not working…

• FIX: this problem is probably due to conflicts between the various versions of career configuration campaignsXXY.dat & campaignsXXY_NA.dat files and/or the related planesXXY.dat file. You must ensure that each language version of the campaignsXXY.dat files for a given career XXY contain the same campaigns (e.g. [Marianas1]), and that the file planesXXY.dat file contains entries for each campaign listed in the related campaignsXXY.dat files. Of course I assume that you have all the other files related to this career properly installed…

At this stage it is important to mention about which language you use when playing IL-2. EnjoyR’s patches A & B are designed to work with the English version. However you can play using another language: you MUST check ALL your campaignsXXY_NA.dat files in your DGen folder to ensure that they contain the same lists of campaigns as the default/English versions. If only the English version is present in DGen, you will configure your career, i.e. choose your campaigns, squadron and planes, with brief descriptions in English. English versions alone are working, whatever language you set in IL-2 (language is set in conf.ini file, under [rts], locale= NA). So if only the default campaignsXXY.dat file is present for a given career, no problem. But if you see another version for your language, for instance a campaignsXXY_fr.dat file while you play IL-2 in French, then you must make sure that this specific language’s career configuration file contains the same list of campaigns! If you take the time to do that, you can keep using your language and EnjoyR’s patches will work, no problem, and there is no need to switch to English! If your language version of campaignsXXY_NA.dat file contains a different list of campaigns, you have the choice to: either delete that file (only the English/default one is necessary), or manually edit it with Note Pad to include the same list, with descriptions in the language you normally use.



2nd type of problem: campaign cannot start because no mission is generated!


• Description: you reach the career configuration screen, choose your campaigns, squadron and planes, click “generate”, and nothing happens! You do not go back to the main game’s menu though, you are just stuck at the career configuration screen…

• FIX: open your main game’s folder and look for a file named DGenerror.log. Open it: it should contain information about what went wrong, such as ZZZ plane not available. In that case you must manually edit your file Europlanes.dat or PacificPlanes.dat to add information about the missing plane, or remove such a missing plane from the NAMEOFCAMPAIGN.DB file. The NAMEOFCAMPAIGN.DB file lists several types of aircraft. If these are not flyable or not properly documented in Europlanes.dat or PacificPlanes.dat, the campaign will not work!



3rd type of problem: DGen crashes!


• Description: you click “generate”, or click “apply” after a mission, to go to the next one, and then the campaign crashes…And you also have a Windows pop up saying: “DGen.exe has a problem and must shut down, etc…”; you also get an IL-2 message saying something like: “mission not loaded, no map available”.

• FIX: that means that some of the data contained inNAMEOFCAMPAIGN.DB, opsNAMEOFCAMPAIGN.dat or related .mis files are incorrect, or conflicting each other or something else. I then advise you not to erase immediately the crashing campaign. Quit the game, open your crashed campaign folder in main game’s folder\Missions\campaigns\Army (e.g. US for USAAF), and look for the file logbook.dat. This file contains information about which type of mission was supposed to be generated. Other files can also let you know what went wrong. You may also have a look at DGenerror.log, if one has been generated. After that, you can use your energy to narrow down the problem, and manually edit the files NAMEOFCAMPAIGN.DB or opsNAMEOFCAMPAIGN.dat to correct them (back up first!); you may have a hint by comparing those files with other files related to different working campaigns within the same career, so that you can check what is specifically missing or wrong in those files. The files opsNAMEOFCAMPAIGN.dat look very obscure at first sight. In fact it is not so difficult to understand their contents: For each campaign, they specify which type of missions should be generated for each army (e.g. UsArmyIntercept), the period of the war during which these operations are supposed to take place, and the number and type of planes involved in each mission to be generated. I do not know a generic fix here, so this is debugging case by case!



4th type of problem: all active campaigns lost!


• Description: you have completed 50 missions (for instance) in a given career, you open your game with a view to finish the last campaign of this career, and win the war, you click “pilot’s career”… and none of the active campaigns you have started appears! All of them are gone, vanished into ashes, even the static ones! You should start all over again? Don’t laugh, it can happen to anyone; it happened to me a couple of times after I changed my game’s language in conf.ini…

• FIX: restore your Users’ folder by copying your backup and replacing the game’s Users folder - of course you backed up your Users’ folder didn’t you -? Inside this Users’ folder, you can see your pilots’ folders, and in each one of them the campaigns.ini file. That is the particular file that needs to be restored. Please note that this one cannot be manually edited or modified with Note Pad.
Another FIX is to use the system restore function of Windows XP, which could work if you have a recent Windows XP restore point. In my case both fixes worked.
In any case you will lose the progress you made in your active campaigns since the last back-up or the last restore point!



OTHER DGen PROBLEMS? I don’t know! I experienced only those listed above. DGen is rather complex, but also quite logical. So I suppose that logic and attention to detail are key ingredients to solve the problems. Good luck…



OTHER FIXES: there are certainly other solutions to problems described above.


There is one trick, which has been reportedly working for others: if your campaign crashes, simply edit the campaign.ini file in the crashed campaign folder within the Missions/campaign/NA concerned folder, and copy the last mission’s reference under the crashed one, like this:

[Main]
ExecGenerator DGen.exe
Class il2.game.campaign.CampaignBlue
awardsClass il2.game.campaign.AwardsDEfighter
[list]
10622.mis
10706.mis
10706.mis
end.mis

In that case there was a mission generated on July 6th, 1941, which crashed, and by copying it again as shown in red above, one may restart flying the campaign.
This last trick may work if your campaign data files are not bugged, but you had a crash due to a hardware failure for instance.


In case of trouble, the best way is to head for forums at IL-2 fan sites, look for threads related for your problem, and if necessary post yourself or create a new thread. I found that the below forums are the best to get help and knowledge about your IL-2 game:

SimHQ: http://www.simhq.com/forum/ubbthreads.p ... t&Board=86

UbiSoft: http://forums.ubi.com/eve/ubb.x?a=frm&s ... f=49310655

CheckSix: http://www.checksix-forums.com/forumdisplay.php?f=307

I also recommend the Mission4Today forum, the CombatAce forum for IL-2, and others, but I found the above 3 ones very active and packed with knowledge and experience about DGen, especially the SimHQ one.

Please try to distinguish between real DGen problems, and other issues, such as hardware problems, internet connection problems, etc. There are various ways for your favourite WWII flight Sim to crash, and DGen trouble is only one of them. In particular beware of your hardware: IL-2 is very demanding on all your hardware at the same time (CPU, chipset, RAM, sound card, GPU, video RAM), and based on my – limited – experience so far, no generic benchmark can really stress your PC as much as IL-2 does. In other words, do not be surprised if your system passes many hardware stability tests successfully, but does crash when playing IL-2…On the other hand, perfect stability with IL-2 is really a good test for your PC; IL-2 stresses your PC components to their limits, and it is good to know that your PC was able to go through hours of IL-2 playing: it means it can sustain almost anything else.


Finally, once you get used to DGen troubleshooting, the next step would be to become a DGen modder, and why not even a DGen creator?


For the last step, please read Amagi’s DGen guide referred to above.


For DGen modding, I suppose that there are easy mods, such as adding or modifying campaign descriptions, briefings and other messages, or adding specific skins in the NAMEOFCAMPAIGN.DB files. More advanced mods would include upgrading the campaigns mission files, including changing the map (for instance it is tempting to do so for the Italian campaigns now that the Italian map is available), or adding flyable planes. To add flyable planes to the career configuration options, I suppose that, assuming the DGen.exe version you use supports the planes you want to add, you should edit and modify or at least check three files for a given career and campaign: the files planesXXY.dat, NAMEOFCAMPAIGN.dat, and EuroPlanes.dat or PacificPlanes.dat. I have not yet attempted to upgrade a campaign, so I do not know at this moment. Please let the community and its members know about your experience and successes in this respect! I will try to add the Shiden Kai and the J2M5 to the Japanese Navy campaigns and let you know if I am successful.


Any comments/questions/suggestions/corrections/additions are welcome by e-mail at vtrelut@yahoo.fr