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.
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.
I sleep in late
Oh what a wonder
Oh what a waste.
It's a Monday
It's so mundane
What exciting things
Will happen today?