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.
