Grimex Documentation

# Grim Extension Pack 1.0b

The Grimoire Extension Pack, or short Grimex, is a set of tools that integrates nicely into Grimoire/Jass NewGen. These tools can also be used standalone by calling them from the command line, batch scripts or custom programs. Included in this documentation are also a bunch of core Grimoire hacks, that many people might not know about.

## Table of content

- Quickstart
- File Importer
- Path Mapper
- Tile Setter
- File Exporter
- Object Merger
- Constant Merger
- Trigger Merger
- Patch Generator
- Grimoire Addons
- Appendix
- Credits

## Quickstart

This section contains a list of expected parameters for each tool that is part of the Grim Extension pack. People who are using the tools from command line will need these parameters. Also the arguments for a vJASS external call can be derived from these usage instructions. So whoever is familiar with command line will probably find this section enough to get started.

File Importer:

    map.w3x lookuppaths ( directory | { diskfilepath archivefilename } )

Path Mapper:

    map.w3x lookuppaths (checkflags | checktiles) applyflags [checkmode] [applymode]

Tile Setter:

    map.w3x lookuppaths tileset tilelist

File Exporter:

    map.w3x lookuppaths [targetdir]

Object Merger:

    map.w3x lookuppaths [ m | r | i ] mergefile { moremergefiles }
    map.w3x lookuppaths ( w3u | w3t | w3b | w3d | w3a | w3h | w3q ) originalid newid { changeid [ level | variation ] value }

Constant Merger:

    map.w3x lookuppaths mergefile { moremergefiles }

Trigger Merger:

    map.w3x lookuppaths { war3map.wtg | war3map.wct }

Patch Generator:

    script.lua lookuppaths patchname { flags }

For all tools the first argument is the path of the map being modified and the second parameter is a list of lookup directories that is used to resolve relative paths of other files passed in. You can pass "" if you're not using relative paths. Otherwise this is a string of all the paths separated by a ; and with \ replaced by /. If any of the paths contains a space then simply put the whole list in brackets. For example the lookup paths could be "C:/MyMap/;./jass/".

Remember that all this is beta software, there may still be bugs. In case something goes wrong, simply make use of JassHelper's backups and report bugs at the forums at www.wc3campaigns.net!

Since the version 1.0 of Grim Extensions all included tools can now be controlled with lua-scripts as well. This makes them even more powerful, flexible and usually a lot faster. To make use of this feature, instead of the usual parameters you have to pass one or more lua files (with the extension .lua) to the tool:

All Tools:

    map.w3x lookuppaths script.lua { more.lua }

Check out the LUA scripts in the grimext/samples/ folder to find out how the scripting language works and which functions are available.

## File Importer

The File Importer plugin enables you to import a list of files or simply a folder including all subdirectories into your map. It can also auto-convert images to BLP format and MDL files to MDX due to its integration of BLPaletter and MDLXConverter. Additionally it will add appropriate icon borders and resize icons based on a naming convention.

When working on a map it is useful to keep all imports that are still being worked on in a folder that gets auto-imported by the File Importer tool as soon as the map is saved. That way the map always contains an up-to-date version of all your custom files. While working on a model or texture you can test your work ingame within seconds, without the hassle of having to convert and import the files manually. When distributing a system that requires imported files, an external call to the File Importer in the system's script will make sure that the required files are properly imported. An example would be the Dummy.mdx model from the caster system.

There are two ways to use the File Importer. From the menu you can click Extensions/Import Directory and select the directory that you want to import or you add a vJASS external call to your JASS script. The selected directory will then be imported into the map including the directory structure of all subdirectories. The imported files wil generally use the same path that they have inside the imported folder. The second option is using a vJASS external call, here's an example that will import the contents of C:\MyMap:

vJASS:

    //! external FileImporter C:\MyMap

These external calls are evaluated whenever the map is saved, so the up-to-date files from that directory will always replace older imported files in the map. Relative paths to the map's directory and the lookup paths defined under [lookupfolders] in mapcompiler.conf (the JassHelper configuration file) are automatically resolved:

vJASS:

    //! external FileImporter ..\MyMap

If you don't want to import a whole directory, but only a few files, then you can use Extensions\Import Files from the menu and select the files you want to import. When using an external call to import specific files you'll have to specify a list of pairs of source file and target file names. The target file name is the name that it should have inside the map:

vJASS:

    //! external FileImporter F:\Files\AbilityData.slk Units\AbilityData.slk

Note how you only need to change the file extension of the imported path to make use of the auto-convert function:

vJASS:

    //! external FileImporter ..\MyMap\DiscoStu.mdl Models\DiscoStu.mdx ..\MyMap\Textures\Stu.tga Textures\Stu.blp

When importing a whole directory, auto-convert will attempt to convert all files with a .jpg, .bmp, .tga or .mdl extension. If the conversion is successful the resulting file will be imported using the same path with only the extension changed to .blp or .mdx. Otherwise the original file is imported using its original path. You can explicitely overrule this attempt by keeping the same extension in the imported path, although it doesn't make much sense:

vJASS:

    //! external FileImporter ..\MyMap\DiscoStu.mdl Models\DiscoStu.mdl

Finally there's a naming convention that will add icon borders to images with a certain prefix in the filename.

- infocard- attack/armor type icons
- level-infocard- same but with levels (caster upgrade art)
- CMD normal icon
- PAS passive icon
- AUT autocast icon

The icons in the following example will get a normal/autocast/passive icon border:

vJASS:

    //! external FileImporter CMDBTNMyIcon.bmp MyIcon.blp AUTBTNOtherIcon.tga OtherIcon.blp PASBTNNewIcon.jpg NewIcon.blp

The imported path for icons doesn't matter, they will end up in ReplaceableTextures\CommandButtons\BTNMyIcon.blp, ReplaceableTextures\AutocastButtons\BTNOtherIcon.blp and ReplaceableTextures\PassiveButtons\BTNNewIcon.blp and a disabled version will automatically be put in ReplaceableTextures\CommandButtonsDisabled\DISIconName.blp. Now let's combine the prefixes to make use of a shared disabled icon:

vJASS:

    //! external FileImporter AUTPASCMDSharedIcon.tga SharedIcon.blp

This will create a normal, a passive and an autocast version of the same icon and put the shared disabled version in ReplaceableTextures\CommandButtonsDisabled\DISSharedIcon.blp. Finally we can put attack/armor type borders and caster upgrade borders around our icons:

vJASS:

    //! external FileImporter ..\MyMap\infocard-chaos-damage.tga InterfaceTextures\infocard-chaos-damage.blp ..\MyMap\level-infocard-undead-caster.tga InterfaceTextures\level-infocard-undead-caster.blp

As you can see, the infocard- and level-infocard- prefixes do the magic here. Since infocard icons do not have disabled versions, the imported path will not be changed in this case. If an icon doesn't have the appropriate size, it will be resized automatically by the tool. If you use a custom icon style in your map or mod, you can customize the borders and overlays used by the tool. You'll find them as TGA files inside the directory where the Extensions are installed to. Also remember that the tool will never try to modify BLP files, the auto-bordering and resizing is only applied to BMP, TGA and JPG images.

### Known Issues

If you want the imported files to show up in the import manager you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY.

### LUA Benefits

You can specify a callback function which provides the compression details for each auto-converted image. And of course you can speed up single file imports a lot, because this is now just one external call.

## Path Mapper

The Path Mapper plugin enables you to post-process the pathing map of your map after saving it. It's good for changing the walkability/flyability/buildability of specific tiles or of terrain cells that meet some other certain creteria. This allows for a number of tricks like making cliffs walkable or for example in Project Revolution we used it in combination with the 'Placement Prevented By' field to make refineries only buildable on geysirs.

The following example makes the map unwalkable where Lordaeron Summer Dirt, Lordaeron Summer Grass or Lordaeron Summer Dark Grass is:

vJASS:

    //! external PathMapper LdrtLgrsLgrd 2 |

Here is another example that sets the pathing to normal ground where tiles other than Lordaeron Summer Dirt are:

vJASS:

    //! external PathMapper Ldrt 40 !

To be able to use it you'll need a bit more information. First of all you'll need to know the tile ids, which you can obtain from TerrainArt\Terrain.slk or from this list. Then you'll need the pathability flag table to determine which values you want to apply to the pathing map.

- 01 0=unused
- 02 1=no walk 0=walk ok
- 04 1=no fly 0=fly ok
- 08 1=no build 0=build ok
- 10 0=unused
- 20 1=blight 0=normal
- 40 1=no water 0=water
- 80 1=unpathable 0=normal

The flag values here are hexadecimal and need to be added up to combine the flags, the mask argument for the tool also needs to be hexadecimal. Internally the pathing map is stored in a grid of 32x32 cells. That means that the smallest unit in the editor, a 128x128 cell is split up into 16 pathing cells, each of which is assigned a value from the above flag table. With this tool you're able to change this value for each of the cells. Here are some examples that you will typically find in a pathing map.

- 00 bridge doodad
- 08 shallow water
- 0A deep water
- 40 normal ground
- 48 water ramp, unbuildable grounds, unbuildable parts of doodads
- CA cliff edges, solid parts of doodads
- CE map boundaries

Now to modify the pathing map, you'll need a way to specify which cells will be changed and a way to apply flag values to the existing value of each cell. For the latter there are four different apply modes that you can use.

- | binary or -> flag is added
- & binary and -> common flags remain
- ^ binary xor -> common flags are removed
- default set -> value is overwritten

So in the first example only the no-walk-bit is set with a binary or and nothing else is changed. If you don't specify an apply mode, the old values are completely replaced by the value you specify. Like in the second example where it's set to normal ground. Check modes here can be either match or mismatch.

- ! mismatch -> apply if tile is not listed
- default match -> apply if tile is listed

In the first example ! is used to change the pathing for all tiles that are not Lordaeron Summer Dirt. If you don't set this parameter the normal mode will apply the change for all specified tiles.

Instead of the tile of each cell you can also compare the current pathability value to decide which cell needs to be updated. When comparing to a pathability mask, the following compare modes can be specified.

- 1 all bits that are set in the mask must be set for a cell to be updated, other flags may be set too
- 0 all bits that are set in the mask can be set, but don't have to, other flags must not be set for a cell to be updated
- default the value of a point must be equal to the mask to be updated

Apply modes in this case are again |, &, and ^. In the next example map boundaries are made walkable by removing the no-walk-bit with a binary and:

vJASS:

    //! external PathMapper CE FD 1 &

In this next example areas that have either the no-walk or the no-fly bit set, are made walkable and flyable:

vJASS:

    //! external PathMapper A F5 0 &

### Known Issues

If you ever decide to add walkability to a tile that is normally unwalkable, please note that this will update ALL cells that have this tile. That means that units will also be able to walk over cliffs, doodads and possibly water and the camera bounds when those are covered with the specified tile. In such cases can use the pathing configuration that is part of UMSWE instead of this tool.

### LUA Benefits

You can specify callback functions for the condition that a cell needs to meet to be updated and for the update action, making it a lot more flexible and faster. Also the tool becomes a lot more user friendly, because you can save yourself the hassle of bitwise flag operations.

## Tile Setter

The Tile Setter plugin allows you to edit the tileset of your maps similar to the already existing option in the world editor. The only major difference is that this tool extends the tile limit to 16. This will make the old tileset editor of WEU obsolete. You can also change the base tileset with this tool, in case you want to switch to a different water/cliff look.

Using it is quite simple, just click Extensions\Edit Tileset from the menu, then a graphical tile picker will pop up. At the bottom it shows the base tileset of your map and a list tiles currently present in your map like so:
By clicking on the tile icons you can add/remove it to/from your map. The max is 16 tiles for each map. When you're satisfied with your changes click the ok button to apply them, then close and reopen your map without resaving it, and your new tiles should show up in the terrain palette. The configuration dialog might spit out a warning if you removed or replaced cliff tiles with non-cliff tiles. This can only cause problems if the removed/replaced tile has actually been used for cliffs in your map, otherwise it's safe to ignore the warning.

You shouldn't ever need to use the Tile Setter from a vJASS external call, but in case you can think of any situation where this could be useful, here's an example that changes the terrain of your map into the Lordaeron Summer tileset. Use this tileset list and this this list of tiles as a reference for your calls:

vJASS:

    //! external TileSetter L LdrtLdroLdrgLrokLgrsLgrd

### Known Issues

Do NOT replace cliff tiles that are actually used as cliffs in your map. Please remove those cliffs from your terrain before exchanging the tile to prevent possible problems, unless you know what you're doing.

### LUA Benefits

You can edit your tile list programmatically and use several functions to query details about each tile.

## File Exporter

The File Exporter plugin simply exports all files inside a map to a specified folder. It will also rebuild the folder structure from inside the map in the specified target directory. That way the target directory can the again be used as the source directory for the File Importer plugin. This can be useful to copy the files from a system that is distributed through a demo map to your own map. For example one could export all contents of the Ultimate Terraining Map and import them all into a custom map using the File Importer and Object Merger plugins with just a few clicks. Or it can be used to copy the terrain, units, doodads, sounds, regions, or cameras from one map to another map.

To get all files extracted simply click Extensions\Export Files in the menu and select the target directory. This will essentially extract all files listed in the import manager, but also some internal files that contain special data. For each category of files the tool creates a separate subdirectory in the target directory, here's the list:

- Imports\ All imports from the import manager go here. The folder structure of those imported files is recreated within this directory and it can then be used as the input directory for the File Importer plugin to get the files into some other map.
- Constants\ If you have customized the gameplay constants, the game interface or the test map settings, then the files that contain this information are put here. The directory can be used as the input folder for the Constant Merger plugin to get these changes into other maps. The list here explains what each file does.
- Objects\ If you have used the object editor to customize units, abilites, items, buffs, upgrades, doodads or destructables, all these changes will be put into this directory. The directory can then be used as the input folder for the Object Merger plugin to get the changes into other maps. The list here explains more about the file extensions and their meaning.
- Triggers\ Trigger data, variables and custom text content from your map goes here. Later this directory can be used as the input folder for the Trigger Merger plugin to import the trigger data into other maps.
- Environment\ Other internal content from your map like the terrain, placed units and doodads, sound definitions from the sound editor, regions, cameras, the minimap and minimap preview will be put here. Each of them is put into a separate file and using the File Importer plugin, you can put them into other maps. The following list explains what each file contains.

- war3map.w3e terrain file
- war3map.shd shadows
- war3map.mmp icons for the minimap
- war3map.wpm pathing map
- war3map.doo placed doodads
- war3mapUnits.doo placed units and items
- war3mapMap.blp minimap image
- war3mapMap.tga alternate file name for the minimap image
- war3mapPreview.tga minimap preview image
- war3map.w3r region definitions
- war3map.w3c camera definitions
- war3map.w3s sound definitions

On a final note, all files that are used as input for the Object Merger, Trigger Merger or Constant Merger plugins should have been exported using this File Exporter plugin or by the export function of the WE before. That is because it takes care of inlinig TRIGSTR references when exporting the files, which prevents strings from getting lost when importing those files into other maps. If the files however had been exported using a normal MPQ viewer, the strings will not be inlined properly and may get lost. Also if you ever want to use the File Exporter in a vJASS external call, here's an example that exports all files to C:\MyMap:

vJASS:

    //! external FileExporter C:\MyMap

### Known Issues

None so far.

### LUA Benefits

You can also export single files to specific directories.

## Object Merger

There are two basic use cases for the Object Merger plugin. First of all it can import object editor data, but it won't replace the existing data, instead it will merge the existing and the imported data, there are different modes available that control how collisions of object ids are handled. This can be useful for distributing systems that require certain objects, like for example the caster unit from the caster system. A vJASS external call to this tool will make sure that the required unit exists in the map. Also in a team people can work separately on certain aspects of the map and later merge their work this way. The other use case is generating larger amounts of similar objects using vJASS external calls. Again this is useful to distribute systems that require object data. I'm thinking of systems like Bonus Mod which requires a number of bonus abilites. Finally it allows you to specify custom rawcodes for your objects, although this is conveniently possible with a Grimoire hack already.

When merging or generating object data, the first thing you'll have to know is what type of objects each file extension is associated with. Here's the list:

- w3u units
- w3t items
- w3b destructables
- w3d doodads
- w3a abilities
- w3h buffs
- w3q upgrades

To merge object data there are three different modes available how collisions can be handled. Each of them is available from the menu as well as from vJASS external calls.

- m merge changes for objects with the same rawcode, this is the default (Extensions\Merge Object Editor Data)
- r replace existing objects with the imported objects in case of equal rawcodes (Extensions\Replace Object Editor Data)
- i a clean import, that generates new ids for imported objects if their id is already used (Extensions\Import Object Editor Data)

When using one of the menu entries a popup wil ask you to select all input files that you want to add to the map. All the input files need to be of the sime type of course, you cannot mix unit and ability definitions for example. Our first example shows how to import custom unit data that was previously exported by the File Exporter plugin using a vJASS external call:

vJASS:

    //! external ObjectMerger Objects\war3map.w3u

The above is the same as the following call that explicitely defines how collisions should be handled, because m is the default mode:

vJASS:

    //! external ObjectMerger m Objects\war3map.w3u

It's important that the merged files have been exported with the WE's export function or the File Exporter tool and not using an MPQ viewer, because otherwise string references may get lost. The second example shows how to import several files of the same type (extension) with one call. In case of collisions the existing object will be completely replaced (r parameter):

vJASS:

    //! external ObjectMerger r myabilities.w3a D:\war3\moreabilities.w3a evenmoreabilities.w3a

Ok, with this tool you can also create new objects using a vJASS external call instead of the object editor. I'll start with a few examples and then explain the parameters. This one creates a copy of the glaive upgrade with 2 levels and a different icon on the second level:

vJASS:

    //! external ObjectMerger w3q Remg Rgl2 glvl 2 gar1 2 "ReplaceableTextures\CommandButtons\BTNImpale.blp"

Here's one that creates a new armor bonus ability that gives a bonus of 64 at level 1, the second call then creates a new item based on the existing protective ring item. It is assigned the new ability and a new name:

vJASS:

    //! external ObjectMerger w3a AId1 Ad64 Idef 1 64
    //! external ObjectMerger ObjectMerger w3t rde1 Id64 iabi Ad64 unam "Protective Ring (+64)"

This next example makes a copy of the fence doodad (NOfl), changes it so it has three variations and then tints the first variation all blue, the second variation all green and the third variation red:

vJASS:

    //! external ObjectMerger w3d NOfl Dfen dvar 3 dvr1 1 0 dvg1 1 0 dvr1 2 0 dvb1 2 0 dvg1 3 0 dvb1 3 0

This last example creates a chaos ability to morph into a peasant. Apparently Warcraft doesn't mind abilities having the same id as units, so I gave the ability hpea as id:

vJASS:

    //! external ObjectMerger w3a Sca1 hpea anam "My Chaos" ansf (Peasant) achd 0 Cha1 1 hpea

Now let's use the last example to take a closer look at the parameters. First of all you'll need to specify the type of object that you want to create. This is done by putting the file extension of this type as the first parameter, use this table as a reference. The example has w3a which means we're creating an ability. The next parameter is the rawcode of the base object that we want to copy, this can be a standard object or also a custom object that you previously created in the object editor or with a previous call to this Object Merger tool. To find out the rawcode of an object use View/Display Values as Raw Data from the object editor menu. The third parameter is the id that the created object should have, you're free to choose any 4-letter-id that isn't already used by an object of the same type. Then follows a list of pairs or triples that specifies the changes you want to apply to the base object. The first pair here is anam "My Chaos" which sets the name of the created ability to My Chaos. The left part of such pairs is a 4-letter-change-id that determines which field should be updated, the right side is the new value. The next one sets the editor suffix, as you can see the quotes are not needed if the string doesn't contain spaces. Then the check tech dependencies flag is set to false. You'll notice that booleans are simply represented by 1 (true) and 0 (false). Finally there's also an example for a change triple. This is needed for fields that can be changed per level. In this case the target unit id for the chaos morph is set to hpea for level 1. If you're not sure if a field requires a pair or a triple, you can test it by increasing the level of the base ability in the object editor and looking if the field repeats for multiple levels. Upgrades also use levels for some fields as you can see in the first example where the icon is changed for level 2 of the upgrade. Doodad variations work similar. In the third example such triples are used to change the tinting values of the 3 variations of the created doodad. All other object types like units, items, buffs and destructables only use pairs and never triples because they don't have levels.

At this point you may wonder where to look up all those change ids. The answer is that with Grimoires object editor hack the ids of each change will be shown in brackets. Make sure that View\Display Values as Raw Data is disabled when you want to view these ids. Alternatively you can look up the ids in the appropriate MetaData.slk file for the respective object type. On a note about the inner workings, all vJASS external calls get evaluated whenever the map is saved. That means whenever you save the Object Merger will create the same objects that will overwrite each other over and over again, which isn't necessary, so after the first time you save you can technically remove the external call again.

### Known Issues

Be careful when choosing the ids of your generated objects. Don't use ids that already exist, this can overwrite your existing objects. If you want the new objects to show up in the object editor you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY. Also do only merge object files that have been exported with the File Exporter tool to Objects\ or the export object data function of the world editor. Otherwise TRIGSTR references could be missing.

### LUA Benefits

First of all you can speed it up a lot, because you can create all your objects in a single external call. Then there are some additional functions available which you can use to reset objects, reset changes and apply changes to specific objects, all custom, all original, all modified original, or all unmodified original objects with a single script call. Also you can use LUA to program custom formulas to generate your object ids and for autofill-like needs.

## Constant Merger

The Constant Merger plugin works quite similar to the Object Merger tool, but instead of object editor data it imports customizations to the gameplay constants, the game interface settings and certain test map settings. If one of your system requires a specific change to the game interface or gameplay constants you can use a vJASS external call to this tool so that the required changes are automatically applied to a map that uses your system when it is saved. For example you might want to change the chat recipient prefixes for a chat system or you might want to customize the experience gain table for a levelup system.

Usually you will want to import customizations that were exported previously from another map by using the File Exporter tool. All files that it places inside the Constants\ folder after the export can be handled by the Constant Merger. There are three types of files that can be handled:

- war3mapMisc.txt gameplay constants
- war3mapSkin.txt game interface settings
- war3mapExtra.txt test map settings (the only occurrance where I've actually seen this file is, when you select an external object data source in the test map tab of the map properties dialog)

You can merge several files of the same type with a single Constant Merger call, but do NOT mix different types in a single call. This tool is also available from the menu Extensions\Merge Constants Data which pops up a file selection dialog. The other option is a vJASS external call like in this example:

vJASS:

    //! external ConstantMerger C:\MyMap\Constants\war3mapSkin.txt ..\otherInterfaceStuff.txt

### Known Issues

If you want your changes to show up in the editor you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY. Also do only merge files that have been exported with the File Exporter tool to the Constants\ folder. Otherwise TRIGSTR references could be missing.

### LUA Benefits

It's also possible to set values from within the LUA script, not only by merging files.

## Trigger Merger

The Trigger Merger plugin is capable of adding the trigger data form another map to your map. That means it can import variables, GUI triggers and also the custom text triggers and header. So technically it is now possible to distribute GUI trigger systems that are easy to import into any map.

Use it with caution though, since variables and triggers that have the same name like existing variables/triggers will overwrite them. So if you're developing a system that you want to distribute this way you'd better use a unique prefix for your variables and triggers to prevent possible conflicts. Also the custom text header of the imported trigger data will be put into a new custom text trigger, so that the existing custom text header of your map won't be touched. The input for the tool is pair of wtg and wct files. You only need to specify one of the two as the input file, the tool will look for a file with the same path and name and only the extension changed and use it as the second input file. The easiest way to obtain a wtg and wct file is by using the File Exporter tool which will put the trigger data into the Triggers\ subfolder of the export target folder. Trigger files that have been exported using a MPQ viewer shouldn't be used as input files, because they will be missing TRIGSTR references.

Again it's possible to use it from the menu using Extensions\Merge Trigger Data and then selecting one of the two input files in the file browser, or from a vJASS external call. Here's an example that will add the triggers from an external file to your map:

vJASS:

    //! external TriggerMerger C:\MyMap\Triggers\war3map.wtg

You can also merge the trigger data of several maps with a single call, simply list all the files that you want to merge as parameters of the external call. However you should always only list one file of a wtg/wct pair, never both in the same call:

vJASS:

    //! external TriggerMerger C:\MyMap\Triggers\war3map.wtg C:\OtherMap\Triggers\war3map.wct

### Known Issues

If you want the imported triggers to show up in the editor you need to close and reopen the map WITHOUT manually saving it. When using the tool from the menu this step is MANDATORY. Also do only merge files that have been exported with the File Exporter tool to the Triggers\ folder. Otherwise TRIGSTR references will be missing. The tool also doesn't check for duplicate JASS functions, so if two imported custom text headers both contain the H2I function this will of course cause compile errors and needs to be manually fixed. Also if the imported data contains references to generated unit, destructable, item, sound, region or camera variables those will be lost in the target map.

### LUA Benefits

You can register global GUI variables from within the script without having to merge files.

## Patch Generator

The Patch Generator has been created to produce World Editor patches, specifically to port UMSWE to NewGen. UMSWE has been implemented entirely in LUA scripts which are interpreted by this Patch Generator tool. This means you can use the Patch Generator to produce your own MPQ patches for the World Editor or the Warcraft 3 game. Check out the LUA scripts in the umswe\ subfolder of your NewGen directory for sample scripts. Here's how you call the tool from the command line:

Patch Generator:

    script.lua lookuppaths patchname { flags }

The first parameter is the script you want to run, the second as usual is a list of directories used to lookup file paths that cannot be resolved. The third parameter is the name of your patch, a txt file with this name is created in the logs/ subfolder of NewGen when you run this tool. Then you can pass a list of options which will be registered as global boolean variables in the LUA space. This is useful so you can use the same LUA script to turn a patch on and off with only the passed option changed. For example you could pass in "enable=1" or "enable=0" and in the script you can use if enable then to act depending on that option. Again, the UMSWE scripts are good samples to learn from.

## Grimoire Addons

### Registry Fixes

Via Extensions\Enable Local Files you can enable and disable local files on your system. When it's on Warcraft will load files from local folders with a higher priority than the files from the mpqs. This enables you to override war3patch.mpq with your own files, without messing with the mpq for rapid testing purposes. Local files means that inside your Warcraft directory you could place a Units\ subfolder and for example put a custom AbilityMetaData.slk file in there that will be loaded instead of the file from the mpqs. This way it's also possible to override files that normally don't load when imported into a map (like all the meta data files or CliffTypes.slk).

Using Extensions\Register Shell Extensions you can add items to the context menu of Warcraft maps and campaigns. When this is enabled and you right click a map or campaign the context menu that pops up will show a Play Fullscreen and Play Windowed option:

### No Limits Integration

This is an improved version of the old No Limits patch that is integrated in Grimoire that removes unit, item, doodad and map size limits. With the menu entry Grimoire\Disable WE Limits you can enable and disable this feature. Additionally the possibility to create epic 480 x 480 maps has been added to the editor. But watch out, some people have told me about blight not working properly in maps that large. As you can see the hack is directly integrated into the create map dialog:

### Test Map Hack

The menu entry Grimoire\Customize Test Map Settings will show the following configuration dialog:
As you can see it allows to speed up the game speed for your tests (just like you normally speed up replays) by a factor of up to 25. It can also disable fog of war and the victory and defeat conditions for your test runs in case you are testing a melee map. Additionally you can play around with player colors, add computer controlled players for your tests and assign custom handicaps and even ai scripts. However make sure that Use Custom Forces is disabled in the force properties of your map, otherwise the test map settings will not work. With the upper left checkbox you can also enable and disable the custom test map settings. When it's disable the map starts as usual when clicking the test map button, otherwise the custom settings will be applied.

### Object Editor Hack

Finally there's a new hack that allows you to specify custom rawcodes for new objects in the object editor. It can be enabled and disabled with the Grimoire\Enable Object Editor Hack menu entry. Additionally all object properties will also show their internal rawcode in brackets. You will need those if you want to use the Object Merger tool in your map. Here's a screenshot of the hack in action:
By the way this hack can be used to create copies of non-hero units and even buildings which are heros. This is done by simply capitalizing the first character of the new unit id.

## Appendix

### Tileset List

- A Ashenvale
- B Barrens
- C Felwood
- D Dungeon
- F Lordaeron Fall
- G Underground
- L Lordaeron Summer
- N Northrend
- Q Village Fall
- V Village
- W Lordaeron Winter
- X Dalaran
- Y Cityscape
- Z Sunken Ruins
- I Icecrown
- J Dalaran Ruins
- O Outland
- K Black Citadel

### Tile Id List

- Ldrt Lordaeron Summer Dirt (cliff)
- Ldro Lordaeron Summer Rough Dirt
- Ldrg Lordaeron Summer Grassy Dirt
- Lrok Lordaeron Summer Rock
- Lgrs Lordaeron Summer Grass (cliff)
- Lgrd Lordaeron Summer Dark Grass
- Fdrt Lordaeron Fall Dirt (cliff)
- Fdro Lordaeron Fall Rough Dirt
- Fdrg Lordaeron Fall Grassy Dirt
- Frok Lordaeron Fall Rock
- Fgrs Lordaeron Fall Grass (cliff)
- Fgrd Lordaeron Fall Dark Grass
- Wdrt Lordaeron Winter Dirt
- Wdro Lordaeron Winter Rough Dirt
- Wsng Lordaeron Winter Grassy Snow
- Wrok Lordaeron Winter Rock
- Wgrs Lordaeron Winter Grass (cliff)
- Wsnw Lordaeron Winter Snow (cliff)
- Bdrt Barrens Dirt
- Bdrh Barrens Rough Dirt
- Bdrr Barrens Pebbles
- Bdrg Barrens Grassy Dirt
- Bdsr Barrens Desert (cliff)
- Bdsd Barrens Dark Desert
- Bflr Barrens Rock
- Bgrr Barrens Grass (cliff)
- Adrt Ashenvale Dirt (cliff)
- Adrd Ashenvale Rough Dirt
- Agrs Ashenvale Grass (cliff)
- Arck Ashenvale Rock
- Agrd Ashenvale Lumpy Grass
- Avin Ashenvale Vines
- Adrg Ashenvale Grassy Dirt
- Alvd Ashenvale Leaves
- Cdrt Felwood Dirt (cliff)
- Cdrd Felwood Rough Dirt
- Cpos Felwood Poison
- Crck Felwood Rock
- Cvin Felwood Vines
- Cgrs Felwood Grass (cliff)
- Clvg Felwood Leaves
- Ndrt Northrend Dirt (cliff)
- Ndrd Northrend Dark Dirt
- Nrck Northrend Rock
- Ngrs Northrend Grass
- Nice Northrend Ice
- Nsnw Northrend Snow (cliff)
- Nsnr Northrend Rocky Snow
- Ydrt Cityscape Dirt (cliff)
- Ydtr Cityscape Rough Dirt
- Yblm Cityscape Black Marble
- Ybtl Cityscape Brick
- Ysqd Cityscape Square Tiles (cliff)
- Yrtl Cityscape Round Tiles
- Ygsb Cityscape Grass
- Yhdg Cityscape Grass Trim
- Ywmb Cityscape White Marble
- Vdrt Village Dirt (cliff)
- Vdrr Village Rough Dirt
- Vcrp Village Crops
- Vcbp Village Cobble Path
- Vstp Village Stone Path
- Vgrs Village Short Grass
- Vrck Village Rocks
- Vgrt Village Thick Grass (cliff)
- Qdrt Village Fall Dirt (cliff)
- Qdrr Village Fall Rough Dirt
- Qcrp Village Fall Crops
- Qcbp Village Fall Cobble Path
- Qstp Village Fall Stone Path
- Qgrs Village Fall Short Grass
- Qrck Village Fall Rocks
- Qgrt Village Fall Thick Grass (cliff)
- Xdrt Dalaran Dirt (cliff)
- Xdtr Dalaran Rough Dirt
- Xblm Dalaran Black Marble
- Xbtl Dalaran Brick
- Xsqd Dalaran Square Tiles (cliff)
- Xrtl Dalaran Round Tiles
- Xgsb Dalaran Grass
- Xhdg Dalaran Grass Trim
- Xwmb Dalaran White Marble
- Ddrt Dungeon Dirt (cliff)
- Dbrk Dungeon Brick
- Drds Dungeon Red Stone
- Dlvc Dungeon Lava Cracks
- Dlav Dungeon Lava
- Ddkr Dungeon Dark Rock
- Dgrs Dungeon Grey Stones
- Dsqd Dungeon Square Tiles (cliff)
- Gdrt Underground Dirt (cliff)
- Gbrk Underground Brick
- Grds Underground Red Stone
- Glvc Underground Lava Cracks
- Glav Underground Lava
- Gdkr Underground Dark Rock
- Ggrs Underground Grey Stones
- Gsqd Underground Square Tiles (cliff)
- Zdrt Sunken Ruins Dirt (cliff)
- Zdtr Sunken Ruins Rough Dirt
- Zdrg Sunken Ruins Grassy Dirt
- Zbks Sunken Ruins Small Bricks
- Zsan Sunken Ruins Sand
- Zbkl Sunken Ruins Large Bricks (cliff)
- Ztil Sunken Ruins RoundTiles
- Zgrs Sunken Ruins Grass
- Zvin Sunken Ruins Dark Grass
- Idrt Icecrown Dirt
- Idtr Icecrown Rough Dirt
- Idki Icecrown Dark Ice
- Ibkb Icecrown Black Bricks
- Irbk Icecrown Runed Bricks (cliff)
- Itbk Icecrown Tiled Bricks
- Iice Icecrown Ice
- Ibsq Icecrown Black Squares
- Isnw Icecrown Snow (cliff)
- Odrt Outland Dirt
- Odtr Outland Light Dirt
- Osmb Outland Rough Dirt (cliff)
- Ofst Outland Cracked Dirt
- Olgb Outland Flat Stones
- Orok Outland Rock
- Ofsl Outland Light Flat Stone
- Oaby Outland Abyss (cliff)
- Kdrt Black Citadel Dirt (cliff)
- Kfsl Black Citadel Light Dirt
- Kdtr Black Citadel Rough Dirt
- Kfst Black Citadel Flat Stones
- Ksmb Black Citadel Small Bricks
- Klgb Black Citadel Large Bricks
- Ksqt Black Citadel Square Tiles
- Kdkt Black Citadel Dark Tiles (cliff)
- Jdrt Dalaran Ruins Dirt (cliff)
- Jdtr Dalaran Ruins Rough Dirt
- Jblm Dalaran Ruins Black Marble
- Jbtl Dalaran Ruins Brick
- Jsqd Dalaran Ruins Square Tiles (cliff)
- Jrtl Dalaran Ruins Round Tiles
- Jgsb Dalaran Ruins Grass
- Jhdg Dalaran Ruins Grass Trim
- Jwmb Dalaran Ruins White Marble
- cAc2 Ashenvale Dirt (non-cliff)
- cAc1 Ashenvale Grass (non-cliff)
- cBc2 Barrens Desert (non-cliff)
- cBc1 Barrens Grass (non-cliff)
- cKc1 Black Citadel Dirt (non-cliff)
- cKc2 Black Citadel Dark Tiles (non-cliff)
- cYc2 Cityscape Dirt (non-cliff)
- cYc1 Cityscape Square Tiles (non-cliff)
- cXc2 Dalaran Dirt (non-cliff)
- cXc1 Dalaran Square Tiles (non-cliff)
- cJc2 Dalaran Ruins Dirt (non-cliff)
- cJc1 Dalaran Ruins Square Tiles (non-cliff)
- cDc2 Dungeon Dirt (non-cliff)
- cDc1 Dungeon Square Tiles (non-cliff)
- cCc2 Felwood Dirt (non-cliff)
- cCc1 Felwood Grass (non-cliff)
- cIc2 Icecrown Runed Bricks (non-cliff)
- cIc1 Icecrown Snow (non-cliff)
- cFc2 Lordaeron Fall Dirt (non-cliff)
- cFc1 Lordaeron Fall Grass (non-cliff)
- cLc2 Lordaeron Summer Dirt (non-cliff)
- cLc1 Lordaeron Summer Grass (non-cliff)
- cWc2 Lordaeron Winter Grass (non-cliff)
- cWc1 Lordaeron Winter Snow (non-cliff)
- cNc2 Northrend Dirt (non-cliff)
- cNc1 Northrend Snow (non-cliff)
- cOc1 Outland Abyss (non-cliff)
- cOc2 Outland Rough Dirt (non-cliff)
- cZc2 Sunken Ruins Dirt (non-cliff)
- cZc1 Sunken Ruins Large Bricks (non-cliff)
- cGc2 Underground Dirt (non-cliff)
- cGc1 Underground Square Tiles (non-cliff)
- cVc2 Village Dirt (non-cliff)
- cVc1 Village Thick Grass (non-cliff)
- cQc2 Village Fall Dirt (non-cliff)
- cQc1 Village Fall Thick Grass (non-cliff)

## Credits

Here I'd like to thank everyone who has contributed in the creation and testing of the Grim Extension Pack and the Jass NewGen Pack as a whole. Special thanks go to the following people:

- PipeDream for Grimoire and valuable tips
- MindWorX found out that the test map settings can be customized
- Guessed provided the source code for his MDLX Converter
- Vexorian made JassHelper have external tool support
- StonedStoopid as the original creator of the no limits patch
- Zepir for countless hours of research and work on the file format specs
- ShadowFlare for her great SFmpq library
- Wc3Campaigns for hosting and a I used their tauren theme for this

Have fun, PitzerMike