How to - Use the Object Merger

[Azlier]

Today I will explain how to use the Grimex Object Merger, a useful tool.

The ObjectMerger is an external program that can be used to create or move object data, the stuff you change in the Object Editor. Moving object data from map to map is useful only in very specific circumstances. I will focus on the creation of new object data, instead.

Creating new object data with the ObjectMerger is done with a one line command. To run an existing ObjectMerger command, save the map. Exit the map. Open the map. Your new data will be there.

This tutorial will teach you the basic structure of an ObjectMerger command to create new object data.

Required

• NewGen WE
• Grimex (Comes with NewGen)

Yes, that's all. ObjectMerger is best used to create stacks of abilities, for things like Bonus. Creating many similar objects and editing a small part of each at once is made simple with the ObjectMerger. It is important to note that ObjectMerger is not called dynamically. You cannot create new abilities during gameplay.

You enter an ObjectMerger command into anything that accepts and parses Jass code (the map header or a trigger paged converted to Custom Script.) This most likely works in even the GUI Custom Script action.

//! external ObjectMerger

There. First, the //! tells Jasshelper that there is a special command to execute.

A parameter, for those who don't know, is something you input into a program or function that the program or function uses or changes internally.

The 'external' parameter tells that we need to call an external (duh) program. The name of the program? The second parameter. ObjectMerger.
In conclusion, don't bother figuring out how that part works and just type it in.

Now, what are we going to create? We need to know very badly. The next parameter tells what we're going to create. Here's a handy table.

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

Now, let's say we're creating a stun ability for a dummy caster.

So, begin our command and add the next parameter. w3a, ability.

//! external ObjectMerger w3a

Doing well! Now, we need the raw code of the ability to base our ability on. Storm Bolt, it stuns. That is the next parameter.

(Simple raw code tutorial.)

//! external ObjectMerger w3a AHtb

The next parameter is the raw code we want our new object to have. Let's call it STUN.

It is important to note that objects created via the ObjectMerger overwrite any existing ones that have the same raw code. Be careful about raw code overwriting, grasshoppah.

//! external ObjectMerger w3a AHtb STUN

That's the hard part. Now we can edit the ability itself!
Look at the inside of Storm Bolt, in the object editor (Display Raw Data turned off).

After every field, there is a small four letter code.

(Okay, I accidentally showed Aerial Shackles. Same concept.)

Let's do something simple. Let's change the name of the ability.
Scroll down to Text - Name. It should have (anam) after it. This is the important part.

//! external ObjectMerger w3a AHtb STUN anam "My Stun"

You see what I did there? First, anam. It tells what we need to change. Then, you enter a string value (does not accept variables) as your next parameter.

If you are not sure what type of parameter a field takes, press Ctrl + D and look at that field's value in the Object Editor. Beware, some fields which take integers will cause the ObjectMerger to supply the ASCII value of the integer you meant to supply. To avoid this, you need to use "\xxx", where xxx is a three digit number. This part is very important when dealing with Channel based abilities.

And, lastly, if a field can take multiple parameters (such as Unit - Abilities), you add a comma between each argument.

That's a simple edit. Now to slightly more complicated stuff. Let's set how many levels are in the ability.
Stats - Levels has the (alev) code after it. Perfect. Let's set the max level to 1.

//! external ObjectMerger w3a AHtb STUN anam "My Stun" alev 1

Yes, as you change more, it gets longer and more unreadable. Nothing I can change.

Let's edit the damage to 0. Now, this part is really important!
There are fields that multiply when you edit how many levels an ability has (damage, cooldown, etc.). When changing these with the ObjectMerger, you need to tell it which level this affects. Even on a 1 level ability. Annoying, I know.

Data - Damage's code is (Htb1). We need to modify level 1. So:
Htb1 1 0
This sets Level 1 Damage to 0.

//! external ObjectMerger w3a AHtb STUN anam "My Stun" alev 1 Htb1 1 0

Excellent! Go on to set cooldown and mana cost to 0. Duration, if you want an infinite stun.

//! external ObjectMerger w3a AHtb STUN anam "My Stun" alev 1 Htb1 1 0 acdn 1 0 amcs 1 0

Closer... We should've done this step earlier. You must set the model the ability uses to nothing. " " will do ("" does something weird. It gets replaced with //================).

It takes a string instead of the usual number. Exactly like the name did.

//! external ObjectMerger w3a AHtb STUN anam "My Stun" alev 1 Htb1 1 0 acdn 1 0 amcs 1 0 amat " "

There! A good dummy stun! I neglected to set duration to 0, but that is easy enough to do on your own.

This command is ready to run. Save the map. Exit the map. Open the map. Delete this line of code.
Check in the object editor, and voila! A nice dummy Storm Bolt, even named My Stun!

This isn't enough. Let's create a custom buff to go with our spell!

//! external ObjectMerger w3h BPSE STNB fnam "My Stun Buff"

I ordered ObjectMerger to copy BPSE (Stunned (Paused)), set the new buff's raw code to STNB, and changed the name to My Stun Buff. Let's add this buff to our custom stun.
The order in which you type the commands does not matter one bit.

//! external ObjectMerger w3h BPSE STNB fnam "My Stun Buff"
//! external ObjectMerger w3a AHtb STUN anam "My Stun" alev 1 Htb1 1 0 acdn 1 0 amcs 1 0 amat " " abuf 1 STNB

You can do this with units, doodads, destructables, whatever. It's just handiest to use with abilities and buffs, for there is no need to make masses of unit types.


Grimex is well coupled with textmacros. A textmacro to make an item, an ability, and give the ability to the item can greatly speed things up. Here's a textmacro to make a ring of protection, an armor ability to go with it, and ties the ability to the ring.

For information on how to use textmacros, see the Jasshelper Manual (World Editor Bible).

//! textmacro MakeArmorRing takes AMOUNT, NAME
  //! external ObjectMerger w3a AId1 AR$AMOUNT$ Idef 1 $AMOUNT$ anam "$NAME$" ansf "($AMOUNT$)"
  //! external ObjectMerger w3t rde1 AR$AMOUNT$ iabi AR$AMOUNT$ unam "$NAME$"
//! endtextmacro

Now, making new rings is cake!

//! runtextmacro MakeArmorRing ("01", "Crude Armor Ring")
//! runtextmacro MakeArmorRing ("02", "Minor Armor Ring")
//! runtextmacro MakeArmorRing ("04", "Lesser Armor Ring")
//! runtextmacro MakeArmorRing ("06", "Moderate Armor Ring")
//! runtextmacro MakeArmorRing ("08", "Armor Ring")
//! runtextmacro MakeArmorRing ("12", "Greater Armor Ring")
//! runtextmacro MakeArmorRing ("16", "Superior Armor Ring")
//! runtextmacro MakeArmorRing ("22", "Superb Armor Ring")
//! runtextmacro MakeArmorRing ("30", "Perfect Armor Ring")

This one was rather simple. It's perfectly possible to make the tooltips change depending on the input. Icons, too!

Imagine an RPG where you need ~12 of a certain potion, only slightly varying between types. Wouldn't it be a nightmare to manually make every single potion? Once you make a good textmacro you can do...

//! runtextmacro MakeHealingPotion ("100", "Simple Healing Potion")

Lua with ObjectMerger

Now, onto more complex, possibly more readable, and more flexible usage of the ObjectMerger. Feel free to disregard this section if you do not need more advanced ObjectMerger tools.

Good use of this method compiles much faster than the above methods, but takes a bit of time to learn.

It is possible to make an ObjectMerger lua script right in the trigger editor. The first thing we need is the external block. You may ignore the syntax and just see it as "heddur" and "fuder". It would be wise to look for an lua tutorial.

//! externalblock extension=lua ObjectMerger $FILENAME$

//Lua goes here.

//! endexternalblock

Now, we choose what type of object we are going to deal with. This is simpler than the w3u and w3a madness the previous method requires. Lines of lua script should be prefixed with [lJASS]//! i [/lJASS].

//! externalblock extension=lua ObjectMerger $FILENAME$

//! i setobjecttype("units") //"items", "upgrades", etc.

//! endexternalblock

And now we can finally get to the modification or creation of objects. One difference between this and one line ObjectMerger calls is that this can modify and create objects.

This is an example of modifying units.

//! externalblock extension=lua ObjectMerger $FILENAME$

//! i setobjecttype("units") //"items", "upgrades", etc.

//! i modifyobject("hpea")  //Let's proceed to modify the peasant. We can refer to the peasant with 'current'.
//! i makechange(current, "usca", 1.25)  //Set peasant scale to 1.25.
//More modifications here.

//! i modifyobject("hfoo")  //Now footman.
//! i makechange(current, "usid", 1000)  //Set day sight radius to 1000.
//More modifications.

//! endexternalblock

And that's how it's done! Creating objects is only slightly more complex.

//! externalblock extension=lua ObjectMerger $FILENAME$

//! i setobjecttype("units") //"items", "upgrades", etc.

//! i createobject("hpea", "h000")  //Copy the peasant, and give the new unit type the rawcode h000.
//As before, we can refer to it with 'current'.
//! i makechange(current, "usca", 1.25)  //Set our new unit's scale to 1.25.
//More modifications here.

//And just to show you that multiple object types in one block is perfectly valid...
//! i setobjecttype("items")
//! i createobject("afac", "i000") //Flute of Accuracy cloned.

//! endexternalblock

Combined with textmacros, this becomes rapid compiling gold.

But wait! There's even more!

It is possible to modify every WC3 object of a type at once! I think I'll let the script explain itself

//! externalblock extension=lua ObjectMerger $FILENAME$

//! i setobjecttype("units")

//! i makechange(custom, "usca", 1.25)  //Set the scale of all custom units to 1.25.
//! i makechange(original, "usca", 1.25)  //Set the scale of all original units to 1.25.
//! i makechange(modded, "usca", 1.25)  //Set the scale of all modified original units to 1.25.
//! i makechange(unmodded, "usca", 1.25)  //Set the scale of all unmodified original units to 1.25.


//! endexternalblock

 

[Romek]

This is useful, and original.
I haven't seen a tutorial about this before.

Let's wait for some more comments.

 

[Tyrande_ma3x]

It really is - I never knew how to use it and the day when you posted it I was in real need to understand its functionality since I wanted to create lots of units but with different stats and copy/paste wasn't really a great option. Good job!

 

[SerraAvenger]

Awesome!
How fast is adding units this way?
You know, it takes hours to save in object editor. Is this one faster?

PS: Love it <3

 

[Romek]

> How fast is adding units this way?
When you save a map, it creates the objects in the Object Editor.
Then you can remove the objectmerger line, and the map will have those objects.

 

[SerraAvenger]

> How fast is adding units this way?
When you save a map, it creates the objects in the Object Editor.
Then you can remove the objectmerger line, and the map will have those objects.

Y, but how long does this process take ^^
EDIT:
I mean, like how many seconds will the save process additionally take per w3u entry of the ObjectMerger=?

 

[Romek]

> Y, but how long does this process take ^^
Why don't you try it?
IIRC, it most certainly isn't instant. Takes a few seconds minimum (on my crappy computer). But you only ever wait once anyway.

 

[Azlier]

>create lots of units but with different stats
Hmm. Somebody actually wanted to use the ObjectMerger for units. The only real use I see in that is a Footman Frenzy map, to be honest.

>How fast is adding units this way?
If you're making only one or two objects, this is actually slower. You still need to go into the Object Editor and look up those little 4 letter codes. However, with things that require switching between Object Editor menus and such (Armor Rings, Healing Potions), it's much faster.

Processor-wise, it's about 2x as slow. The time is takes to process (The armor rings took about 10 seconds) is nothing to worry about, though.

>When you save a map, it creates the objects in the Object Editor.
Then you can remove the objectmerger line, and the map will have those objects.
Yes, that's in the tutorial.

The thing is, what more is there to add (besides the whole porting object data between map stuff. I've never needed that.)? Is there anything else to cover?

Edit: Huh. Two more posts while I was typing. Haven't had this happen in quite a while.

 

[UndeadDragon]

Wow, this looks cool. I have never even notcied that feature before

 

[Darthfett]

This would be really useful to import an entire spell, I think I'm going to start using this. Great job!

 

[Tyrande_ma3x]

> The only real use I see in that is a Footman Frenzy map, to be honest.
Or a summoning spell that requires ~20 units with increasing strength ... Something like that. I used the ObjectMerger for my Invoker spellpack to create those Spirits.

 

[Viikuna]

Its useful. I think people could use object merger more when submitting stuff.

And, for me it took something like 20 minutes to generate all 150 UnitProperties spells with object merger.

( Wonder how long it would have taken to create those 150 spells with object editor.. luls )

 

[Romek]

Creating new object data with the ObjectMerger is done with a one line command. To run an ObjectMerger command, save the map. Exit the map. Open the map. Your new data will be there.

Oh, that's it? I just think of a spell and save?

> Grimex commands are entered directly into the trigger editor.
Wut commands?

> First, you need to know what program to call.
How will I know that?
In fact, you could remove the whole "program to call", and just start with "//! external ObjectMerger". And explain what it is as a whole.

> //! external ObjectMerger
Where do I put that?

You don't actually explain the whole 'parameter' thing either.

 

[Azlier]

Kay, did some tweaking. Not much. Oh, and there are links. Links are fun. Except rickroll links. Those are awesome, not fun.

 

[Kenny]

Nice tutorial.

Once I got to the part where you say "does not accept variables" I started to think how awesome it would be if ObjectMerger could be used in conjunction with textmacro. I kept reading, the bang! textmacro with ObjectMerger, very awesome .

Once again, nice tutorial. Very original.

 

[Romek]

Approved. Good job.

Though, one last thing, what happens if someone uses parameters that shouldn't be available for the base spell?
For example, giving critical strike a "chance to bash"?

 

[Azlier]

Yay!

>For example, giving critical strike a "chance to bash"?
What sort of idiot would- the ObjectMerger would give you an error. Something about an invalid field. The ObjectMerger doesn't exactly give the best errors.

 

[XeNiM666]

Very nice tutorial! And like Romek said: Very original! <3

Your example of making 12 potions at the end of the tutorial os the one im looking for!

EDIT:
Will it create abilities/items/etc. like in the Object Editor and will it increase the map's size?

 

[Azlier]

>Will it create abilities/items/etc.
Yes. Exactly like in the Object Editor.

>will it increase the map's size?
The same amount of size it would take to make the stuff manually.

 

[Narks]

Do we have to delete the lines of code after we create the objects? Or can we just leave them in the map (assuming that our finished version will be optimized and have all those comments removed).