This tutorial is aimed at advanced modders who already have some experience with using the Widgetizer. The latest version of the tool is available at http://www.wc3campaigns.net/tools/weu/Widgetizer.rar
. You will get to know and probably love some of the tool's features hidden in the ini file of the tool. This file can simply be opened and edited with a text editor like Notepad. Once you opened the file you will find many key value pairs in it, many that shouldn't be changed by the users and some that may be changed to fit your needs. Here's how the default ini file will probably look for you:
I will now explain the most interesting entries in detail and their effect on the conversion.
- Gameplay Constants and Game Interface: Setting the Constants key to 1 will cause the tool to convert the gameplay constants and game interface changes too. That means changes defined in the map's war3mapMisc.txt and war3mapSkin.txt files will be compiled into the files like GlobalStrings.fdf, CommandStrings.txt, CommandFunc.txt, Misc.txt and some others. Unfortunately these files don't get loaded from maps so the only way to make use of this option is a custom loader like the exe generated by the Widgetizer. There are also a few constants like food capacity and upkeep ranges that can't be compiled into any file and therefore are written into a new war3mapMisc.txt file that would have to be imported into every map that should use the dataset.
- File Comments: If you set the CheckCleanSLK key to 0 all output slk and txt files will keep all useless lines like comments. Additionally in each slk file the comments column will be filled with the name of the object it belongs to. Accordingly a comment with the name of the object will be written above each section in the txt files. Additionally you can put a special type of global comment in input txt files that will always show up at the bottom of the respective output file. Such comments start with the //:: symbols. This could be used to add a TODO list to each txt file for incremental development of a mod. The symbol :: is specified by the CommentIndicator key and may be customized.
- Customizable Object Ids: New objects always get an id generated by the editor that looks something like A000. Especially when developing mods you don't want to have such ids in the slk and txt files because the editor might generate the same id again in a different map and screw up your objects. That's why Widgetizer allows renaming objects by using a certain format for the object name. Simply change the name of the object in the editor to Name::newid and the original object id will be replaced by newid in the output file. Of course newid must be exactly 4 letters wide. Attention, references to renamed objects won't be updated automatically which means you have to either update them manually or use newid in the first place. I prefer the latter as it won't screw up the algorithm that resolves references if unused objects should be removed. The symbol :: is specified by the NameSeperator key and may be customized. If you put REMOVE instead of newid the object will be completely removed from all output files. That's how you can get rid of standard blizzard objects. The string REMOVE is defined in the RemoveIndicator key and is also customizable.
- Exception Lists: The Widgetizer has 3 different types of exception lists. The first one lets you specify certain objects that should never be cleaned from the output files. Therefore you will just have to add the object id that should be kept to one of the keys from Except0 to Except6. The number at the end of the key name points to the object type. The order is units, items, destructables, doodads, abilities, buffs, upgrades just like the order in the object editor. Object ids are separated by commas. For example the game crashes if the unit files don't contain the peasant unit that's why for Except0 hpea is listed. The second type lets you exclude object ids from the conversion. All changes for the specified objects simply won't be copied to the output files. To achieve this simply add the id of the object to the appropriate key. The keys range from SkipObjects0 to SkipObjects6. With the third type is similar to the second one and lets you exclude certain types of changes from the conversion. For example I often change the unit speed value of a unit to a higher value for testing purpose only. Now I don't want any changes regarding the move speed in my output files. So I simply look the change id for move speed up in the appropriate meta data file and add it to the appropriate ini key. In this case I looked umvs up in UnitMetaData.slk and added it to SkipChanges0. Each object type has its own meta data file except for items, those can be found in UnitMataData.slk too. The keys range from SkipChanges0 to SkipChanges6.
- Input and Output: To get better control over input and output files you can set the Advanced key to 1. Now you can select more than one source file and you're not limited to map files. You could also simply select a single w3o file or you could select a map and an additional w3a file. The Widgetizer would then try to merge the content of all input files into a single output dataset. Be aware that certain file combinations that don't make sense may and will cause problems, don't blame the tool for that. Another benefit of this option is that none of the output files will be removed from the output folder when the compilation is finished. That way you don't have to extract them from the output map if you need them in a folder. Another pretty cool feature of the Widgetizer is round trip compilation. That means after widgetizing a map you can open it in the editor again using the compiled editor patch. Now the map can be freely edited and if you made any additional changes in the object editor simply widgetize it again. This works because the txt and slk files that are present in the map will automatically be used as the base files instead of the files in the input folder. Talking about the compiled patches you can also specify which files will be imported into the 4 resulting archives, namely the map, the ROC patch, the TFT patch, and the editor patch. This is handled by the 4 values assigned to keys like ImportNormal0, ImportCustomROC0, ImportCustomTFT0. The index at the end of the key name points to the object type, in this case we specify how unit files are handled. If ImportNormal0 is1 it tells the tool to import those files with the standard path like Units\, ImportCustomROC0 tells it also import them to Custom_V0\Units\ and ImportCustomTFT0 tells it to also import them to Custom_V1\Units\. As you can see all files are only imported with the standard paths into maps because we need to save space there. The editor patch on the other hand imports the output files to the standard path, Custom_V0 and Custom_V1 because we know that the editor may use all of them as data source depending on the type flag of the loaded map and size doesn't really matter here. The keys MiscImportNormal0, MiscImportROC0, MiscImportTFT0 work the same way, only for gameplay constants and game interface values. Index 0 relates to gameplay constants, index 1 to the game interface. Last but not least the ImportResources key specifies if other totally unrelated files that might be found in the input map should be copied into the output archives.
- Hashtable Sizes: If your project has really large numbers of objects and you start getting strange errors like objects or changes that are missing or wrong field values in the output files you should try increasing the hashtable size for the object type that bugs. Therefore simply change the appropriate value of the HashtableSizeskey. Again the order of values here is the same as the order of the tabs in the object editor.
Well, I hope this tutorial got you some insight into the inner workings of the Widgetizer. Again, I don't want new users to make use of them and then complain about results they didn't expect, that's why the options are hidden in the ini file.