THE ISCRIPT.BIN
NOTE: While this article may still be useful for conceptual understanding and manual hacking, it is suggested that you just use the newly developed program by KramerBoy, ICE or BeHold's Script Creator to edit the iscript more easily. You should also see the SCEB for a reference and a more clear discussion of this topic. Some of the minor statements made in this article may be wrong or misleading and have since been updated.
SPEC SHEETS
- Images.dat entry list
- Iscript main entry format and opcode list
This is just basically a very quick tutorial on how to edit the iscript.bin file (animation properties of sprites). It's intent is to be succinct, so either you'll get it or you won't. Sorry, it just is that way.
INTRODUCTION
The iscript.bin file is what determines the animation properties of all the "sprites" in Starcraft. It is important that you understand the difference between a sprite and a unit. A sprite is just the graphic that a unit uses. Note that a sprite is not just a GRP file. A GRP file is just a list of frames. A sprite makes use of those frames by applying certain orders of play back in addition to things such as when to play overlay graphics and sounds. Sprites include unit graphics, overlays, shadows, doodads, and more.
Another file you should be familiar with is the images.dat. I'll save the details for another article, but basically, the images.dat is a list of all the sprites in Starcraft (all 999 of them). Each sprite entry gives certain properties to the sprite, such as how it turns, what palette its graphic uses, and, as for the purpose of this article, which animation scripts it will use (pointer to an iscript entry).
The iscript entry it points to is actually a list of more pointers to each specific animation that sprite utilizes (intial animation to play, the attack animations, spell casting, etc.). The specific animations are "scripts" or simple lists of opcode commands and variables. They work very much the same way as an AI script would work.
EDITING
Here's how to get to a certain animation script for a certain sprite:
1) To find a sprite's iscript entry: First, find the sprite you want. Each sprite has an entry in the images.dat. You can find a almost compete list of most the sprites here. Second, look at the Unknown 8. Write down the value. Open up the iscript.bin and search bottom-up for that value (in hex, unsigned short, intel). [Be sure to extract the iscript from the patch_rt.mpq file, not the Broodat.mpq or Stardat.mpq]
At the bottom of the iscript is a listing of all the Unknown 8's paired with the offset of their main animation entries. I.E. XXXX YYYY, where XXXX is your Unknown 8 and YYYY is the iscript entry offset. So you'll find an offset (unsigned short, intel) directly following your Unknown 8 variable. Write down the offset.
Actually, KramerBoy of Camelot Systems made a quick program to find the offet of a sprite for you (all you need to know is its GRP). You can download it here. Do NOT mail him questions about how to use it. You can mail me and I'll try to help. "Alpha Shadow" means it uses the shadow iscript entry which is at 7A06.
2) Goto the main offset. At the main offset you'll find something like this:
5343 5045 XX 00 00000 YYYY ZZZZ AAAA .... etc.
where XX is a "type" variable (different types determine how many specific animation a sprite has; you shouldn't have to worry about it too much) and YYYY, ZZZZ, AAAA, etc. are more offsets to other areas (usually around the same area). These offets are actually pointers to each specific animation. To determine which pointer corresponds to which animation, see this. 5343 5045 (or SCPE in ASCII) is just a identifier. It doesn't do anything besides start the entry. The 00 00 00 is just a spacer.
3) Decide which animation you want to look at/edit/etc. For most normal sprites, the main entry will have 14 different offsets listed (the YYYY, ZZZZ, AAAA, etc. part). Each offset points to some location where the animation code is actually located. Go to one of those (NOTE: 0000 means it doesn't have this animation; 79BA is an offset that has code which does nothing and loops itself -- you'll find these commonly). Don't be suprised if the offset does point to some place far off like near the bottom of the iscript. Many sprites share animation scripts, such as all flying units using the same idle "floating"-like animation.
4) Once you actually get to the animation code, you get to make use of the opcodes. An opcode is a command identifier followed by an exact number of variables or parameters. I.E., the "play frame" opcode identifer is 00 and is followed by a single unsigned short as a variable parameter (in other words, 00 XXXX). Example:
05 01 00 11 00 08 23 00 07 BA 79
The opcode commands are bolded. Each opcode command is followed by its corresponding variable(s). You can find a list of opcodes here. This particular example is pretty simple:
- Wait: 1
- Play frame from frame set: 00 11
- Play sound: 0023
- Goto offset: 79BA
For additional information on how frame set variables are formatted, go here. The other variables are pretty self-evident. The sound number is an entry in sfx.dat and teh goto is another offset.
... and then the animation continues from that offset.
THEORY
This is how animations are called, and basically work:
1) An order is given to the unit (like walk, attack, cast spell, etc.). This is done either by the player (i.e., move) or internally by Starcraft's auto AI (i.e., die, move to location to begin attack, idle)
2) The current animation running for the sprite stops in mid-script (unless it is in an "unbreakable" opcode routine -- in which case it will wait until the unbreakable section is finished).
3) The unit turns to the direction of its target (if it has one). I think flingy.dat controls the turning rate. I think it also, by default, goes to the "return from walking to idle" animation for a second here (not really noticable though).
4) Then it begins the animation associated with the order it got.
It will continue with that animation simply following the code along and follow all the "goto" commands it comes to. Usually, one of the gotos will eventually loop the script. And it will continue with this until it gets another order.
A couple notes. Opcode 16 will end the animation completely and remove the sprite. When a unit is spawned, it automatically begins its "Intitial animation," which, among other things, usually spawns the shadow sprite for the unit.
To make a completely new animation for a unit:
This is what I do for testing opcodes, and what you'll probably want to do so you can make
entirely new animations without restrictions. It's really easy. Goto the main offset of
the sprite. Now, make the animation you want to make from scratch point to the end of the
iscript file (9E22). Then, just start inserting your opcodes at the end of the iscript and
you don't have to worry about messing up all the other stuff. Be sure to end it with a
goto or 16 (to end the anim) if its a death animation.
That's basically it. As I said, most people probably won't understand this article, but I feel it is more important to do research now instead of teaching so that eventually Camelot Systems' program will easily allow all users to make full use of the iscript's power. This was a crash course and is probably a lot more than anyone can really handle. But if you read it over a couple times and experiment with it yourself, it will all make sense in the end.
DI (aka MAGNUS99)
July 25, 1999
The 00 or "play frame" opcode is not a simple "pick this frame # from the GRP" because it must account for the animation running in all directions which the sprite faces. Here's the theory so far.
All frame variables are like this:
XY 0Z
I guess the 0 could be different, but you'd have to have an awfully large grp to get up to that many frames. =)
Z is either 0 or 1 (but I'm gussing it could be higher). If it's 1, it means the frame set to use is 16 + whatever X is. (so 44 01 would be the 20th frameset)
CASE 1
X=Y for all the frames in this particular animation. (44 00, 55 00, 11 00, 00 00, etc.) This means use the frame in set X that corresponds to the direction the unit is currently facing.
CASE 2
Y=A, where A is equal to any number between X-1 and F (15 dec).
X-1 <= Y <= F
This means use a specific frame in frameset X. Y determines the specific frame. Y=X-1 would be the first frame. X would be the second. X+1 would be the third. X+2, the forth. X+3 the fifth. Etc. I'm not really sure how it would deal with X=F or something like that. But this seems to be the case.
I've made other combinations work, but I can't make heads or tails of what they do. I'm just sure of the second byte determining how many 16's to add to the frameset number and the first digit of the first byte determining the frameset to use.
