MemGraft

MemGraft is a "Grafting" tool, more specifically, a memory patching modding tool. Other Grafters are StarGraft and FireGraft. The difference between these tools is mainly in interface, but the same rules apply to all.

Tutorial

Please note that this tutorial won't give a sample of how to train a Civilian or anything like that. I decided not to, since I haven't been able to find even ONE tutorial that explains how to actually USE MemGraft. Like a beginner's guide on every aspect of this tool. Which is where this tutorial comes in. It will, however, have small examples for almost everything. I assume that after reading this tutorial to actually understand at least 50% of MemGraft and will get you eager enough to start experimenting in areas you want to. For example, if you feel you understand a section better than another, you can experiment only in that and so on. So... onward to the world of memory patching :)

Please, pay VERY close attention to the Notes of each section. They may help you avoid or track down bugs in your mods.

Required Tools

• DatEdit
• MemGraft
• WinMPQ
• nASM Assembler

Interface

The first thing MG will ask for upon initialization is a stat_txt file, having the extension of ".tbl". For those that have the StarCraft mpq source, it's in the "rez\" folder. If you don't have it, open "patch_rt.mpq" in WinMPQ and simply drag&drop it somewhere, like your desktop. Next, you'll see some tabs. And in order, with a bit more descriptive name listed...

• UNITS: This is a list containing all the used units in-game. The last few are, what I like to call, "virtual units". Although my nickname is not the best chosen, it implies that they are not real units, but more like unit-placeholders. Among them you'll find the "Cancel" groups (cancel construction, mutation, nuking etc.), "Unit" groups (cloaked, workers etc.), "Construction" groups (the list of buildings to be constructed by each race) and the best feature of StarCraft: replays.
• BUTTONS: self-explanatory, controls what buttons appear on each unit (or group of units)
• STAT BAR: The console you see when you select units. The console controls the wireframe (updating the wireframe to turn yellow when it takes damage, red when it doesn't have much to live, dark blue when it has full shields and displaying transported units etc.)
• UNIT REQ: This controls what pre-requisites each unit or building have. For example, in order to build a Ghost you need an Academy and a Science Facility with an attached Add-on: the Covert Ops.
• UPG REQ: This controls what requirements each upgrade needs. For example, you need Templar Archives to advance to the next level of Protoss Ground Weapons. But the Shields don't have a requirement.
• TECH-R REQ: This controls what you need to perform a research. You can control which building is in charge of researching and what pre-requisites you need for it.
• TECH-U REQ: This, as you have probably guessed, is the requirement for technologies used by units. You can set which unit is allowed to use which ability. Note that not all are customizable. (read the notes to find out why)
• A.I./Order: This controls the orders, the scripts and the ability casting that is done internally by the engine. What you can change here is only the condition to perform that sepcific Order. Note that not all are customizable.
• ACTIONS: These are the little fragments of code that handle what functions to call inside the game to perform a specific Order. More on this at the end.
• REQUIREMENTS: These are the conditions needed for an Action to perform. These are not the same conditions as those used by the Orders or the other 4 REQs.

Units tab

You will notice 3 items: "No. of commands", "Commands" and "Connected Unit". The only ones you'll need are the first 2. "No. of commands" is the total number of buttons. The "Commands" is the set of buttons controlled by this unit. As you have guessed, more units can control the same button set. In other words, you can give ALL units the Medic set, but you'll have to do a LOT of editing to allow all units to Heal, Blind or Restore :) But it isn't difficult, it just takes a long time. But hey - who'd want 150 units, all with the same ability, just different graphics, anyway ?

Notes

"No. of commands" is actually misleading at the same time with being accurate in its name. The first thing you should note is that it is called "No. of Commands" and not "No. of Buttons". This is because a good modder should distinguish between the two. Let's take the Academy. Everyone knows what it does. Among opening a new Unit Tech Tree (Ghost, assuming you have a Covert Ops, Firebat, Medic and Comsat Station), it also performs researches. What you have to also keep in mind is that an "Upgrade Research" is not the same with a "Technology Research".

While these things may seem trivial, they may be the cause of a few bugs if someone was to attempt a heavy total conversion. We all know that it has 5 buttons: U-238, Stim Packs, Optical Flare, Restoration and the +50 Energy upgrade (Caduceus Reactor). True. How many buttons do we have ? 5. OK... now let me change the question a bit. How many commands do we have ? If you answered 5, I'll stop and say it's wrong. We also have a "Cancel" button that cancels whatever it is that we told it to do. Writing 5 would mean that we won't be able to Cancel. (Except by clicking the Console). So, let's correct that mistake. You'd say we have 6 commands. Correct ? WRONG. Why ? I just said, there is a difference between upgrades and technologies. That means we need TWO Cancel buttons: one to cancel the technology we are researching and one to cancel the upgrade we're performing.

Hhow many commands do we have ? 7. Exactly. There may be 5 visible buttons, but 7 commands. And the number we need to input there is 7. Checking the Academy will show 7 is correct.

Also remember, while it is "OK" (more or less) to write a lower number than the actual number of commands, writing a higher number will result in a crash. And, remember that "No. of commands" should always be done ONLY after editing buttons. Otherwise you might miss some or put a high number in case you deleted some and wonder why it crashes.

Exercise

Now, let's test if you got it. How many buttons does the Command Center have ? So... it builds an SCV, Comsat, Nuke Silo, Lift-Off... 7 ? SCV, Comsat, Nuke, Lift-Off, Land, Move, Stop ? Sure... but what about the "Cancel Unit" ? We do need to cancel an SCV if we changed our minds, right ? What about "Cancel Add-On", in case we don't need an Add-On ? And... don't forget the Rally Point.

Buttons tab

Unfortunately, MemGraft isn't THAT user-friendly when it comes to the interface. It is easy to understand, but it becomes a pain if you want to actually use the program. The problem is, you can't quite always select what to add, where to add it, or what to remove. Thankfully, the BUTTON section isn't as buggy as other sections, so all you have to put up with is getting used to the way you do things. After that, it'll be a lot easier.

• "Command": This is the command we are working with atm. You can select it from the pull-down menu. To remove a certain command, select it, right-click and click DELETE. In opposition, to add a new button, you right-click and select ADD.
• "Position": This is the slot it uses. As you know, you can only have 9 slots. Using 0 or 10 may result in unforseen experiences.
• "Icon": Self-explanatory - it selects the Icon you wish to see in-game. As you will notice, the Command takes up the name of the icon.
• "Req type": this is a bit more difficult if you look at it on the first use of MG. In time, you'll see it isn't difficult to understand at all. This contains the conditions required to perform a specific action. They aren't conditions for an order, but an action. For example, the Barracks has the "Can Create Unit/Building" condition for an SCV. That means that if you can't create it (it is disabled in StarEdit or a requirement, like say, the Academy is missing, you can't train Medics of Firebats).
• "Action type": This is the performed action that will be executed once the requirement condition is fulfilled. For example, in the above case, assuming we DO have an Academy, we will train Medics or Firebats.
• "Req var": the variable here corresponds to the REQ type of the currently selected command. Some REQs need a certain var, some don't. You'll know which with experience.
• "Act Var": Same as above, only for the ACT type.
• "String": The text you'll see when you want to perform an ACT
• "Req String": The text you'll see when you have to perform a condition set by the REQ (such as seeing what you must build or research to perform the action)

Vars

OK, we settled what each item in the interface does... we settled that we can, for example, create a unit ONLY if a condition is met. But in the end HOW DO WE CREATE FIREBATS ?! There is no "Train firebat" command. There is only a "Create Unit" command. But that ACT is used for ALL units. So how does the game know ?! The answer is simple: VARS. Let's check out the Barracks button set. Before you start checking every menu, every command, every tab and before you say anything, switch to DatEdit. More importantly, the Units tab. Grab a piece of paper or open up notepad and write down the Unit IDs (and their names, of course, so that you know which is which) of the following units (found on the bottom right):

• Marine
• Ghost
• Firebat
• Medic

Let's switch to MG. Let's check the "Terran Marine". For the sake of simplicity, the syntax I'll use will be <REQ TYPE> - <REQ VAR> and <ACT TYPE> - <ACT VAR>.

Marine: REQ: Can create unit / Building - 0; ACT: Create Unit / 0 Firebat: REQ: Can create unit / Building - 32; ACT: Create Unit / 32 Ghost: REQ: Can create unit / Building - 1; ACT: Create Unit / 1 Medic: REQ: Can create unit / Building - 34; ACT: Create Unit / 34

I believe you noticed the pattern, since it is self-explanatory. The reason DatEdit is handy to have around is to see what Technology, Upgrade or Unit is which. You'll notice the IDs in DatEdit and use them in MG. Although you'll find out the details later, you can, for example, build a unit, say a Ghost, IF you research Personnel Cloaking first, but I'll let you figure it out how... but I suggest you do it later, when you get the hang of this more.

The best way to learn all about Actions and Reqs is to first, check ALL units and buildings and see how each action occurs and then start experimenting.

Notes

Not selecting a string for a command will result in a crash if you hover the mouse over that command. Pre-requisite strings are not ALWAYS required. They are required only if you need to fulfill a certain condition in order to perform that action (say, you need a Science Facility to Upgrade the weapons to Level 2). Not selecting a pre-requisite string when it is required and hovering that command will also result in a crash.

Exercise

Let's try one simple thing. Let's ADD a new button to the SCV: "HOLD POSITION". The only unused spot is Position 9. No, position 6 is used by "Return Cargo". And Yes, slot 9 is used, but only when building... so it won't bother us. Let's set it up:

Right Click the "Command" menu and choose ADD. Now, select the Position and input "9" (without the quotes, of course). Scroll through the Icons and choose Hold Position. Now, the REQ... You'll have to be a bit more experienced to know what to choose and why, but I'll help you on this one. The REQ we need is "Move, Stop, Attack, Repair (SCV)". This is the state the SCV is in when it isn't building or harvesting.

The ACT as you probably guessed, is Hold Position. The string we need for the ACT is h<0><3>H<1>old Position<0>. To update the changes, just click the SCV on the button list on the left. And the last thing we'll do is go to the UNITS tab, Select the SCV and change the number of commands to "10" (obviously, without quotes). There you go, you now have a very obedient SCV.

Star bar tab

As said, this controls the game console. There isn't much to discuss here, as you'll only go here if you'll add transportation abilities to a unit or remove them... or if you'll add a new Reaver-like unit that has 5 scarabs but moves faster or whatever.

A simple run down on most of them:

• 2/1: Normal Units
• 3/2: Normal Buildings (supply displaying is hard-coded; if the building is a food supplier, it will display that info)
• 4/3: Passengers Display (Shuttle / Dropship / Bunker)
• 5/4: Units that train (Reavers / Carriers)
• 6/5: Merging (Archon / Dark Archon)
• 7/6: Morphing (Larva Eggs / Lurker Eggs / Mutalisk Cocoons)
• 8/7: Passengers + Food (Overlord / Yggdrasill)
• 9/8: Power-ups

In the case of 5/4, this doesn't allow or disallow units to build subunits. It just displays the queue in the console, nothing more. Note that the queue and research progress bars are hard-coded. You can't add the hangar count for Scarabs, Interceptors or Mines either, as they are hard-coded features.

Notes

Some of them aren't fully done and implemented. Or at least that's what we like to think. So some combinations might result in the wireframe or health or energy displays not being updated. Like say, a unit is attacked. When you select it, instead of seeing the HP drop or the wireframe change colors, you'll notice that nothing happens. To see a change you must select another unit, than reselect this unit.

Exercise

Make the Dropship display the food count when it is not transporting any units, but display the passengers when it does.

The four REQs

As said before, each REQ (UNIT, UPG, TECH Research and TECH Usage) control what and who does something and why. Things like building Scarabs or Interceptors if we didn't reach the limit of the hangar, attacking only if we have a weapon, upgrading to Level 2 of a weapon or armor or shield upgrade if we built a certain pre-requisite and so on.

To erase ALL conditions, simply uncheck "Used" and click the item in the list again. If you want to add new conditions, that COMPLETELY replace the old ones, after unchecking "Used" and clicking the item in the list to refresh it, recheck "Used" and click the item again. Now, click "Opcode" to set a main condition. Note that they are not the same conditions found in the Button REQs. To add a parameter to a condition simply drag the slider to the right and select param. If the opcode doesn't need a param and you wish to add a new condition, simply select opcode instead of param after dragging the slider. Like with most settings in MG, remember to re-click the item in the list to refresh it.

Params

"Params" are to DAT Reqs what "vars" are to ACTION Reqs. The opcodes that require params usually have [next] written after them. Please take into account that omitting "OR" between "Must Have" or "Current Unit is" opcodes is considered as "AND". Therefore, <"Current Unit must be", "Terran Marine", "Current Unit must be", "Jim Raynor Marine"> is not the same as <"Current Unit must be", "Terran Marine", "OR", "Current Unit must be", "Jim Raynor Marine">.

Notes

Unfortunately, it isn't possible to remove any opcode conditions or add new conditions in-between other opcodes. So you have to do everything from scratch by "unusing" it, refreshing it by clicking the item again (or choosing a different item and returning to this item) and re-enabling "Used", and then start adding new opcodes and params.

Exercise

Make Plague researched by default... NO, it has nothing to do with the "Researched" flag from DatEdit.

A.I/order tab

This controls all the stuff that is A.I. related. Although if you are reading this tutorial it means that you don't wanna touch this stuff since it might make unpleasant effects, I won't talk too much about it. Once FireGraft is out, I'll post a lot of info on Orders.

Notes

The DAT Reqs and the slider work the same way as with the 4 REQs described above, so I won't explain them all over again. The Orders that don't have "Used" checked are in fact used internally by the engine or by a Computer opponent.

Exercise

Disallow the SCV to repair anything.

ASM: the requirements and actions tab

These tabs allow you to call functions and generate new effects by performing new commands.

Notes

Well, unless you know any ASM and debugging, of course, or at least, have the offsets, I don't suggest you touch the REQ and ACT tabs.

Exercise

I will give you something fun to do though.

Download Hex Workshop or start your favorite Hex Editor. Unfortunately, this little exercise is only for the MG modified by DoA that works with SC 1.13e.

Download nASM (found in the Required Tools section), a very simple and user friendly assembler. Now, open Notepad and write the following:

BITS 32
PUSH EBX
MOV EBX,[0x697EC4]
ADD [EBX+0x09],CX
POP EBX
RET

Now, go to START -> RUN (or press Windows + R) and type "cmd". I suggest you place nASM in C:\ Next, save the notepad text file as "113e.asm" or whatever name you wish and place it in the nASM folder.

In the command prompt, type "cd \", then "cd nasm". Now, type "nasmw 113e.asm" (or replace "113e.asm" with the name of your file).

All done, type "exit" and press ENTER. Install Hex Workshop if you haven't done so and start it (or start your hex editor) and open the "113e" file created in the nASM folder (NOT the file with the ".asm" extension)

Copy the HEX dump which should be 538B1DC47E690066014B095BC3. Now, go to the "ACTIONS" tab and right click the list and select "ADD". A new ACT called "NEW" was made. Note that "Rename" doesn't work and "Delete" is missing. You only have "Remove Last". "Undo" is also missing in MG, so be careful what you do. Go to the "New" ACT and simply copy paste the hex-converted asm in the textbox on the right. Click the "New" item again to refresh it.

Now, go to a simple unit. Because I doubt by now, that you are in any mood to go through all that button creation process, since you're probably wondering what the asm code I pasted does. Let's select the "Marine/Firebat + Heroes" button set. Go to "Stim Pack". Replace the icon with "Roar". Now, as REQ select "Always". As ACT select "NEW" and as ACT VAR type 15. (or any number you wish, but keep it between 5 and 20 for the sake of the famous simplicity). Now, re-click the "Marine/Firebat + Heroes" button item. When you will now test it in game, your Marine or Firebat will have something... "changed". And if you did it right, you'll see it instantly. Click it a few times to admire the blueish wireframe.

ALL stuff you do in the REQ and ACT tabs will only run on your machine, so running stuff like the above code in a network (Bnet or LAN) will cause desyncs and you to drop. To add completely new stuff, you need to mod the EXE.

Optimization

Although things like this will become natural once you get better, rememeber to optimize things where-ever possible. For example, look at the "Ghost" item in the Units REQ tab.

In the game, the COMPLETE tree is:

• Terran Barracks
• Terran Academy
• Terran Factory
• Terran Starport
• Terran Science Facility
• Terran Covert Ops

Now, let's check the DAT REQ if it's the same:

<"Current unit must be", "Terran Barracks", "Is not constructing an add-on", "Is not lifted off", "Terran Covert Ops", Terran Academy"> So... apart from the 2 fail-safes which any good programmer should add, it has only 3 requirements: Barracks, Academy and Covert Ops. Why ? Simple. The Covert Ops can only be built by a Science Facility, which can only be built if a Starport is constructed which can only be made if a Factory is created.

Please note the "Current unit must be". This means that only Barracks can train it. You could, for example say:

<"Current unit must be", "Terran Barracks", "Or", "Current unit must be", "Terran Factory">

... to also allow Factories to train it (assuming you added buttons for it). Also notice the "OR". Otherwise it meant "AND", since it actually says "Ghost: can be made if the current unit is a Barracks AND it isn't building an add-on AND it isn't lifted AND we have a Covert Ops AND an Academy".

Also try to look at how Blizzard does it. For example, you will notice that the "Basic Transport" buttons already have an ATTACK button. It's just that the main condition is "Unit has a weapon". ALWAYS remember to put conditions that make a flawless "programming" of your mod. That also means to try to add morphing or lift-off conditions whenever possible "just in case".

Another example of a quick optimization (more of a hack, actually) is for the "Plague" example above, making it researched by default. If you did change the slider with all the stuff as I told you, then skip this, otherwise you might hate me. A very quick "hack" to make it researched was to replace "must have tech" (third sliding point) to "Is BW". That way the conditions will ALWAYS be met (since we ARE playing BroodWar, or at least, I hope you are) and thus it will be researched.

<"Is hero", "OR", "Is BW", "Current Unit is", "Defiler", "Or", "Current Unit is", "Unclean One", "Is not morphing">

Ah... one more thing. I kept this for the end since it is a bit "more advanced". You can also add a new button set in the "BUTTONS" tab, but just as with the ASM tabs, you can't rename or delete button sets. You can only delete the last entry. Which means that you should be careful when you'll have around 10 buttons sets called "NEW".

Answers to exercises

• Buttons: If you answered 10, then you're correct.
• Stat Bar: If you chose 8/7, then you did it right.
• Requirements: Go to Tech-R REQ and disable the Used flag for "Plague". Re-click "Plague". Now, go to the Tech-U Req tab and select "Plague". The correct way to do this is: <"Current unit must be", "Zerg Defiler", "Or", "Current unit must be", "Unclean One (Defiler)", "Is not morphing"> (the "Is not morphing" is not really needed, but it is a good precaution assuming your defiler WOULD morph... since it won't, you can leave that out).
• A.I./Orders: Very simple, go to each "Repair" order (located under the "Build" orders) and uncheck "Used".

Common complaints

Below are simple ways to fix common complaints when using MemGraft.

Mod crashed

• check that the selected number of commands is not higher than the actual number of commands used
• check that you selected a string for the action
• check that you selected a string for the requirement (if needed)
• check that the MG version you have supports the SC version you're using; MG uses the registry entry for the SC executable; that means that if you have your own dev-folder that has SC 1.11b, 1.12b or 1.13e and your gaming folder has 1.14, don't wonder why it crashes, if the registry points to your gaming folder; to avoid this, always check the version displayed near the EXIT button before choosing Single Player.
• if you added a new REQ or ACT by typing things at random and used that REQ or ACT, don't wonder why it crashes
• if you added a new REQ or ACT in hex-converted ASM, and actually knew what you were doing, make sure the offsets are correct; each SC version has different offsets

Something doesn't work

• if a unit, upgrade or tech don't seem to work when you click them, make sure the 4 REQ tabs are set-up properly with the pre-requisites you want
• if you think you set it up correctly, but the button is always grey, type "medieval man". If you can click it and the action you wanted is performed, check the REQ in buttons or the 4 REQ tabs. If you click it and nothing happens, check the AI tab REQs.
• if the action or req strings display incorrectly or ask for wrong things (energy instead of supply or resources), make sure you chose THE CORRECT string from the stat_txt.tbl file. "Burrowing<0>" is not the same as "u<3>B<3>u<1>rrow<0>".
• if some of your settings weren't saved, make sure you refreshed EACH ITEM before switching tabs or saving it as an EXE. Best way is to choose different items once (that weren't changed) in each tab where you performed changes.
• make sure you properly added the mgd file in your mpq, that it was saved as MGpatch.mgd (not case-sensitive) and that it was put in the "custom\" folder (with a trailing backslash)

Saving your changes

Assuming you did everything right, remembered to update each item, update the button count, made all REQs as they should be and so on, it's time to get this baby on the road. We'll go to the "Misc" tab. In the "Patch_RT.mpq" textbox type the name you wish your MPQ to have. Please, avoid spaces and long names. Try to not go over 10 or 12 for best aesthetics.

In this example, we'll originally call it "Example.mpq". Oh, notice you need the \ before the filename. Don't forget that.

Now, go to the first tab, the one called "Main". Click "Save Release". ALWAYS call the mgd file "mgPatch.mgd". ALWAYS. (not case sensitive). If you call it "MyMod.mgd" or "SuperMod.mgd" or anything other than "mgpatch.mgd" it won't work.

Now select an EXE name, which can be anything, but again, keep it simple. Yes, you can use spaces here.

One last step before we're ready to test... Open WinMPQ and add the "mgPatch.mgd" file in a new folder called "Custom\". To add it, simply drag&drop it on the filelist. So the MG data file must ALWAYS be called "mgpatch" and must ALWAYS be placed in the "Custom\" folder (remember the trailing backslash). Once this is done, you're ready to test it. Just make sure the registry points to your modded SC exe (1.11b, 1.12b or 1.13e, depending on what MG version you used). Remember that if you want to test my ASM example you MUST use SC 1.13e. If you use MG with other version apart from the ones I enumerated, it'll crash.