TheNomad
12-03-2006, 4:56 PM
This tutorial will explain how to use a Grafting tool in general (Grafters are StarGraft, MemGraft and FireGraft). The difference between these tools is mainly in interface, but the same rules apply to all. Because StarGraft is not too widely used (compared to MemGraft), except to make up for the bug that MG crashes upon loading presets and my tool doesn't always fix it, I'll explain MemGraft. Those of you that will understand this tutorial will have no problems switching to StarGraft or updating to FireGraft once it'll be public.
Because FireGraft will have, let's say, "more" features (to say the least), I'll update this tutorial to explain the fun stuff it will have. But for now, onto the world of downgrading StarCraft... This tutorial won't explain how to downgrade since it is pretty easy, but for the sake of saving the world, I will include a link to a tutorial (http://www.staredit.net/index.php?tutorial=260).
Also, 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. That kind of tutorial just tells the reader to do "this and that" while the reader does it, but is unsure why. 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 :)
MemGraft is pretty self-explanatory and not every hard to use, if you have the patience to go through all items it has (menus, buttons, options etc.). In order to know how to use this program, you require 2 very important elements: LOGIC and PATIENCE (and I am not joking). The reason many have "nooby" bugs or errors or can't get one thing working is cos they don't have the logic to assemble some syntaxes or the patience to look where the bug is, so most just post :) So, in order for you to avoid that, I'll show you how to approach this program logically. Please, pay VERY close attention to the Notes of each section. They may help you avoid or track down bugs in your mods.
In order to properly follow this tutorial, I suggest you start DatEdit (any version).
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, but for the sake of simplicity, I attached it. 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.
So we covered the hardest part: the interface :)
Let's move on to the fun stuff. How to use each tab...
1. UNITS
DESCRIPTION:
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 ? :P (an original mod idea, actually).
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 2. 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, Flare, Restoration and the +50 Energy upgrade. 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.
So... I ask again: how 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... hmm... 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 ? :P What about "Cancel Add-On", in case we don't need an Add-On ?
And... don't forget the Rally Point. If you answered 10, then you're correct :)
2. BUTTONS
DESCRIPTION:
This must be the most fun out of all things in MemEditing. Unfortunately, MemGraft isn't THAT user-friendly when it comes to the interface. It is easy to understand, YES, 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. Easy, so far, eh ?
"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)
More about "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" button. There is only a "Create Unit" button. But that ACT is used for ALL units. So how does the game now ?! 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
Writing them down, is of course optional, but I figured you want this tutorial as simple as possible, and ALT+TABBING every 30 seconds is not that simple. Ready ? Good, 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 / 0; ACT: Create Unit / 0
Firebat: REQ: Can create unit / 32; ACT: Create Unit / 32
Ghost: REQ: Can create unit / 1; ACT: Create Unit / 1
Medic: REQ: Can create unit / 34; ACT: Create Unit / 34
Now make the notepad window small so that it is on top of MG, but doesn't eclipse it, or grab the piece of paper. Notice anything... related between them ?
If you are too tired to think, then close this tutorial since you disobeyed the second rule: PATIENCE :P For those of you that figured it out, congratulations!
The reason DatEdit is handy to have around is to see what Technology, Upgrade or Unit is which. You'll notice the IDs in DatEd 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. Nice idea eh ? 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 fulfil 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" :P. 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 whatever you want, but cos of tradition, I'll use "Hold Position" as example :)
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 :P). There you go, you now have a very obedient SCV.
3. STAT BAR
DESCRIPTION:
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.
I'll give 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.
NOTES:
Some of them aren't done. Or at least that's what we like to think :P 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 hte 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. If you chose 8/7, then you did it right :)
4. THE 4 REQs
DESCRIPTION:
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.
Again, I ask that you check all of them and experiment to get the hang of it, but I will explain how to use these tabs.
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.
More about "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 is", "Terran Marine", "Current Unit is", "Jim Raynor Marine"> is not the same as <"Current Unit is", "Terran Marine", "OR", "Current Unit is", "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.
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 is", "Defiler", "Or", "Current Unit is", "Unclean One", "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).
5. A.I.
DESCRIPTION:
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. The list with which is controlled by what made by me will be compiled along with FG's release and this tutorial's update in this thread.
EXERCISE:
Disallow the SCV to repair anything. Very simple, go to each "Repair" order (located under the "Build" orders) and uncheck "Used". Now you have a perfectly worthless SCV in case a building is burning to the ground :D
6. ASM
DESCRIPTION:
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:
Just because I want to be praised by all of you (and cos I KNOW most will show off with this :P), I will give you something fun to do.
Download Hex Workshop (http://www.bpsoft.com/downloads/index.html) 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 (attached here), 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... (no worries... it won't format... much :P just kidding, it will "improve" your unit a bit :) )
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 :)
BTW, DoA told me that 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. To add completely new stuff, you need to mod the EXE.
7. SAVING
Well, assuming you did everything right, remembred 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" :D 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 "NomadMod.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 your favorite MPQ editor (I use WinMPQ) and add the "mgPatch.mgd" file in a new folder called "Custom\". So the MG data file must ALWAYS be called "mgpatch" and must ALWAYS be placed in the "Custom" folder. 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). Remember that if you want to test my ASM example you MUST use SC 1.13e.
Enjoy :)
8. OPTIMIZATION
Although things like this will become natural once you get better, remmeber 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:
Barracks
Academy
Factory
Starport
Science Facility
Covert Ops
Now, let's check the DAT REQ if it's the same:
<"Current unit is", "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 is". This means that only Barracks can train it. You could, for example say:
<"Current unit is", "Barracks", "Or", "Current unit is", "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 ntoice that if you complete my "Shuttle with an attack" IceCC 1.3 tutorial which includes the DatEd steps, you will see it can attack in 1.14 as well, even though I don't have a memeditor for 1.14 to add that button. How ? Simple. If you'll check the "Basic Transport" buttons, you'll see they 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" :)
9. IN CLOSING...
... before you post complaining your 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 ahs different offsets
... before you post complaining that 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.
More about crashing (covering various other reasons which might or might not be related to MG) can be found here (http://www.staredit.net/index.php?showtopic=33333). A very useful thread :)
Also keep in mind the fact that if you can't put up with MG crashing so much everytime you load a preset, you can use the one for SC 1.1b that doesn't have this bug, but it means you'll have to downgrade SC.
-------------------
Hope this tutorial helped!
Good luck with memory editing and be careful to not crash StarCraft :)
Because FireGraft will have, let's say, "more" features (to say the least), I'll update this tutorial to explain the fun stuff it will have. But for now, onto the world of downgrading StarCraft... This tutorial won't explain how to downgrade since it is pretty easy, but for the sake of saving the world, I will include a link to a tutorial (http://www.staredit.net/index.php?tutorial=260).
Also, 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. That kind of tutorial just tells the reader to do "this and that" while the reader does it, but is unsure why. 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 :)
MemGraft is pretty self-explanatory and not every hard to use, if you have the patience to go through all items it has (menus, buttons, options etc.). In order to know how to use this program, you require 2 very important elements: LOGIC and PATIENCE (and I am not joking). The reason many have "nooby" bugs or errors or can't get one thing working is cos they don't have the logic to assemble some syntaxes or the patience to look where the bug is, so most just post :) So, in order for you to avoid that, I'll show you how to approach this program logically. Please, pay VERY close attention to the Notes of each section. They may help you avoid or track down bugs in your mods.
In order to properly follow this tutorial, I suggest you start DatEdit (any version).
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, but for the sake of simplicity, I attached it. 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.
So we covered the hardest part: the interface :)
Let's move on to the fun stuff. How to use each tab...
1. UNITS
DESCRIPTION:
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 ? :P (an original mod idea, actually).
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 2. 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, Flare, Restoration and the +50 Energy upgrade. 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.
So... I ask again: how 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... hmm... 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 ? :P What about "Cancel Add-On", in case we don't need an Add-On ?
And... don't forget the Rally Point. If you answered 10, then you're correct :)
2. BUTTONS
DESCRIPTION:
This must be the most fun out of all things in MemEditing. Unfortunately, MemGraft isn't THAT user-friendly when it comes to the interface. It is easy to understand, YES, 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. Easy, so far, eh ?
"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)
More about "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" button. There is only a "Create Unit" button. But that ACT is used for ALL units. So how does the game now ?! 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
Writing them down, is of course optional, but I figured you want this tutorial as simple as possible, and ALT+TABBING every 30 seconds is not that simple. Ready ? Good, 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 / 0; ACT: Create Unit / 0
Firebat: REQ: Can create unit / 32; ACT: Create Unit / 32
Ghost: REQ: Can create unit / 1; ACT: Create Unit / 1
Medic: REQ: Can create unit / 34; ACT: Create Unit / 34
Now make the notepad window small so that it is on top of MG, but doesn't eclipse it, or grab the piece of paper. Notice anything... related between them ?
If you are too tired to think, then close this tutorial since you disobeyed the second rule: PATIENCE :P For those of you that figured it out, congratulations!
The reason DatEdit is handy to have around is to see what Technology, Upgrade or Unit is which. You'll notice the IDs in DatEd 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. Nice idea eh ? 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 fulfil 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" :P. 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 whatever you want, but cos of tradition, I'll use "Hold Position" as example :)
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 :P). There you go, you now have a very obedient SCV.
3. STAT BAR
DESCRIPTION:
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.
I'll give 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.
NOTES:
Some of them aren't done. Or at least that's what we like to think :P 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 hte 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. If you chose 8/7, then you did it right :)
4. THE 4 REQs
DESCRIPTION:
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.
Again, I ask that you check all of them and experiment to get the hang of it, but I will explain how to use these tabs.
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.
More about "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 is", "Terran Marine", "Current Unit is", "Jim Raynor Marine"> is not the same as <"Current Unit is", "Terran Marine", "OR", "Current Unit is", "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.
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 is", "Defiler", "Or", "Current Unit is", "Unclean One", "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).
5. A.I.
DESCRIPTION:
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. The list with which is controlled by what made by me will be compiled along with FG's release and this tutorial's update in this thread.
EXERCISE:
Disallow the SCV to repair anything. Very simple, go to each "Repair" order (located under the "Build" orders) and uncheck "Used". Now you have a perfectly worthless SCV in case a building is burning to the ground :D
6. ASM
DESCRIPTION:
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:
Just because I want to be praised by all of you (and cos I KNOW most will show off with this :P), I will give you something fun to do.
Download Hex Workshop (http://www.bpsoft.com/downloads/index.html) 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 (attached here), 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... (no worries... it won't format... much :P just kidding, it will "improve" your unit a bit :) )
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 :)
BTW, DoA told me that 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. To add completely new stuff, you need to mod the EXE.
7. SAVING
Well, assuming you did everything right, remembred 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" :D 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 "NomadMod.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 your favorite MPQ editor (I use WinMPQ) and add the "mgPatch.mgd" file in a new folder called "Custom\". So the MG data file must ALWAYS be called "mgpatch" and must ALWAYS be placed in the "Custom" folder. 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). Remember that if you want to test my ASM example you MUST use SC 1.13e.
Enjoy :)
8. OPTIMIZATION
Although things like this will become natural once you get better, remmeber 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:
Barracks
Academy
Factory
Starport
Science Facility
Covert Ops
Now, let's check the DAT REQ if it's the same:
<"Current unit is", "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 is". This means that only Barracks can train it. You could, for example say:
<"Current unit is", "Barracks", "Or", "Current unit is", "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 ntoice that if you complete my "Shuttle with an attack" IceCC 1.3 tutorial which includes the DatEd steps, you will see it can attack in 1.14 as well, even though I don't have a memeditor for 1.14 to add that button. How ? Simple. If you'll check the "Basic Transport" buttons, you'll see they 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" :)
9. IN CLOSING...
... before you post complaining your 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 ahs different offsets
... before you post complaining that 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.
More about crashing (covering various other reasons which might or might not be related to MG) can be found here (http://www.staredit.net/index.php?showtopic=33333). A very useful thread :)
Also keep in mind the fact that if you can't put up with MG crashing so much everytime you load a preset, you can use the one for SC 1.1b that doesn't have this bug, but it means you'll have to downgrade SC.
-------------------
Hope this tutorial helped!
Good luck with memory editing and be careful to not crash StarCraft :)