Note: This tutorial is incomplete. Whether it will ever be completed is debatable. The contents herein were all written by Voyager7456[MM] unless stated otherwise.

Section 0: Table of Contents

Introduction to Modding
Basic .dat Editing
String Theory - An Introduction to TBL Editing
Fun With Images.dat
Introduction to GRPEditing
Basic Iscripting
Flingy.dat

Post has been edited 7 time(s), last time on Jan 11 2009, 9:29 pm by Voyager7456.

How to Make a StarCraft Mod
Or "How I Learned to Stop Worrying and Love the MPQ"


Section I: Introduction to Modding
...in which our protagonists are introduced to the world of modding

So, you've heard a lot about these "mods," but what exactly are they? Mod is short for modification, and they change aspects of StarCraft, from the graphics and weapons units use to abilities and even the objectives of the game. Through modding, you can customize StarCraft to your heart's content.

Here are some example screenshots to show you what kind of things are possible: 1 2 3

Let's start our modding journey by answering some common questions:

Q: Can mods screw up my copy of StarCraft?
A: Absolutely not! Not only is there no way for a mod to damage your StarCraft, but the changes a mod makes end as soon as you exit. You can enjoy many different mods and go back to regular SC as soon as you quit playing.


Q: Can I play mods with other people?
A: Yes! You can play mods with anyone who's running the same mod. Sometimes, however, mods are for older versions of StarCraft. For more information on how to play them, check out this article: <<replace when Wiki comes online>>


Q: How do I install an older version of StarCraft?
A: We use a program called SCDowngrader3 to do this. It's very simple to use, and is available here: <<replace when DLDB comes online>>


Q: Different mods require different versions... but how can I tell what version a mod needs?
A: Ideally, the modder would include a readme and tell you that information.

However, here's a quick mod identification guide:


Figure 1-1: Common types of mods.

1. MPQ - This type of mod has the extension .mpq and can be run on any version of StarCraft through the use of MPQDraft. We'll talk more about how to run MPQ mods later.

2. CWD - This type of file has an extension of .cwd. It's very old and can only be run through StarDraft, an outdated modding tool. We'll talk about how to convert them to more modern formats in Appendix V.

3. Either a SEMPQ (Self-Executing MPQ) or a SECWAD (Self-Executing CWAD). A SEMPQ is a MPQ file that's bundled in an EXE allowing you to run it simply by double-clicking. A SECWAD is the same thing, except with a CWAD instead of an MPQ. SECWADs cannot be run on versions apart from 1.07. Here's how you tell the difference. Run the file, and if you get a screen that looks something like this, then it's a SECWAD (the image may vary):


Figure 1-2: A typical SECWAD loading screen.

Don't worry, we'll learn how to convert SECWADs in Appendix V as well. If StarCraft loaded without any sort of dialog, it's a SEMPQ and can be run on any StarCraft version.

4. StarGraft Executable - These mods can only be run on 1.07. Again, Appendix V is the place for you if you'd like to update them.

5. MemGraft Mod - Depending on the version of MemGraft used to make them, these can only be run on 1.11b, 1.12b, or 1.13e. The only way to tell is to try and run them and see what happens.

6. FireGraft Beta Executable - These mods run on 1.14 and have a couple stability issues.

7. FireGraft Executable - The most modern modding format. They run on 1.15 and 1.15.1, depending on the version of FireGraft. Check the readme or ask the modder in question.


Q: How do I get started modding?
A: Reading this tutorial's a good start. Let's get right into it!

Post has been edited 3 time(s), last time on Aug 26 2008, 4:19 pm by Debardus.

Section II: Basic .dat Editing
...in which our protagonists learn to use DatEdit

First things first, we're going to need to download the following programs:
- DatEdit
- WinMPQ
- MPQDraft
<<replace with DLDB links>>

I also recommend you create a working directory somewhere to store all our modding files.


So, what are .dat files? They contain a lot of information StarCraft uses, including unit and weapons stats. .dat files determine what weapons and graphics units use, how much health they have and other attributes.

First, let's open DatEdit. It may be overwhelming at first, but DatEdit is actually very simple to use.


Figure 2-1: The DatEdit interface.

Tabs: These control what .dat file you are editing. For now, we'll stick to the Units and Weapons tabs.
Subtabs: These are unique to the Units tab and organize the various properties of a unit into categories.
Info Box: When you are editing a property, this box displays a description of it. Make sure to pay attention to what it says!
ID List: This lists the IDs in the .dat file you're editing. Since we're in units.dat, it displays a list of all the StarCraft units. Currently, the Terran Marine is selected.
Search: Can't find the unit you're looking for? Use the search feature!
ID Jump: This lets you jump directly to the ID you're looking for. As you get more comfortable with modding, you'll find this saves you a lot of time.


For our first mod, let's make some modifications to the Terran Marine. I'm going to give the Marine shields by checking the "Enable" box next to Shields. I'm also going to modify its health a little bit and change its armor amount. Doing this should be fairly self-explanatory, as it functions similar to StarEdit's unit stats dialog and DatEdit's Info Box provides help.

I'm also going to change the build time, which might require a little explanation. The number on the left is the actual value in the .dat file. A value of 24 corresponds to 1 second on the Fastest game speed. The box on the right is the time in seconds it will take to build. You can adjust this value by whole seconds by clicking the up/down increment buttons. If you want to fine-tune it further, you can edit the left box.


Figure 2-2: A summary of our changes so far.


Alright, now let's move on to the Advanced subtab. This stores various properties of the unit, many of which are only of interest to advanced modders, but I bet you can recognize a couple of them! I'm going to give our Marine regeneration, a permanent cloak and make it a Detector unit by checking the appropriate boxes. The Cloakable and Burrowable boxes may look tempting, but giving a unit Cloak or Burrow isn't as simple as that! For now, just stick to the first couple of properties. If you're following along, this is what changes we've made to the Marine:


Figure 2-3: Advanced unit properties.

I bet you're eager to see your changes, so let's learn how to save these files and run them as a mod. First, go to File-> Save As... and save the file as units.dat in your working directory.

Next, let's open WinMPQ and create a new MPQ file. Once we've done that, you'll notice the "Add" button became available. Click Add and choose the units.dat file you just saved. A box will appear asking for a folder name. All .dat files are stored in the directory arr\, so type that and hit OK.


Figure 2-4: Folder name dialog box.

If you did it correctly, your MPQ contents should look something like this:


Figure 2-5: MPQ contents.

The listfile is a file that is generated automatically by WinMPQ and tells it the names of files stored in your MPQ. There's no need to save, WinMPQ does this automatically, so we're ready to move on to the next step. As I mentioned earlier, MPQ files are run using MPQDraft.

When you open MPQDraft, you'll be confronted with two options, Create Self-Executing MPQ or Load MPQ Patch. We want to select the latter. For step one, select StarCraft as the program and the component, like this:


Figure 2-6: StarCraft should be selected as both the program and the component. Selecting StarEdit as the component allows you to run modded versions of the Campaign Editor.

On the next screen, click Browse for MPQs, find your working directory and double-click on your MPQ. It should appear with a checkbox next to it on the list of archives. Click next and then Finish, and SC should run with your changes.


Figure 2-7: We did it! Our changes ingame.


Ok, now that we've got a cool Marine, don't you think it's time he got a weapon that suits him? For this, we're going to need to go back to DatEdit and switch to the Weapons tab. We'll start by editing the Gauss Rifle (Normal) weapon, because by default, that's what the Marine starts with.

We can modify a lot of things from this tab, including splash radius, cooldown, damage and the weapons graphics. In this example, I'm going to show you how to make a laser weapon that does splash damage. First, I'm going to change the weapon damage and range a little. This is self-explanatory.

Next, what we need to do is change the "Explosion" value to Splash (Radial). This tells StarCraft that the weapon does splash damage. There are a couple other values there, most are for spells, Splash (Enemy) deals splash damage only to enemy units, Splash (Air) only to air units, and Normal just deals damage.

Now we need to edit the splash radii. The Inner radius is the distance from the weapon hit at which units take 100% of the initial weapons damage. At Medium range, they take 50% damage and at Outer range they take 25%. Splash radii are expressed in pixels.

To make the Marine fire lasers, we need to change the Graphics value to something like "Burst Lasers" and the weapon behavior to "Fly to Target" You can use any projectile graphic, if you'd like, but if you're going to use the "Fly to Target" behavior, make sure it's a weapon graphic that actually does fly to its target, like Seeker Spores or missiles. Using something like the Gauss Rifle will cause a crash.

There are a bunch of weapon behaviors, but stick to Fly to Target or Appears on Target for now... we'll go over the other ones later, because they require a little bit more advanced knowledge.

Finally, we can make a couple aesthetic changes, like changing the icon of the weapon and modifying the X Offset. The X Offset determines how far in front of the unit the weapon projectile appears. Let's modify it a little, so that the laser appears in front of the Marine, instead of on top of it.

Here's what my modified Gauss Rifle looks like:

Figure 2-8: Example weapons.dat entry.


Just like before, we're going to go to File -> Save As... and save our file, except this time we'll save it as weapons.dat. Then, go to WinMPQ and click Add, select the newly-saved weapons.dat file and enter arr\ as the folder name. arr\weapons.dat should now appear underneath arr\units.dat.

Congratulations, you're almost done with the basic DatEditing tutorial! One last thing to do, and it's the fun part... let's check out our Marine ingame once more:


Figure 2-9: Lasers, pew pew!

Very cool.

Next up, we'll learn about .tbl editing so we can change the name of our valiant Marine!

Post has been edited 1 time(s), last time on Aug 26 2008, 4:20 pm by Debardus.

Section III: String Theory - An Introduction to TBL Editing
...in which our protagonists learn to use TBLPad

For this chapter, we're going to need to download TBLPad and a StarCraft listfile.
<<replace with link>>

.tbl files are, as the name might suggest, simply large tables of strings. They control all the text ingame, from the names of units and weapons to the labels on buttons. Editing them is fairly simple, but there's a catch. First we need to extract them from the StarCraft MPQs.

Before extracting any files from the StarCraft MPQs, we need to give WinMPQ a listfile, because the original StarCraft MPQs do not have them. To do this, we go to Options and click the File Lists tab. Then we select Add List File... and browse for the listfile we downloaded at the beginning of the chapter. We'll only need to do this once.

After this is done, it's time to go to our StarCraft directory. The file we want to open is called patch_rt.mpq. You'll see a whole bunch of files, but the one we want is called rez\stat_txt.tbl, and it contains most of the strings in StarCraft. But wait! There are multiple copies of it! That's because there's a stat_txt for various languages. The English one has a Locale ID of 0, that's the one we're going to extract.


Figure 3-1: The Locale ID column.

To extract the file to our working directory, it's as simple as selecting it in WinMPQ and dragging it to the folder. The other .tbl file that is commonly edited is network.tbl, which contains a lot of the Battle.net strings, as well as the race names. For now, however, we'll focus on stat_txt.tbl

So, run TBLPad and we'll open the newly-extracted stat_txt.tbl. You can select a string on the left and edit it on the right. There's also a search feature to find strings easily. Let's edit the name of the Marine, which happens to be the first string.

The string for the Marine's name looks like this:

Terran Marine<0>*<0>Ground Units<0>

What is all this? Well, the Marine's string is broken into 3 substrings, separated by the tag <0>. The first is the unit's name, which appears ingame. The second appears in parentheses next to a unit's name in the map editor. For example, look at the string for Sarah Kerrigan. It appears in the editor as "Sarah Kerrigan (Ghost)" for easy identification. The third substring tells the map editor what folder to place the unit in. In our example, the Marine is to be placed in the Ground Units folder.

We'll edit the Marine's name by changing the first substring. Make sure to leave the others, especially the <0> tags alone.

That's all there is to it... or is it? If we left it like this, the Barracks would still say Build Marine! We need to edit the string for the Marine's button as well. To get to the Marine's build string, do a search for "arine" until you come to something that looks like this:

m<1>Train <3>M<1>arine<0>

Now what's all this? The first character in the string is the hotkey you can press to activate the button. The <1> tag tells StarCraft this string is the build string for a unit, which causes it to display the mineral, gas and supply cost underneath the string. If you want to read more about TBLPad String format, there's an article available here <<insert link>>, but for now we don't need to know about it.

The <3> tag before the M changes the color of the text, so ingame the M in "Train Marine" would be yellow, indicating that it's a hotkey. (<1> changes the color back to the default blue.) There is a list of the tags that change color at the bottom right of the TBLPad window. You can also use the characters commonly used in map editing.

Now that we know a little bit about how this string works, we can change it to better fit the name of our unit. My build string looks like this:

s<1>Train <3>S<1>hock Trooper<0>

The new hotkey is "s" to build a Marine and the string should look appear as "Train Shock Trooper" ingame.

If you'd like, you can go back to the unit's name and add colors to see how they work.





One last thing before we finish with TBLPad... let's change the name of the Marine's weapon. Do a search for "Gauss Rifle." This string's pretty simple, just the weapon name, ending with <0>. When you're finished, go to File-> Save and switch to WinMPQ.

Add your modified stat_txt.tbl file, but this time type rez\ as the folder name.


Figure 3-2: stat_txt.tbl should be stored in the rez\ folder.

You should now have 3 files in your MPQ (4 counting the listfile), units.dat, weapons.dat and stat_txt.tbl. Now let's run our mod and observe our changes.


Figure 3-3: A modified build string. If edited correctly, "s" should activate the button.


Figure 3-4: A modified unit name with colors and modified weapon name.

Awesome! Now we know how to edit unit names and build strings! Next, we'll play with images.dat to make some crazy effects.

Post has been edited 1 time(s), last time on Aug 26 2008, 4:21 pm by Debardus.

Section IV: Fun With Images.dat
...in which our protagonists learn about palettes

I hope you didn't think we were done with .dat editing! This time we're going to use the Images tab and play with palettes a little. There are a lot of properties in images.dat, but for now, we're going to focus on the ones labeled "Drawing Properties."


Figure 4-1: Drawing properties.

Let's take a look at exactly what these properties do:
Function:
- Normal Draw: uses the normal unit palette to render the image.
- Cloak options: use the appropriate cloak palette, fairly self-explanatory.
- EMP Shockwave: applies a distorted effect, like, well, the EMP Shockwave.
- Use Remapping: uses a palette from the Remapping list.
- Shadow/FoW: renders the graphic using the shadow palette.
- Warp Flash: renders the graphic as pure white at first and fades to transparent. It will cause crashes if it's used on images that stay around for a while (like units) but it's fine for weapons.
- Hallucination: uses the hallucination palette.

Remapping: more palettes... you have to use the "Use Remapping" value in Function though.
- ofire.pcx (Orange): An orange palette, like fire and lasers.
- gfire.pcx: A green palette, used for stuff like Seeker Spores.
- bfire.pcx: The blue version of gfire.pcx, used in things like Scarab explosions.
- bexpl.pcx: Another blue palette, used in things like Protoss explosions.


For a little example of images.dat palettes, we're going to change the color of the Marine's lasers. Also, we'll change the effect used on the Yamato Cannon.

First, let's search for the entry "Burst Lasers Hit" and change the Remapping value to "bexpl.pcx (Blue 2)." Search for the Burst Lasers entry and do the same thing.

Next, let's mess with the Yamato Gun... search for the Yamato Gun entry and change its Function to EMP Shockwave and do the same thing for "Yamato Gun Trail."

Save the file as images.dat and add it to our MPQ like we did with weapons.dat and units.dat. Now let's check out the changes ingame:


Figure 4-2: Blue lasers.

Be sure to check out the Yamato Gun effect yourself, the effect is difficult to convey in screenshots.

Before we end this chapter, I'd like to give you a couple tips on palette editing:

- If a unit uses the normal palette, don't tell it to use Remapping, and vice versa. This often causes crashes.
- bfire.pcx and gfire.pcx are very similar, so swapping them works really well. The same thing goes for ofire.pcx and bepxl.pcx. With the others, sometimes you get strange results.
- Go wild! Experiment with palettes and see what things look like. By doing this, you can create exciting new effects for your weapons.


This was a pretty short chapter, huh? Next up, we're going to learn how to make custom graphics for units!

Post has been edited 1 time(s), last time on Aug 26 2008, 4:22 pm by Debardus.

Section V: Introduction to GRPEditing

...in which our protagonists make a custom GRP.

For this section, we'll need RetroGRP <<blah blah insert link blah>> and a graphics editor, like Paint.

StarCraft graphics are stored as files called GRPs, which are collections of bitmap frames. To compile bitmaps into a GRP, we use a program called RetroGRP.

The first thing you're going to need to do when you load RetroGRP is set the Output Directory.


Figure 5-1: Set Output Directory.

Once we've done this, we need to extract a GRP from StarCraft's MPQs. The GRPs for most units are stored in StarDat.mpq (in your StarCraft directory), while the Brood War GRPs are stored in BroodDat.mpq.

Let's extract the Battlecruiser's GRP (unit\terran\battlecr.grp) to examine it. Once it's in your working directory, switch to RetroGRP click Load External File and choose the newly-extracted battlecr.grp.

Let's just at it for a second. You can press the < or > buttons to go forward/back one frame, or you can use the << 10 or 10 >> buttons to skip ahead 10 frames. You'll notice the Battlecruiser has only 17 frames. This is called a frameset. StarCraft units have 17 frames labeled 0-16, starting facing due north, and rotating 10.5 degrees per frame to reach 180 degrees at frame 16. The engine automatically mirrors these frames ingame to provide the frames for the left direction.

The Battlecruiser is a very simple GRP, having only one frameset. More complicated units can have multiple framesets, resulting in hundreds of frames for things like infantry units and Zerg creatures. In contrast, buildings often have very few frames, since they can only exist in one direction.

For this example, we're going to modify the Science Vessel GRP, which is located at unit\terran\wessel.grp. Extract it to our working directory and load it in RetroGRP. Then click "Write out BMPs." A dialog box will pop up, select "Only - Unique Bitmaps." Sometimes frames are duplicated in GRPs, for example, ground units turn in less directions than air units, and thus duplicate a couple frames in their framesets. Selecting this option creates .bmps for only the unique files.


Figure 5-2: Unique Bitmaps option.

Now, in your working directory RetroGRP should have created a wessel000.bmp file and a wessel.ral file. Wessel000.bmp is the Science Vessel's one and only frame, while wessel.ral is a list of those files. If you open it with Notepad, you'll see this:

wessel.grp
wessel000.bmp

This is the format that all .ral files follow: the first line is the name of the .grp the frames were decompiled from, and the next lines are a list of the frames. If we wanted to add additional frames to the Science Vessel, we would add some on new lines, but since the Science Vessel's iscript (more on that later) uses only one frame and this is just an example, we'll close the .ral file and open wessel000.bmp in Paint.

We can edit this file however we like (although keep in mind, frames cannot exceed 256x256 pixels in size.) This isn't a graphics tutorial, although there are some nice ones here <<insert link here>>. We're focused on the technical, not artistic aspect of modding in this tutorial, and the Science Vessel's appearance is up to you. This is my example unit:


Figure 5-3: The modified wessel000.bmp

Now that we've made our changes, we need to compile the frames back into a GRP file. To do this, we load RetroGRP, click "Compile to GRP" and select our .ral file from earlier. It should create a file called "x_wessel.grp" in our working directory. If everything's gone well, you should see this dialog:


Figure 5-4: Example of programmer humor.

To see it ingame, we need to add it to our MPQ at the path that the old Science Vessel GRP was stored. If you'll recall, this was unit\terran\wessel.grp. You should be getting the hang of adding files to an MPQ by now, so I'm sure I don't need to tell you how. Don't forget to rename it to remove the x_!

Feel free to edit other aspects of the Science Vessel like the name and health to represent its new nature! This will also serve as a good overview of what we've learned so far. Don't give it an attack yet, though... the Science Vessel doesn't have an attack animation, and we haven't learned how to make one yet!

Let's see our custom graphic ingame:


Figure 5-5: Nuclear Wessel in operation.


Custom graphics are a great way to change the feel of a mod! By making your own graphics, you get rid of people's pre-conceived notions of a unit and make it your own! There are also a number of custom GRPs available in our DLDB <<insert link here>> already made and free for you to use in your creations.

Now we know how to make custom graphics! We're well on our way to modding greatness... but first, you'll want to check out the next section of our tutorial, where we introduce a fundamental modding skill - iscripting.

Post has been edited 1 time(s), last time on Aug 26 2008, 4:23 pm by Debardus.

Section VI: Basic Iscripting
...in which our protagonists make laser gatling guns and car bombs.

For this chapter, we're going to need IceCC, and a text editor such as Notepad. <<you know the drill>>

So, what is iscripting? The animation of StarCraft graphics is controlled by a file called iscript.bin. It determines what frames units play when they attack, move, and die, as well as many other things. There are some amazing effects that can be done through iscripting!

Let's start off simply though. In this chapter, we're going to make two simple iscript effects, a suicide attack and a spread fire attack, as well as take a closer look at some of the common iscript commands.

The program that's commonly used to edit iscript.bin is called IceCC. The IceCC UI is run by double-clicking the .jar file in the IceCC directory. When you open it, you'll notice that the Decompiler tab is broken into four columns. These represent images, sprites, flingy and units.dat entries. You'll notice that a lot of entries are repeated in the four columns... this is because things like units have entries in all four .dat files. You only need to select the entry in one column to edit its iscript.


Figure 6-1: All these entries are identical.

We're going to start by taking a look at the Vulture's iscript. To do this, we need to decompile it. Select the Vulture in the units column. Then, where it says "Save to:," click Browse and save the file in your working directory as "vulture.txt." However, this does not actually create the file. To do this, we need to click Decompile. In our working directory, there should be a file called vulture.txt, let's open it and see what's going on.

It looks complicated, but let's work through it piece by piece. The first thing to note is that # is the comment character. Anything after a # is ignored by StarCraft.

Let's go through the next couple lines:

.headerstart - This line starts the header. The header contains information like the Iscript ID, the type of graphic this is, and what animations match what ingame events.
IsId 86 - This is the ID of the iscript.bin entry.
Type 13 - This is the type of the graphic. Various types have various numbers of animations in their header... for example, Type 21 is for Protoss Buildings, and contains a Warp-In animation. Type 13 is used for a lot of units.
Init VultureInit - Lines like this tell StarCraft what animation to use for certain events. This line is the Init animation, the one that plays immediately after a unit is constructed. "VultureInit" is the name of the label the script jumps to, and it can be found further down. Let's take a look at it:


VultureInit: - The label name.

imgul 257 0 7 # VultureShad (terran\Vulture.grp) - Imgul stands for "image underlay." It tells the engine to create an images.dat entry underneath this image. The first number is the images.dat entry to create, the second one is the horizontal offset (negative numbers move the image right, positive numbers to the left) and the last one is the vertical offset (positive numbers move the image down, negative numbers move the image up.)

So what does this command mean? It tells StarCraft to create images.dat entry 257 underneath this image and move it down 7 pixels. If we open DatEdit, we see that images.dat entry 257 is... the Vulture's shadow!

playfram 0x00 # frame set 0 - Remember back in the previous chapter where we talked about framesets? Well they come into play heavily in iscripting. This command tells StarCraft to use the first 17 frames (0-16) depending on what direction the unit is facing. The next frameset would be called 0x11, and the next 0x22, etc.

goto VultureGndAttkToIdle - This is a simple command, it tells StarCraft to go to the "VultureGndAttkToIdle" label after this animation is done playing. The Vulture uses its GndAttkToIdle animation as a sort of "catch-all" where it just waits for further instructions.


Are you still with me? I hope so, 'cause we're about to do our first iscript edit! We're going to transform the Vulture into a suicide attacker. The actual iscripting for this is going to be fairly simple, but we'll get into more complicated effects later. Right now, we need to look at the "VultureGndAttkInit" label. I'll run through it quickly with you so you understand what's going on:

wait 1 - The wait command tells the unit to pause. The units here are ticks, which are 1/10ths of a second.
attackwith 1 - Attackwith tells the unit to attack using a specific weapon. 1 is for ground weapons and 2 is for air weapons. There is also a command called attack, which causes the unit to automatically select the correct weapon depending on what type the target is.
gotorepeatattk - This command tells the unit to continue attacking the target until the unit is dead or it receives another command.
And the last line is a simple goto, like we discussed earlier. What we're going to do is insert an explosion effect before the Vulture attacks. To do this, I'm going to teach you a new command: sprol.

Sprol stands for "sprite overlay" and it causes the engine to create a sprites.dat entry above the current image. Now, you might be thinking "Hey, there's an imgul command... surely there's an imgol, why don't we use that?" Well, you're right... there is an imgol command, but there's a reason why we don't do that. Image overlays/underlays disappear after the unit dies, while sprites can remain independent of the image that spawned them. Since the Vulture is going to use a suicide attack, we want to use sprol.

The format for the sprol command is just like the one for imgul, except for one difference... the first number is now a sprites.dat entry, not a images.dat entry. So, what we're going to do is insert the following line just above where it says "attackwith 1":

sprol 267 0 0 #nuclear explosion

While you don't have to comment your opcodes, it's certainly good practice to... unless you want to look up sprites.dat entry 267 every time you open this script. That's all we're going to do for now, so let's save the file and close Notepad.

Now, we need to compile the iscript.bin file again. To do this, we're going to switch to the "Compiler" tab in IceCC. Press the Add button and then select your vulture.txt file. Down where it says "Save to:", click Browse and save it as iscript.bin, then hit Compile. If you've done everything correctly, you shouldn't see anything. IceCC doesn't display any message on a successful compile.



Figure 6-2: This is not what you want to see.

Often, if you do get an error, you get a whole long list of them... but don't worry! Sometimes one typo can derail the entire compiler and generate a whole bunch of errors... just go through your iscript carefully and fix errors one at a time, you'll find by fixing one command you can eliminate many errors at once.

But, since we didn't get an error, we've successfully compiled our first iscript! Now we need to add it to our MPQ under the folder name scripts\.

Before we run it, though, let's change the Vulture's attack. We need to transform the Fragmentation Grenades attack into an actual suicide attack. We can do this by changing the behavior to "Attack & Self-Destruct." Let's also change the attack graphics to "White Circle (Invisible). This is an invisible graphics entry that's used for units that don't need a visible weapon, like melee attackers. Since our Vulture already spawns an explosion in its iscript, we don't really need a weapons graphic! You might also want to change the weapon damage, range, icon and maybe even give it splash damage! Don't forget to make some stat_txt.tbl edits to reflect the Vulture's new nature!

Now let's check out our changes ingame:


Figure 6-3: BOOOOOOOOOOOOOOM!



Great, now let's move on to another simple iscript effect... remember our Marine from earlier? He's pretty cool, huh? But wouldn't he be cooler if... he shot a barrage of lasers that rained destruction upon everything in his path?

In the next half of this chapter, we're going to beef up the Burst Laser's graphic and have the Marine use a spread fire attack. Let's start by amping up the lasers. We're going to add a shockwave effect to the Burst Lasers, so first we'll need to decompile the Burst Laser iscript. To quickly find things in IceCC, we can use DatEdit's search function to find something in say, images.dat, look at the ID of the entry we want and then scroll down in IceCC.

The entry for the Burst Lasers happens to be Images entry #535, so select it and decompile it to a text file. Make sure to change the name!

As you can see, the Lasers iscript has far fewer animations than say, the Vulture! In fact, it has only three! LasersInit is the init animation, naturally. LasersDeath is the hit animation for the weapon, and LasersGndAttkInit is actually the traveling animation. There are a couple new commands in here, especially in the init animation, Let's take a look:

tmprmgraphicstart - This command temporarily hides the graphic. It still exists, but it's hidden.
trgtrangecondjmp 40 LasersLocal00 - This is a very cool command that we'll go into later. It tells StarCraft to jump to the label "LasersLocal00" if the targeted unit is 40 or fewer pixels away from the attacking unit.
tmprmgraphicend - This causes the graphic to appear again.

So what the LasersInit animation does is this: if the target is 40 pixels or less away from the attacker, it tells the laser to hide itself. This is done because lasers move very fast, and so it might overshoot the target. It still does other effects, like play sounds and spawn overlays, though, so the end result is if the target is less than 40 pixels away, the laser hit graphic appears on it instantly.

playsnd 74 # Bullet\TPhFi100.wav - Playsnd is a pretty simple command... it plays a sound. The number is the sfxdata.dat (Sounds tab) entry to play.

sigorder 1 - Sigorder is a command that tells StarCraft to execute a specific order... in the case of the Burst Lasers, it tells StarCraft the weapon has launched. Generally if a script has one of these, you want to leave it there.

Moving down to the LasersDeath label, we see the imgol command, which we should be able to use... and this new domissiledmg command which causes the weapon to deal damage. We're going to do two things to these lasers: we're going to have them deal damage to everything they touch, and we're going to add a shockwave.

We'll add a shockwave by adding two imgol commands right below the first one. Our imgols will look like this:

imgol 555 0 0 # EMP Shockwave 1
imgol 556 0 0 # EMP Shockwave 2

(A quick check in images.dat reveals that the "EMP Shockwave" effect actually has two seperate images.dat entries... one for the distortion and one for the white part.)

Well, that's fairly simple... what else should we do? Well, we're going to cause damage to targets the laser passes through by editing the traveling animation, GndAttkInit.

Right now, all it does is wait a long time and loop back on itself. What we're going to do is change the wait to a much smaller number, like 15, and then add a domissiledmg command after the wait. This will cause the laser to do damage to targets as it travels, as well as when it eventually hits.

Let's save this file and move on to the Marine. Decompile the Marine's iscript. You'll notice the Marine has a very large iscript, because it's an infantry unit. Don't worry about it for now, instead, just skip down to the MarineGndAttkInit animation. Hmmm, that's interesting... all that's in the MarineGndAttkInit animation is playframs! How does it attack?

Well, if an label doesn't have a goto or end statement at the end of it, StarCraft just keeps going into the next label. If you look in RetroGRP, you'll see those first 3 framesets are the process of the Marine raising its gun to fire, and then it moves to the next label, which is the actual firing animation. There's one command I'd like to talk about here, before we move on to editing the Marine's attack.

The nobrkcodestart command present in the Marine's attack animation tells the unit to ignore all orders until it receives a nobrkcodeend command. This is done in the Marine's attack animation so you can't interrupt a Marine while it's firing its weapon.

We're going to add a couple more "attackwith 1" commands to the Marine's firing animation... say, one more above each "playfram 0x33" and one at the end, right above the "nobrkcodeend" command. Save this text file and go to the Compiler tab in IceCC.

We're going to press the Add button and add the saved Burst Lasers text file, as well as the modified Marine one. Compile the iscript.bin again and add it to your MPQ. Since it has the same name, it should replace the old version we added earlier.


Figure 6-4: We can merge multiple text files into the same iscript.bin without problems.

One last thing before we check out our new Marine... let's have the attack spread out a little bit, so we can see the effects of what we've done. We'll do this by editing weapons.dat and changing the Gauss Rifle's behavior to "Attack Target 3x3 Area," the same effect the Valkyrie uses.

Alright, add weapons.dat and iscript.bin to our MPQ and let's check out the new effect ingame!


Figure 6-5: Now THAT'S an attack!


Alright, we've completed the basic iscripting tutorial! Hopefully you've gained a bit more understanding about the mysterious workings of iscript.bin... next up, we'll talk about flingy.dat and use it to change unit speeds.

Post has been edited 1 time(s), last time on Aug 26 2008, 4:24 pm by Debardus.

Section VII: Flingy.dat
...in which our protagonists travel at unsafe speeds

When you were in the Marine's iscript in the previous chapter, did you happen to notice its walking animation? If you did, you might have noticed a couple lines like this:

move 4
wait 1
playfram 0x55 # frame set 5
move 4

We already know about wait and playfram, and move seems pretty self-explanatory. Each "move" command moves the Marine 4 units. Now let's take a look at the Wraith's iscript.
Hmm. The Wraith's iscript doesn't say anything about the move command. So how does it move?

The answer is that the Wraith, along with most air units, has its speed controlled by flingy.dat. Let's open DatEdit and check it out.


Figure 7-1: The Wraith's flingy.dat entry.

What do these numbers mean? DatEdit has an explanation for them, but I'll go over them quickly here.

Sprite File: The Sprites.dat entry that corresponds to this flingy. Allows you to easily find corresponding entries.
Top Speed: This is measured in pixels/tick * (320/3). A tick, if you recall, is 1/10th of a second. It's generally more helpful to think of the speed of a unit you want to emulate and look at its Top Speed rather than try and calculate the pixels/frame. Larger numbers are obviously faster.
Acceleration: Added/subtracted from the speed until it reaches the Top Speed or 0. How fast the unit speeds up/slows down.
Halt Distance: How far from the target location the unit begins to decelerate. Measured in pixels * 256.
Turn Radius: Determines how the unit turns. Smaller numbers cause a unit to "skid" and make more sweeping turns.
Move Control: Determines what controls a unit's movement. Flingy.dat control causes a unit to use the Flingy.dat settings. Iscript.bin control will cause a unit to use the iscript.bin animation. "Partially Mobile, Weapon" is used for weapons but is not really understood. It's not recommended you change this.


There isn't much to really do in flingy.dat, so all we're going to do in this chapter is increase the Top Speed of the Wraith, as well as the Halt Distance and Acceleration to match. Let's also decrease the Turn Radius to something like 10, so it makes some nice banking turns.

Add flingy.dat to your MPQ and observe the Wraith's new flight behavior. That's it for this chapter! Next up, we're going to play with some more advanced iscript tricks, so keep reading!

Post has been edited 2 time(s), last time on Jan 11 2009, 9:29 pm by Voyager7456.

Range-based attacks, continous damage and adding new attack animations

Replacing portraits

.Got editing

Introduction to Grafting

Custom spells with Grafting

Introduction to AI Editing

Appendix I: Modding Resources

Appendix II: Glossary

Appendix III: Troubleshooting

Appendix IV: Balancing tips

Appendix V: Converting Old Mods

Well. It's not all there, but at least what's there is updated to modern tools. A big thanks to Voy for writing this stuff.