Reference: ICE written by DI

Reference: ICE written by DI

Of all the file utilities discussed so far ICE is probably the most powerful (this is excluding the Stardraft and Stargraft patch loaders of course, since without them none of this would be possible :). While ICE is designed to be user friendly (much, much more user friendly than if you had to edit the iscript.bin manually, which, believe it or not, is what a lot of people did until now), it is still critical to understand the basic structure of the iscript.bin before learning how to use it. It will make it a lot easier to understand, and help you diagnose bugs (with your scripts and with ICE itself). With that said, I will reluctantly tell you that you probably won't have to worry about much of the pointers (goto line XXX, etc.) that were ranted about in the last section. Pointers are still important and will still cause many crashes if they aren't handled right, but ICE tries to handle them for you. For example, you normally can't just insert an opcode in the middle of some animation routine because it will throw off every pointer that is below it. However, in ICE you normally can just insert (add) an opcode in the middle of a script. This is because when you do this, ICE will automatically move the script you are editing to the end of the iscript, and adjust the appropriate script pointer in the header to match.

File Menu

Open File - This will let you open an iscript.bin file for editing.

Load Default - This will load the default iscript.bin from the MPQ for editing (it will not edit the iscript.bin that is in the MPQ specifically, it will just extract it and you can edit it as a new file).

Load from CWAD - This will load the iscript.bin from inside a specific CWAD file. Note that it must be in scripts\iscript.bin in your CWAD.

Save File - Self explanatory.

Save File As - Self explanatory.

Save File to CWAD - This will import the current iscript.bin file into a specific CWAD with the path scripts\iscript.bin (the appropriate one for use by SC). This will save you the trouble of opening up the CWAD Manager all the time.

Create CWAD from File - This will create a new CWAD with your iscript.bin inside (with the path scripts\iscript.bin).

Main Headers

This tab on top will allow you to select which animation header you want to edit (or create a new one or delete one). Recall that an animation header is the set of line offsets which determine which individual animation for that animation set is located. ICE gives "names" for the headers indicating which sprite the header was originally associated with. Don't let the names confuse you though; they really don't mean a thing. (You can associate any animation header with any images.dat sprite)

The drop-down menu will allow you to select one of the current headers, and thus load the header's data (pointers and animation routines into the editing tabs on the bottom).

Create New Header - This will allow you to add a new header (set of animation routines) to the iscript.bin.

Script Name: This will make ICE associate a name with this animation header. Its just for helping you remember what this header is for. It doesn't effect anything.

Offset: This will tell ICE where to put this animation header in the iscript.bin ("line," or offset). By default ICE will add the header to the end so it won't mess up any pointers. YOU SHOULD ONLY PLACE THE HEADER IN ANOTHER LOCATION IF YOU KNOW WHAT YOU'RE DOING.

ID Tag: This is the Iscript ID number that is associated with this set of animations. For example, if you want a certain images.dat entry to associate with this animation routine, you would make this ID Tag and the Iscript ID variable in the images.dat the same number. If the ID number you choose is already associated with an images.dat entry (in the original images.dat in the MPQ), then ICE will allow you to "Preview" the GRP file which is associated with that images.dat entry.

Type: Each set of animations in the iscript is of a certain "type." The type of header determines how many different animations there are in the set. Most "normal" terran and protoss man sprite (non-building) have type 12 or 13. Most zerg man sprites have type 26 (extra animations routine needed for burrowing). Most buildings have 20 (zerg) or 26 or 27 (terran, protoss; need more animation for lift off and "building is working" animations). Most "overlay" type sprites (sprites that aren't used for units but just played in conjunction on top of or below to other sprites have type 0 or 1 (they only need an initial initial and death animations). If you're not sure what type to use, just go with the largest number of animations. Which animation is which doesn't change between types (e.g., the initial animation will always be the first animation listed in type 0, 13, or 27), but you don't always need all of them.

Delete Header - Self explanatory.

Rename Header - Self explanatory.

GRP Preview and WAV Preview

These are peripheral tabs that are designed to help you edit the iscript by allowing you to preview unit graphics and sounds, but have absolutely nothing to do with the actual iscript you are editing. In other words, you could ignore them if you wanted and there wouldn't be any difference, and messing with them doesn't effect your iscript. The GRP Preview tab will allow you to preview the GRP which is originally associated with this animation set (in the Main GRP window). How it does this is ICE looks up what original images.dat entry is currently associated with this animation header's ID tag and then looks up what GRP is associated with that images.dat entry. Keep in mind that no GRP is actually directly associated with the animation set, it is only indirectly connected by association with the images.dat entry which contains a pointer to this iscript routine. The Secondary GRP window allows you to preview another GRP (associated with a certain images.dat entry, or a certain sprites.dat entry -- which is really just a sprites.dat entry pointing to an images.dat entry which then points to a GRP). The purpose of this is to allow you to preview overlay or underlay graphics that are played by the iscript on the current main sprite. This is done by double clicking on certain opcodes which will be explained further later. The buttons between the two windows allow you to choose a specific GRP to preview in the Secondary GRP window. You just enter the number of the images.dat or sprites.dat entry, check the appropriate radio button, and click preview. ICE will show the GRP originally associated with that entry.

The WAV Preview is similar. While there are no "default" sounds associated with sprites, iscript animation routines are allowed to play sounds (i.e., the clash of psi blades when the zealot sprite attacks). When you double click on certain opcodes which play sounds (by association with an sound entry in sfxdata.dat), ICE will put the associated sound in this window. You can double click on it or press "Play WAV" to preview the actual sound. You can add more WAVs to the preview list by inputing an entry number from sfxdata.dat (the sounds data file, each entry points to a certain sound, listed in sfxdata.tbl -- we'll get to this later, but its not that complicated). ICE will add the associated wav file to the list for previewing. Similarly you can remove wavs from this list with the "Remove WAV" button.

Reference: ICE Part II

Now that we've learned how to navigate around the basics of ICE, its time to start modifying some headers and actual animation routines. First, you need to select or create a new header to edit.

Header Info

There's not much to edit here. This is just basic info that associates the header with an ID number (so images.dat can use it).

ID Tag: This is the Iscript ID tag associated with this header. If you didn't read the description I gave with the "Create New Header" section, here it is again: This is the Iscript ID number that is associated with this set of animations. For example, if you want a certain images.dat entry to associate with this animation routine, you would make this ID Tag and the Iscript ID variable in the images.dat the same number.

Offset: This determines the line offset where the header is actually located in the iscript (the header is the list of pointers to the actual animation routines). You should not mess with it unless you know what you're doing.

Entry Header

This is the actual header of the animation set. If you recall, the header is basically a list of pointers to the location of each individual animation routine in this set. In general, I advise against editing any of these pointers unless you are very sure of what you are doing. The reason you don't have to edit locations to routines manually through this section is because ICE will do it automatically for you when you create/modify the actual animation routines (next section). You don't want to accidentally make a pointer to the middle of nowhere (that will crash SC :), so its best to let ICE handle it.

You can change the "Type" of header this is. If you didn't read the description of set types before, here it is again: The type of header determines how many different animations there are in the set. Most "normal" terran and protoss man sprite (non-building) have type 12 or 13. Most zerg man sprites have type 26 (extra animations routine needed for burrowing). Most buildings have 20 (zerg) or 26 or 27 (terran, protoss; need more animation for lift off and "building is working" animations). Most "overlay" type sprites (sprites that aren't used for units but just played in conjunction on top of or below to other sprites have type 0 or 1 (they only need an initial initial and death animations). If you're not sure what type to use, just go with the largest number of animations. Which animation is which doesn't change between types (e.g., the initial animation will always be the first animation listed in type 0, 13, or 27), but you don't always need all of them.

Animation Scripts

Here's where the heart of the iscript lies. Each entry in the drop-down menu will bring you to the actual opcodes of an animation routine, and allow you to edit that animation (for the current header set).

Animation [drop-down menu]: Select the animation routine of this set that you wish to edit. The opcodes will appear in the black box below. Here is a brief description of what each animation is for:

Initial animation - This is the animation that plays when the sprite is spawned or created. Normally, this animation also spawns any active overlay/underlay graphics for the main sprite (e.g., a shadow sprite or a turret). Also, in many cases, the code for this animation contains the code for the normal "idle animation" of the sprite (if it's a unit). This is because right after a unit is spawned, it goes into its idle state. However, do not mistake this entire animation for the idle stance, because it is not. What usually happens is that at the end of this routine, there will be a goto opcode that points to a line in the middle of this routine (the beginning part will usually spawn a shadow, so it will simply loop back to the part after the opcode which spawned the shadow, since it doesn't need to do that more than once).

Death Animation - This is the animation that is played when the sprite is destroyed (e.g., when the unit using this sprite is killed). Usually this will end with a "End animation, remove graphic" opcode, signaling that the sprite should be removed (otherwise it will linger on the battle field forever, though just as a graphic).

Initial Ground Attack Animation - This is the animation to play for this sprite when the unit it is associated with begins to attack a ground unit.

Initial Air Attack Animation - This is the animation to play for this sprite when the unit it is associated with begins to attack an air unit.

Special Ability Animation 1? - Unknown.

Repeated Ground Attack Animation - This is the animation that plays for a sprite when it continues to attack a ground unit. (I.E., when it begins to attack it will play the initial attack animation, but if the target is not dead yet, then it will continue attacking with this animation)

Repeated Air Attack Animation - This is the animation that plays for a sprite when it continues to attack an air unit. (I.E., when it begins to attack it will play the initial attack animation, but if the target is not dead yet, then it will continue attacking with this animation)

Special Ability Animation 2? - This is the normal "cast spell" animation. E.G., the one to play when a High Templar casts Psi Storm or a Ghost casts Lock Down. Some spells do not require an animation and some "special" spells use a different one (but most use this one).

Return to Idle from Ground Attack - This is the animation that plays when a sprite is finished attacking its ground target (usually just a pointer back to the middle of the initial animation, where the idle stance starts).

Return to Idle from Air Attack - This is the animation that plays when a sprite is finished attacking its air target (usually just a pointer back to the middle of the initial animation, where the idle stance starts).

Special Ability Animation 3? - Unknown.

Walking Animation - This is the animation to play when the unit this sprite is associated with moves from one point to another. Note that if you have the flingy.dat Move Control setting set to Flingy Control (as opposed to iscript control) then any "move graphic XX units forward" opcodes in this animation will be ignored, though the rest of this animation will still play as the unit moves (but speed will be controlled by flingy.dat). If you have the Move Control set to iscript control then it will ignore speed settings in flingy.dat and use the "move graphic XX units forward" opcodes in this animation.

Return to Idle from Walking - This is the animation that plays when a sprite is finished walking (flying, gliding, or whatever) to its destination (usually just a pointer back to the middle of the initial animation, where the idle stance starts).

Other Animation? or Generic Animation? - Sort of Unknown. This is usually the "special" animation that is associated with very specific unit actions (it varies depending on what unit this sprite is associated with). For example, this is used for "suicide" attacks (like for the infested terran and scourge sprites).

The remaining animation routines are kind of unknown, but here's what I've picked up about some of them:

Unknown 1 - Is burrowed/in "other" state animation. (e.g., initialize burrowed units' animations if placed as burrowed in staredit since they never got to start burrowing in the first place)

Unknown 2 - Construction Animation (buildings, during construction); Mining Animation (Peons, when harvesting minerals).

Unknown 3 - "Building is working" (training unit, researching upgrade, etc.) Animation.

Unknown 4 - Landing Animation (for terran intransit buildings).

Unknown 5 - Lift off Animation (for terran intransit buildings).

Unknown 12 - Burrowing Animation.

Unknown 13 - Unburrowing Animation.

(Note that this tutorial may be older than the current version of ICE and some of these Unknowns may already be labeled, or shifted around)

Animation Opcodes [the black box =]: When you select an animation routine to edit, its opcodes will show up in this box. Recall that an animation routine is just a list of commands or "opcodes" that tell a sprite what to do (what frames to play, when to play a sound, when to wait, etc.).

You MUST end all animation routines with either a "Go to Offset XXXX" opcode or a "End animation, remove graphic" opcode (the latter usually only for death animations, but can be used elsewhere). ICE will warn you if you try to mess up otherwise. Some routines will say "No Animation Data" meaning there is no routine there yet. You can create a routine there by adding new opcodes using the commands at the bottom.

The trickiest part about writing animation routines has to be getting the "Go to Offset XXXX" pointing to the correct locations. Since the XXXX is just an offset number with no other indication of where it relates, it can be pretty confusing. Usually, you want this to lead to some other location in the current header set (e.g., after an attack animation, you probably want it to loop back to the begging so it can attack again, or after the initial animation animation finishes, you probably want it to loop back to the start of the "idle" stance part). The easiest way to do this is to go to the actual opcode you want it to loop to first (find it in the animation routines and select that line). ICE will display the offset to that opcode in the lower right hand corner as "Op Offset." Remember that number and then go back to your original Go to Offset opcode you were editing and paste that number there. If you're unsure of where to go to, a normally safe bet (if you are using the original iscript) is to go to offset 31162. At that location is a script that does nothing but loops itself, so you're sprite will just halt.

To change the values of an opcode (the numbers), just highlight them (they should turn green). Drag your cursor over them and input your new value and press enter. Here's a brief description of what all the buttons on the bottom do:

New - Insert a new opcode on top of the currently selected one. It will bring up a list of opcodes to choose from. Remember that you don't have to worry about throwing off pointers by inserting opcodes in ICE because when you add an opcode, ICE will automatically move your script to the end of the iscript file. (You can verify this by looking at the Script Offset number in the bottom right hand corner and see that it changes when you add an opcode)

Delete - Delete the currently selected opcode.

Copy - Copy the currently selected opcode.

Cut - "Cut out" the currently selected opcode. (Same as Copy and then Delete)

Paste - Paste the opcode last copied or cut on top of the currently selected one.

Hex - View a hex dump of the current animation routine. Ignore this unless you're researching opcodes like me. :)

Up - Move the currently selected opcode up.

Down - Move the currently selected opcode down.

Jump - If the currently selected opcode is a "Go to Offset XXXX" opcode, then jump to offset XXXX (and display those opcodes in the black box for editing).

Back - Move back to an animation routine if you jumped to XXXX (with the previous option). You can jump and go back multiple steps.

Goto Offset - Goto an arbitrary offset you specify and display the opcodes at that location for editing. Usually only useful if you know where a certain animation routine starts so you can enter it. (You don't want to go to the middle of no where)

And that's basically it. Now you know how to edit animation routines. Though you're probably still wondering specifically what some of those opcodes do. :) Here's some brief descriptions and examples: Iscript Opcodes.

Now wasn't that fun? We're almost done with all the animation stuff. One more section to go