星际mod工具iceccmanualIceCC Manual
47
IceCC: User Manual
Version: 1.2b (Updated: 2002/06/08)
by Jeff Pang
website: http://magnus99.dhs.org
Table of Contents:
I. Introduction
2
II. Installation
4
III. Iscript.bin Refresher
5
IV. Graphical User Interface
7
V. Command Line...
IceCC Manual
47
IceCC: User Manual
Version: 1.2b (Updated: 2002/06/08)
by Jeff Pang
website: http://magnus99.dhs.org
Table of Contents:
I. Introduction
2
II. Installation
4
III. Iscript.bin Refresher
5
IV. Graphical User Interface
7
V. Command Line Interface
9
VI. Script Files
13
VII. Example
17
VIII. Appendix A: Animation Types
20
IX. Appendix B: Instruction List
23
X. Appendix C: Script File Specification
29
XI. Appendix D: Other Useful Programs
31
XII. Appendix E: Program Configuration
32
XIII. Appendix F: DAT Entry Lists
33
Introduction
What is IceCC?
IceCC is a pair of programs, icedc and icecc, that decompile and compile the Starcraft iscript.bin (image animation script) file. It it used to create your own animations for Starcraft in-game graphics such as unit sprites.
Should I be using IceCC?
If you are new to Starcraft customization and 'mod making' then IceCC is probably not the best place to start. This manual assumes the reader is familiar with tools such as Stardraft and/or MPQ 2000 (or some other mpq editing tool). A good place to find other Starcraft editing is Camelot Systems (http://www.camsys.org); I've also written a beginner's tutorial on Starcraft editing called the 'Starcraft Editing Bible' which you can download (in HTML format) on my website (http://magnus99.dhs.org/downloads/). It is the zip file called 'sceb-*.zip' where * is the last date it was updated.
What's new in version 1.1?
No new functionality was added. But, I spent a day and a half learning Java Swing and wrote a graphical user interface for IceCC called IceCCUI. Windows users who like point and click rejoice! :) See the new section called Graphical User Interface for more information.
How is IceCC different than ICE?
ICE, the iscript editing tool by KramerBoy (Camelot Systems), is a graphical program and edits the iscript.bin file directly. It has several advantages over IceCC; for example, it allows you to preview GRP images (Starcraft bitmap collections) and WAV sounds associated with some animations. It also has a graphical user interface and hence may be more familiar to most Windows users. However, it does have some pitfalls; some of its instruction information is wrong and it can be hard to navigate when a user wants to add new animations. IceCC is meant to rectify these flaws in as simple a manner as possible. IceCC allows you to 'extract' animations from the iscript.bin binary file to a human readable text file for editing. Animation and instruction information is up to date and complete so it functions without errors. After editing the text scripts, IceCC can 'compile' them back into an iscript.bin file seamlessly. But most importantly, IceCC runs on Mac OS X as well. :)
How can I help?
The most important thing that is still unfinished right now is the list of iscript instructions. Most of them have been identified already and all of their formats have been identified completely, but I'm still not sure what all of them do. If you could experiment with some of the unknown instructions (and seeing how they are used by animations in the default iscript.bin file) and try to figure out what they do, that would help others who might want to use them. See Appendix B for a list of instructions.
Legal Stuff.
IceCC. The Starcraft Iscript Compiler/Decompiler
Copyright (C) 2000-2002 Jeff Pang
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Installation
If you're reading this manual, there is a good chance that you've already got IceCC installed.
Windows:
IceCC should have been distributed to you in a zip file named something like 'icecc-*-win32.zip' where * is the version number. Simply unzip all the files to C:\. This will create a directory called C:\IceCC where the program files will be installed. If you wish to install IceCC elsewhere, you can do so, but you will have to edit the icecc.ini file in the IceCC directory to reflect where you performed the installation (change where is says INSTALLDIR=C:\IceCC to INSTALLDIR=[install path here]).
To run the graphical version of IceCC (IceCCUI), you will need a Java Runtime Environment version 1.2 or greater. You can get it from Sun here: http://java.sun.com/j2se/1.3/jre/download-windows.html. Make sure that the 'java' family of programs was added to your PATH (which is automatically done by the Sun installer, but may not have worked if your computer crashed during installation or something weird). This is almost surely the problem if you are having problems running IceCCUI.
To run IceCCUI (the graphical version of IceCC), just double click on the IceCCUI.BAT file in the installation directory. If you have file extentions turned off, then it will just be called IceCCUI and have a little yellow gear icon inside a little window.
To run icecc or icedc, you will first have to open an MS-DOS prompt and change your working directory to C:\IceCC (or where you performed the installation) by using the 'cd' command. If you wish to be able to run icecc and icedc from any directory, you will have to open a file called C:\AUTOEXEC.BAT in a text editor and find find the line that starts with 'SET PATH=...' where ... looks like a list of directory names separated by semi-colons (;). At the end of that line, add ';C:\IceCC' (a semi-colon followed by the installation directory). Then restart Windows and you should be all set.
Mac OS X:
IceCC should be been distributed to you in a tar.gz file named something like icecc-*-macosx.tar.gz where * is the version number. Double click this to expand it and drag the resulting directory (Ice CC) to your Hard Drive somewhere.
To run the program, double click on the IceCC icon in the folder (Dark Templar).
To run the command line versions, you can open up a terminal, enter the Ice CC directory and call ./icecc and ./icedc for the compiler and decompiler respectively. If you know a little about UNIX, then you can add the directory to your PATH, etc. since they are regular UNIX binaries.
Iscript.bin Refresher
To use IceCC, or any iscript.bin program, you will need to know a little bit about the iscript.bin file. It is the file that controls the animation of graphics in Starcraft, or how the units in the game 'move.' For example, it determines how a typical marine would walk, how a battle cruiser flies, and the way a hydralisk flexes its gills when it is idle.
There is a unique distinction between a 'unit' in starcraft and a 'graphic' or 'sprite.' A unit is the physical 'thing' that is selectable and controllable in the game, while a sprite is just how it looks on the screen. Any unit can practically change its graphic at will (with some editing of the DAT files) without affecting its other properties. For a more detailed explanation, you should see my 'Starcraft Editing Bible.'
Let's fast forward a head a bit and talk about DAT files. DAT files are the main configuration files which control various features about the way Starcraft behave. There are 4 DAT files which we are concerned with: units.dat, flingy.dat, sprites.dat, and images.dat. Units.dat controls unit properties and includes a variable which determines which graphic it uses. This variable is really just a 'pointer' to a flingy.dat entry, which is a list of movable sprites (units, projectiles, etc.). Flingy.dat contains a pointer to a sprites.dat entry, which is a larger list of sprites (including all the unit and projectile graphics in addition to things like doodads and terrain graphics). Sprites.dat in turn has a pointer to an images.dat entry, which is the most 'raw' graphic description of them all. Images.dat contains almost 1000 different graphic descriptions. There are so many because these include things like the 'engine glow' that the afterburners of a Valkyrie make or the ruins that are left on the ground when a Terran building is razed. Every images.dat entry has a pointer to a GRP file; this file contains the actual set of bitmap images or 'frames' that the graphic will use. The images.dat entry also contains a pointer to an 'Iscript ID', which, as you might have guessed, determines which set of animations it uses. This is where IceCC takes over; it allows you to edit, or even generate completely new animation sets. For a in depth explanation see my 'Starcraft Editing Bible.'
You don't really have to know about all the connections between the DAT files to use IceCC, because it will allow you to extract animation sets from the iscript.bin based on units.dat entry (by following the pointers mentioned above), but they are good things to keep in mind just so that you understand how it all works. Each iscript animation set is composed of several 'animation scripts.' I will refer to the animation set itself has an iscript 'header' because it is like a header which determines what animations are actually used. A header looks something like this:
IsId
10
# this is the iscript id of this animation set; it is
# referenced by images.dat, each set has a unique id
Type
0
# this is the type of set; there are 28 different
# types, each with a different number of animations
Init
BloodInit
# this is one of the animations in this
# set.
Death
BloodDeath
# this is another animation in the set
This example shows the animation set which has an iscript ID of 10. It is of type 0 which means it has two animations, Init (the initialization animation) and Death (the death animation). See Appendix A for a info on all the set types. The 'label' after each of these animation tags is the name of the actual animation scripts that will be used. These scripts are a series of instructions which determine what the animation does (i.e., what order to play the image frames, when to turn the graphic, when to play sounds, etc.). An animation script might look like this:
BloodInit:
playfram
1
wait
2
playfram
2
wait
2
playfram
3
wait
2
playfram
4
wait
2
goto
BloodInit
This simple script, which is the script pointed to by the Init animation of the above iscript header, tells Starcraft to play the sprite's frames 1 through 4, waiting 2 ticks between each (this gives you a sense of fluid motion). Then the script says 'goto BloodInit' which just means, loop back to the top (loops are very common in the iscript, because, unless you want your graphic to disappear right away, loops allow for the animation to play continuously without writing a long script).
And that's all the iscript is: a collection of headers (sets of animations) and a listing of scripts. Of course, most headers have more than two animation scripts. For 'regular' unit graphics, for example, like the Marine's header, there will be scripts for the initial animation, the death animation, the walking animation, the attacking animation, etc. These will be explained further in depth later (and fully in Appendix A). Again, for further information, you can see the 'Starcraft Editing Bible.'
Graphical User Interface
Version 1.1 added a new graphical user interface written in Java Swing. You will need a Java Runtime Environment (version 1.2 or greater) to run it (see the Installation section). The graphical interface mimics the command line interface, so if you're already familiar with the later then you can probably figure out the former for yourself.
To get started, double click the IceCCUI.BAT file in the IceCC installation directory. (You can create a shortcut to this if you want) This should bring up IceCCUI ("Iscript Code Compiler User Interface"). There are two tabs, one for decompiling iscript.bin files and one for compiling script files back into binary iscript.bin files starcraft can use.
Decompiler Tab
The decompiler tab has 4 main menus and several options at the bottom. Use the menus to select which iscript.bin entries you want to decompile to a script file. Each list refers to a DAT file that you can reference entries from. (e.g., if you select "0 Scourge" out of the Images list then you will get the images.dat scourge entry's iscript animation set; if you select "0 TerranMarine" from the Units list then you will get the animation set that is associated with the Terran Marine) Why all these lists? Because not all the animation sets can be traced back to a units.dat entry, so the Units list is too short, but in many circumstances, you do not know the exact images.dat entry which corresponds to the iscript animation set you want, but you know the Units entry, or flingy entry, so these lists are convenient. Click on an entry to select it/deselect it. You can use ranges by holding down shift.
Below the lists is a text field where you can enter iscript ID numbers of animation sets explicitly. E.G., if you know you want exactly the animation sets with iscript ID 0, 10, and 54, then you'd enter "0,10,54" in the text field. Entries are separated by spaces, commas, or semi colons. If you do not select any iscript IDs explicitly and you don't choose any items from any of the lists, it is assumed you want to decompile all the entries in the iscript file.
The option 'Use default iscript.bin' will make the decompiler decompile entries from the default iscript.bin that is in Starcraft Broodwar 1.07. If you uncheck the option, then you can select your own iscript.bin file to decompile in the 'Open' field. The 'Separate Headers' option makes sure that no two animation sets share any animation routines. This will make more sense later when you read the script file examples.
The 'Save To' field allows you to choose where you want to save the generated script file to. If you leave it blank, it will be saved to 'iscript.txt' in the current directory. The 'Open in Editor' button allows you to quickly open this file in a text editor (see Preferences to choose your favorite text editor).
When you've set up all the options, then you can click 'Decompile' and the decompiler will create your script file. If nothing happens when you click it, that means it worked. If you get error dialogs, that means it didn't. :) Read the error messages and see if you can fix whatever the problems are.
Compiler Tab
The compiler tab allows you to compile your script files back into a usable iscript.bin file. Use the 'Add' and 'Remove' buttons to manage the source script files you want to compile. The files closer to the bottom of the list have HIGHER precedence than the ones near the top; this means that if two of them have the same iscript ID in them (e.g., they conflict), then the one in the file closer to the bottom will be used and the one in the file closer to the top thrown out. You can adjust the positions with the 'Up' and 'Down' buttons. You ca also use the 'Open' button to quickly open a selected file in a text editor for viewing.
The 'Merge with default iscript.bin' option means that all your scripts will be merged with the full iscript.bin. This is probably what you want, since it will just add your modified entry back into the original iscript file. The 'Display all warnings' option will make the compiler display all the warnings and errors it encounters trying to compile your scripts. If unchecked, only the first 10 errors/warnings will be displayed.
The 'Save to' field allows you to choose the name of the iscript.bin file that will result from the compilation. If you leave it blank, it will be 'iscript.bin' in the current directory.
Click compile when you have everything set up. Again, nothing happening means it worked, otherwise the compiler will give you an error dialog. If the dialog has a bunch of syntax errors in the message, you can click on an error and choose to open that file in a text editor for quick viewing.
File->Preferences
The preferences dialog has a few settings you can change. The 'icecc Executable' and 'icedc Executable' options determine where IceCCUI will find the command line IceCC programs. The 'Config File' and 'Config Dir' options set where to find the configuration files IceCC needs. See the last section of this manual for more info. The 'Text Editor' option allows you to specify which text editor program (or any program really) you want to launch when 'Open' buttons are pressed, etc. This is something like 'notepad' or 'wordpad' or the full path to a text editor executable like 'C:\Program Files\MS Office\MSWord.EXE' or 'C:\Program Files\UltraEdit\uedit.exe'. Find out where your favorite text editor is installed.
These preferences are written to a text file called 'iceccui.ini' in the current directory. If you are getting error dialogs about preferences, then you might want to check that out.
This primer on the GUI is pretty short, and it will probably benefit you to read the Commandline section if you don't know what everything does yet, even if you're never going to use it. The GUI just reads in your options and runs the command line programs anyway (They're the guts, IceCCUI is just a pretty face on top :).
So now you've saved some script files for editing. Now what? See the 'Script Files' section for the details.
Command Line Interface
Icecc and icedc are command line programs. Instead of double-clicking on an icon to pop up a window, you will run them by entering commands in an MS-DOS prompt (which is called a 'shell' in CLI land). Here's how to get started:
1. Open an MS-DOS prompt. Normally, you can find this in the Start Menu->Programs->Accessories submenu.
2. Change the working directory to C:\IceCC or where you chose to install IceCC by typing 'cd C:\IceCC'. You don't have to do this if you set up your AUTOEXEC.BAT file to allow you to run IceCC in any directory. (See Installation)
3. Now you're set to enter commands.
If your command-line skills are a bit rusty, a good tutorial may be helpful. You can find one at the FreeDOS project here http://www.freedos.org/fd-doc/mini/tutor/menu.html.
Mac OS X users: If you are familiar with the command line, then I don't think I should have to explain the differences between the DOS instructions and the UNIX ones (hint: instead of the C:> prompt, you have a nicer tcsh one :). But do remember that Mac OS X file paths are not bastardized like Windows and use forward slashes "/" and not back slashes "\". There are many Terminal tutorials for OS X online, so they would be the best resources to consult to learn more about the UNIX layer in Mac OS X.
IceCC's command-line options are consistent with UNIX standards. Naturally, I don't expect you to be familiar with this standard, but if you are, you can skip this part. As an example, I'll use icedc, the iscript decompiler. To run the decompiler, at the prompt you would type:
C:\IceCC> icedc [options]
Where the is the name of the iscript file you wish to decompile and [options] is a list of optional "switches" you wish to give to the program. ( "C:\IceCC>" is the prompt of course, so you won't type that) Let's say you have the iscript.bin file in your "My Documents" directory. Do decompile it you would type:
C:\IceCC> icedc "C:\My Documents\iscript.bin"
In this case, you must put the file path in quotes because the "My Documents" directory has a space in its name. This command would decompile the iscript.bin file to the default output-file "iscript.txt" in the working directory. So you could open that file up (such as with the command "notepad C:\IceCC\iscript.txt"; though you probably want to use a better text editor than Notepad) and edit it.
This is really all you need, but generally you will never use the above command line. This is because, it will decompile the entire iscript.bin to iscript.txt, creating a text file with over 20,000 lines. If you want to explore the original iscript animation sets, this may be useful, but in general, you will only want to deal with a few sets at a time. To facilitate this, icedc allows you to extract animation sets by their corresponding iscript ID (which you can find out from images.dat). For example, let's say I only want to extract the sets with ID 0 and 2:
C:\IceCC> icedc -i 0,2 "C:\My Documents\iscript.bin"
The "-i" is known as an option or a switch, all of which begin with a "-" and consist of a single letter. In particular, this option followed by a comma-separated list of numbers tells icedc to only extract the sets from the iscript.bin file which have the Ids 0 and 2 (these are the Scourge and Scourge Death animation sets respectively). What if you don't know the iscript ID of the animation set you want to extract? Icedc will allow you to extract them via images.dat entry number also:
C:\IceCC> icedc -m 0 "C:\My Documents\iscript.bin"
This will extract the iscript ID associated with images.dat entry number 0 (which just happens to be the scourge also. If you don't know the images.dat number, you can extract by sprites.dat entry number, or flingy.dat entry number, or even units.dat entry number. Here are the corresponding switches, each of which should be followed a comma-separated list of entry numbers you wish to extract:
-i
iscript ID numbers
-m
images.dat entry numbers
-p
sprites.dat entry numbers
-f
flingy.dat entry numbers
-u
units.dat entry numbers
You can also use any combination of options in conjunction:
C:\IceCC> icedc -i 0,2 -m 10 -u 0 "C:\My Documents\iscript.bin"
This extracts iscript IDs 0 and 2 along with the ones associated with images.dat entry number 10 and units.dat entry number 0.
One thing to remember is that it is very possible that two images.dat entries share the same iscript ID. This means changing that animation set for one of the entries will change it for all of them. The decompiled iscript.txt file will have comments telling you which image.dat entries use its animation sets. If you want to two images.dat entries which normally use the same iscript ID use separate ones, then you will have to also edit the images.dat file that will be a part of your custom. (And then you can use IceCC to create a unique iscript ID and a new set of animations for your new image)
Of course, it is cumbersome to have to specify a input file all the time, since normally you will always extract your animation sets from the default iscript.bin file that is already in Starcraft. The '-d' option tells icedc to use the default iscript.bin file. This does the same as the above using the default file:
C:\IceCC> icedc -d -i 0,2 -m 10 -u 0
The order of options doesn't matter, and the interface is pretty flexible. For example, you can combine two or more options behind the same '-' if they do not expect something after it:
C:\IceCC> icedc -di 0,2 -m 10 -u 0
This combines the d and the i option. We can't put the m option together with the pair because i expects a list of numbers after it.
Here is a full listing of the command line options:
-h
display a help message summarizing all the options.
-v
display the version of the program
-d
decompile the default iscript.bin file
-s
separate the headers for animation sets (explained later)
-o
decompile to instead of the default iscript.txt
-c
use configuration file (explained later)
-r
use the configuration directory (explained later)
-i
only decompile iscript IDs in the list
-m
only decompile those associated with the images.dat list
-s
only decompile those associated with the sprites.dat list
-f
only decompile those associated with the flingy.dat list
-u
only decompile those associated with the units.dat list
Icecc, the iscript compiler works a similar way:
C:\IceCC> icecc [options]
This time, the program can take multiple input files, each of which is either a iscript.bin file or a text file that the decompiler generated and you edited (or you wrote from scratch). The Icecc program will merge all of these files and output a single iscript.bin which consists of all of the header sets which were in each of the files. For example, let's say you extracted the header set with iscript ID 0 (the scourge animations) into iscript.txt, edited them, and now you want to merge it back into your iscript.bin file. Here is what you can do:
C:\IceCC> icecc "C:\My Documents\iscript.bin" iscript.txt
This will merge your iscript.txt file with the original iscript.bin file and output a file with the default name "iscript.bin" in the current directory. If you have more than one set of animations decompiled into separate files, you can merge those in too. You can even merge multiple binary iscript.bin files if you happen to find two with different sets of animations (this may happen if custom iscript.bin files start to be made by others):
C:\IceCC> icecc iscript1.bin iscript.txt iscript2.bin iscript2.txt
Any file with a "bin" extension is assumed to be a binary iscript.bin and all other files are assumed to be text scripts. Normally you will just want to merge your changes with the original iscript.bin, so the '-m' merge option facilitates this:
C:\IceCC> icecc -mo newis.bin iscript.txt iscript2.txt
This example also makes use of the '-o' option which tells the compiler to output the compiled file with the name 'newis.bin' instead of the default 'iscript.bin'. Note that there may be conflicting Iscript IDs in two files. E.G., when compiling your animation header with ID 0 into the original iscript, you are overwriting the animation header with ID 0 in the original iscript.bin. This is OK, and the compiler will deal with it. This is the rule: the files closest to the right have precedence; so in the example above, if iscript.txt and iscript2.txt each had a header with the same iscript ID, the one in iscript2.txt would win and actually get used. The other one is thrown out. When using the '-m' merge option, the original iscript.bin has lowest precedence (naturally, since you want to use your scripts instead of the originals).
Besides its use as a compiler, icecc also serves as a debugger. While the decompiler will always output text scripts that will compile without any problems, when you edit them, you will undoubtedly make mistakes, whether it be misspelling an instruction name or forgetting to write in a animation label. When you try to compile a text script with syntax errors in it, icecc will try to tell you where they are, what they are, and maybe what you can do to fix them. Sometimes, they will only be 'warnings' and icecc will attempt to recover for you and will not abort the compilation (though warnings generally suggest you still made a mistake, it just wasn't a "fatal" one). In any case, a syntax error will generally mean that the compiler will abort and will not generate any output file (a specific error message at the end will tell you so). These debugging messages will be covered in further detail in the next section (Script Files).
Here is a full command-line overview of icecc:
-h
help message
-v
program version
-m
merge with the original iscript.bin
-w
display all syntax errors and warnings (usually only the first 10 are shown)
-o
compile to instead of the default iscript.bin
-c
use config file (explained later)
-r
use config directory (explained later)
You can always get a summary of all the commandline options to either icedc or icecc by running the programs with no arguments:
C:\IceCC> icedc
C:\IceCC> icecc
Script Files
Section III already introduced the general look of the iscript decompiled scripts, but here we'll take a in depth look. Each animation set consists of an iscript header that looks like the following:
# ------------------------------------------------------------------- #
# This header is used by images.dat entries:
# 000 Scourge (zerg\avenger.grp)
.headerstart
IsId 0
Type 12
Init ScourgeInit
Death ScourgeDeath
GndAttkInit [NONE]
AirAttkInit ScourgeAirAttkInit
SpAbility1 [NONE]
GndAttkRpt [NONE]
AirAttkRpt ScourgeAirAttkInit
SpAbility2 [NONE]
GndAttkToIdle [NONE]
AirAttkToIdle ScourgeAirAttkToIdle
SpAbility3 [NONE]
Walking ScourgeWalking
Other ScourgeAirAttkToIdle
BurrowInit [NONE]
.headerend
# ------------------------------------------------------------------- #
The first thing to note is the lines that begin with a hash or pound-sign character (#). The hash marks the beginning of a "comment" and the rest of that line is ignored by the compiler. So that means you can use comments to make notes to yourself. Secondly, note the ".headerstart" and ".headerend" tags. These two tags are special identifiers that mark off the beginning and the end of a header entry, respectively. Everything in between the two is considered to be part of that header (like all text in the script, they are case-sensitive). Inside the header, there are the two special tags, IsId and Type, which determine the unique iscript.bin ID and the type of animation set, receptively. Type number 12 has the 14 animations listed: Init, Death, GndAttkInit, AirAttkInit, SpAbility1, GndAttkRpt, etc. Each of these animation variables points to a label name in the code, which tells Starcraft where they start. For example, The AirAttkInit animation starts at the label ScourgeAirAttkInit. While the Type always determines exactly how many animations a set has, there is no need for every set to use all of them. For example, the scourge doesn't need the SpAbility1 animation which is used for spell casting, since it's unit doesn't use any spells. Therefore, we can give it the special label [NONE]. This is the most common reasons why when you switch graphics between units in the units.dat file (with a tool like Arsenal III), starcraft will sometimes crash. E.G., if we were to give, say, the queen the scourge graphic, the game would crash when we try to cast a spell, because, as you see above, the scourge graphic's animation set doesn't have an spell casting animation. We can fix this easily by changing [NONE] to an actual label in the code.
Between header entries, there is the actual animation scripts that determine how the animations are played. For example, here is the scourge Init animation:
ScourgeInit:
imgul09 1 0 42 # ScourgeShad (zerg\avenger.grp)
playfram 0x00 # frame set 0
waitrand 1 5
ScourgeAirAttkToIdle:
playfram 0x00 # frame set 0
shvertpos 0
wait 3
playfram 0x11 # frame set 1
wait 3
playfram 0x22 # frame set 2
shvertpos 1
wait 3
playfram 0x33 # frame set 3
shvertpos 2
wait 3
playfram 0x44 # frame set 4
shvertpos 1
wait 3
goto ScourgeAirAttkToIdle
Each script begins with a label, and then proceeds with lines of instructions. You will notice that in the middle of this Init animation script, the AirAttkInit script also starts with the label ScourgeAirAttkInit. This demonstrates a key feature of the iscript: different animations can share code. In fact, different animation sets can share code (you can have the firebat and marine have the same GndAttkInit script for example). This is very useful if you don't want to have to rewrite a lot of stuff for many different animation sets. However, it can also become hairy if you have too many headers jumping around everywhere. This is the nature of coding. :)
The other important thing to note is that this script "ends" with a goto instruction that basically makes it loop (though not all the way back to the beginning). Every chunk of code you write should always end in a loop or a "end" instruction, and only the latter if you actually want the animation to stop completely and have the graphic disappear from the screen. The most common way this is done is by just looping a script back to where it started, or somewhere in the middle of it. Here is another example:
ScourgeWalking:
shvertpos 0
local01:
playfram 0x00 # frame set 0
wait 2
playfram 0x11 # frame set 1
wait 2
playfram 0x22 # frame set 2
wait 2
playfram 0x33 # frame set 3
wait 2
playfram 0x44 # frame set 4
wait 2
goto local01
This scourge walking (or rather, flying) animation loops back to its second instruction. Loops can be created by simply creating a label before an instruction and then using a goto to jump back to that label. Label names can contain any characters except for spaces and tabs, and always end in a colon when you declare it. You can "goto" anywhere in the same file, so long as your label names in your goto and before the instruction match. The same goes for the label name used in the header.
Two other little tidbits should be of note here. First, the numbers for each "playfram" instruction are in hexadecimal (base 16 instead of base 10). If you don't like this, then you can use regular based 10 numbers by excluding the '0x'. However, this is useful for the iscript animations which are used by "turning" images (this is a variable set in images.dat). These images can face multiple directions, and they will look different depending on whether they are facing north, west, east, or south. In fact, each turning image has 17 different bitmap images representing each angle it can face (there are actually 32 angles it can face, but the latter 15 are just mirror images of the first 15). You will notice this if you look through GRP images. When playing frames for these turning graphics, the iscript uses the same animation no matter which direction the animation is facing; however, Starcraft also adds a number from 1 to 16 to this number (depending on which angle it is at) to make sure the correct bitmap image corresponding to its direction it is facing is displayed. What should you get out of all this? Mainly this: since each "set" of bitmaps is 17 frames, then the 0th set always begins with frame 0x00 (0), the 1st set begins with 0x11 (17), the 2nd set begins with 0x22 (34), the 3rd set begins with 0x33 (51), the 4th set begins with 0x44 (68), all the way up to the 15th set at 0xFF (255). Since hex notation makes reading "frame sets" instead of individual frames easier to read, hex numbers are used instead. If you really don't like hex, then just don't use the notation yourself. If you really like hex, you will be happy to know that you can use hexadecimal numbers instead of decimal in any instruction or place where a number would go (just prefix it with '0x'). You can also use octal notation (base 8) by prefixing your number with a '0' (zero). Dunno why you'd want to do that, but just in case you accidentally write 010 and wonder why its value is 8 and not 10. :)
That's basically it. Scripts consist of a header and a series of instructions grouped together in scripts. To learn more about the nuances of all the different instructions that are available to use in your scripts, see Appendix B.
Inevitably, when you write scripts, you will make errors: typos, stuff you forgot to write down, or simply things you didn't think about. Icecc, the compiler, will try to tell you where these syntax errors are in your script files, and how you can go about fixing them. Sample output by icecc trying to compile a poorly written script might look like this:
scourge.txt:19: error: unknown animation name 'SpAility2'
scourge.txt:45: error: unknown instruction opcode 'shvertos'
scourge.txt:63: error: not enough arguments to instruction 'wait'
scourge.txt:64: error: instruction 'goto' not connected to a label;
discarding instructions until next label
scourge.txt:70: error: too many arguments to instruction 'wait'
scourge.txt:79: error: final instruction does not terminate
scourge.txt:60: error: can't find label name 'local00'
scourge.txt:55: warning: label 'ScourgeAirAttkInit' is not referred to by
any headers or instructions
scourge.txt:55: warning: label 'ScourgeAirAttkInit' is unreachable
scourge.txt:28: warning: label 'ScourgeInit' is not referred to by any
headers or instructions
icecc: error: aborted due to syntax errors in scourge.txt
It looks a bit terse (and dirty) at first, but the formatting of the error messages is consistent and are short and easy to read once you get used to it. Each error message is formatted like the following:
:: :
The is the file that it was trying to compile. The line number is where the error occurred in the file (or the compiler's "best guess", it may be "around" that area). Let's go through each of these errors one by one. The first error on line 19 says that the compiler doesn't know an animation by the name of 'SpAility2'. Looking in our file, we see that is in a header and that we probably meant to write 'SpAbility2' (missed the 'b', whoops :). At line 45, the compiler doesn't understand the instruction 'shvertos'. Again, this is a small type we can fix by writing 'shvertpos' instead. On line 63, we forgot to give an argument to wait (wait needs to know how many clock ticks to wait, I didn't write anything after it). On line 64, we have a strange error. Looking at the actual file, we see this:
...
59:
attack25
2
60:
goto
local00
61:
62: local00:
63:
wait
64:
goto
local00
65:
66: ScourgeWalking:
57:
shvertpos
0
...
Line numbers shown for clarity. The error tells us that the 'goto' instruction on line 64 is not connected to any label, but here we see clearly that it can be reached by starting at the label 'local00:'. However, looking back at our previous error, we see that we messed up the wait instruction on line 63; this caused the label 'local00:' not to register with the compiler (since the instruction it was pointing to was erroneous). Hence we get this extraneous error message. Sometimes it is useful to fix the first few errors that make sense to you and try to compile again. Some of the later error messages may only be a result of former errors and will disappear once you fixed the earlier ones.
The next error on line 70 shows us that I accidentally wrote 'wait 2 4' when I meant to write just 'wait 2'. On line 79, I have the following:
...
75:
wait
2
76:
playfram
0x33
# frame set 3
77:
wait
2
78:
playfram
0x44
# frame set 4
79:
wait
3
Which is followed by the end of the file. Thinking for a moment, I realize that this script just trails off the end without a terminating 'end' instruction or a 'goto' to loop back to a label. I meant to terminate this off with a 'goto local01' which is a label just above to loop it. Next on line 60, it says that the label local00 was not found. Looking back at the first example, this means I used local00 in a goto instruction, but don't actually have a 'local00:' label pointing to any instruction. Strange, I see that I wrote local00: right above that; but, this again is the result of that bogus 'wait' instruction. Since the instruction the label was pointing to was erroneous, it never registered and hence, the compiler doesn't know what it is. Again, this is one of those extraneous errors that would go away after fixing the first few easy ones. Next we have a pair of warnings on line 55; that the label 'ScourgeAirAttkInit' is not used by any goto instructions or by any header animations and, hence, that it is not reachable (meaning there is no way we can get to that label). This is only a warning, since the compiler will just discard the label and hope that everything turns out OK. If we look back from the way beginning, we see that this error occurred because we misspelled 'SpAility2' in the header, and thus that animation's label pointer (which was this label that the compiler says is unreachable) was discarded. Finally we have 'ScourgeInit' which the compiler says is not used by any headers to goto instructions. This error, believe it or not, is a result of the 'SpAility' misspelling also. Because we fudged the animation name in the header, the entire header did not register with the compiler, and hence while the label 'ScourgeInit' is referenced in our header, it did not register, since our header did not register.
The moral of the story? A lots of error messages doesn't mean you have lots of errors. Fix the ones you understand and usually the rest will go away. The compiler just tries to be extra helpful just in case you can understand all of them. :)
For more information, see the Appendices.
Example
This section will go through a quick example. One day, we looked at the SCV while it wasn't doing anything and we thought, "hey it's not even moving." It would be much more exciting if the SCV did something while it was idle; even the ghost likes to cock his gun every once in a while. So we decide to do something about it.
First we need to extract the SCV's animation's from the iscript.bin. I don't know the SCV's iscript ID, and I don't feel like looking through all 1000 images.dat entries looking for it, so I fire up Arsenal III and look for the SCV units.dat entry (the entry number is displayed in the lower right hand corner). It is number 7.
In IceCCUI, I select the Decompiler Tab. Then I select "7 TerranSCV" in the Units list. Next, I type in scv.txt in the Save to: field so that that's where the script will be saved to. Finally, I click Decompile.
Now, I open up scv.txt in my favorite text editor. Notepad in Windows and TextEdit in Mac OS X are good enough, but you can easily do better with something like UBB Edit (Windows) or BBEdit (Mac).
I see the following:
# ----------------------------------------------------------------------------- #
# This is a decompile of the iscript.bin file './data/scripts/iscript.bin'
# created on: Sun Jan 14 19:30:03 2001
# ----------------------------------------------------------------------------- #
# ----------------------------------------------------------------------------- #
# This header is used by images.dat entries:
# 247 SCV (terran\SCV.grp)
.headerstart
IsId
84
Type
15
Init
SCVInit
Death
SCVDeath
GndAttkInit
SCVGndAttkInit
AirAttkInit
[NONE]
SpAbility1
[NONE]
GndAttkRpt
SCVGndAttkInit
AirAttkRpt
[NONE]
SpAbility2
[NONE]
GndAttkToIdle
SCVGndAttkToIdle
AirAttkToIdle
[NONE]
SpAbility3
[NONE]
Walking
SCVWalking
Other
SCVOther
BurrowInit
[NONE]
ConstrctHarvst
[NONE]
IsWorking
SCVIsWorking
.headerend
# ----------------------------------------------------------------------------- #
SCVInit:
imgul09 248 0 7
# SCVShad (terran\SCV.grp)
playfram 0x00
# frame set 0
goto SCVOther
SCVOther:
wait 125
goto SCVOther
SCVDeath:
playsnd 369
# Terran\SCV\TSCDth00.WAV
imgol08 332 0 0
# TerranBuildingExplosionsmall (thingy\tBangS.grp)
wait 3
end
SCVGndAttkInit:
shvertpos 0
wait 1
playfram 0x22
# frame set 2
attack25 1
wait 1
playfram 0x11
# frame set 1
wait 1
gotorepeatattk
goto SCVOther
SCVGndAttkToIdle:
playfram 0x00
# frame set 0
goto SCVOther
SCVWalking:
playfram 0x00
# frame set 0
imgol08 249 0 0
# SCVGlow (thingy\tscGlow.grp)
shvertpos 0
goto SCVOther
SCVIsWorking:
shvertpos 0
wait 1
local00:
playfram 0x22
# frame set 2
useweapon 14
# Fusion Cutter
wait 1
playfram 0x11
# frame set 1
waitrand 8 10
goto local00
Its a quite a bit of stuff, but not overwhelming. Studying the header, I see that the initial animation of the SCV starts at the label 'SCVInit':
SCVInit:
imgul09 248 0 7
# SCVShad (terran\SCV.grp)
playfram 0x00
# frame set 0
goto SCVOther
SCVOther:
wait 125
goto SCVOther
So, its animation starts by playing an image underlay (imgul09) which just means it plays another graphic under itself, the image being an images.dat number. The comment tells us that this is most probably its shadow. No problem there, we still want our SCV to see it's shadow. Then it plays a frame from frame set 0 (the SCV is a turning graphic, since it can face many directions), and then it goes to 'SCVOther', which is just below it. Here, it basically does nothing. It waits for a lot of ticks, loops, then waits for even more ticks. Looking at the other animations, we see that most end up here at 'SCVOther'. This looks like the SCV's idle animation. It waits, loops, and waits some more. Boring.
Let's make a little change:
SCVOther:
shvertpos 1
wait 1
shvertpos 2
wait 1
shvertpos 3
wait 1
shvertpos 2
wait 1
goto SCVOther
We add the 'shvertpos' (shift vertical position) instruction to make it turn move up 1 then 2 then 3 pixels and then move back down again, before looping. (You can think of the 'base' ground position at 0, and shvertpos moves the graphic up X pixels from the gournd 0 position) Now our SCV should jump up and down while its idle. Cool.
After saving our text file, we need to compile it back into the original iscript.bin file. Now I select the Compiler tab. Then I click Add and select the scv.txt file that I just modified. I leave Merge with default iscript.bin checked because I just want to use my new SCV while leaving all the other units unchanged. Next I type in myiscript.bin in the Save to: field which indicates where my new iscript will be saved to. Finally, I click Compile. IceCC responds:
scv.txt:61: error: instruction 'd' not connected to a label; discarding
instructions until next label
scv.txt:61: error: unknown instruction opcode 'd'
icecc: error: aborted due to syntax errors in scv.txt
Oops. Looks like I accidentally typed a 'd' character on line 61. Didn't mean to do that. I go back and delete that and try Compile again. (Hint: if you select one of the error lines and then click on Open in Editor, IceCC will automatically open the offending file in the editor specified in the Preferences).
This time it works (no messages is a good sign; learn to love quietness :), and the output file is generated as myiscript.bin.
Now, I either fire up Stardraft, create a new CWAD, or use MPQ2K to create an MPQ and put myiscript.bin in:
scripts\iscript.bin
This is where you will always put your new iscript.bin file
Start up the patch loader (Stardraft for CWADs and MPQDraft for MPQs) and run my patch, and look at an SCV. Looks like we gave our peons a little too much sugar. :)
Of course, you can incorporate other files too. The iscript is just one part of the picture; advanced users will see how they can use it to make their own graphics move how they want them too, instead of following Starcraft's boring routines. More examples are in the Examples directory.
Appendix A: Animation Types
There are 28 different animations that entries can have. However, not all animation types use all of them (in fact, most only use the first 14 or less). They are:
0: Init
1: Death
2: GndAttkInit
3: AirAttkInit
4: SpAbility1
5: GndAttkRpt
6: AirAttkRpt
7: SpAbility2
8: GndAttkToIdle
9: AirAttkToIdle
10: SpAbility3
11: Walking
12: Other
13: BurrowInit
14: ConstrctHarvst
15: IsWorking
16: Landing
17: LiftOff
18: Unknown18
19: Unknown19
20: Unknown20
21: Unknown21
22: Unknown22
23: Unknown23
24: Unknown24
25: Burrow
26: UnBurrow
27: Unknown27
Init - this is the animation that plays when the graphic is 'spawned' (when it first appears on the screen). Generally, for unit graphics, this will play the shadow graphic as an underlay (so that the unit will have a shadow) and then go into it's idle animation loop (which doesn't have a label name of its own, it just is kind of "in the middle" of everything).
Death - this is the animation that plays when the graphic is destroyed (e.g., when the unit dies). This will always end with the 'end' instruction, which terminates the script and tells Starcraft to remove the graphic.
GndAttkInit - this is the animation that plays when the unit the graphic is associated with begins to attack a target which is a ground unit. It generally end with a 'gotorepeatattk' instruction followed by a goto which goes back to its idle animation loop. This is because the unit may stop attacking, or it may continue attacking. If it is still attacking when it reaches the 'gotorepeatattk' instruction, it will goto the GndAttkRpt animation, otherwise it will go back to its idle animation. (If the 'gotorepeatattk' instruction is ommitted, the unit will only attack once, then stop) In the middle somewhere, it will contain a 'attack25' or 'attack26' or some other attack instruction which will tell it to actually do the damage or shoot its missile.
AirAttkInit - same, but for air units. Some graphics use the same animations for both air and ground attacks. This is fine, as most units look the same whether their target is air or ground.
SpAbility1 - this is main spell casting animation. It generally contains a 'castspell' instruction in the middle which is the actual point where the spell "takes effect." Most units don't use this and use the SpAbility2 animation instead.
GndAttkRpt - this is the animation that the graphic goes to if, after starting it's attack, it continues to attack. Usually this is the same as the GndAttkInit animation (so its just a loop).
AirAttkRpt - same for the unit's air air attack.
SpAbility2 - this is another spell casting animation. Some spells use this instead of the first (e.g., some units which have two different spells which use different animations).
GndAttkToIdle - this is the animation that plays when the unit stops attacking its ground target and returns to "idle." Generally this is a pointer to the unit's idle animation.
AirAttkToIdle - same for when the unit stops attacking an air target.
SpAbility3 - yet another spell casting animation. You'll have to look through the original scripts to see what units actually use this. Most don't.
Walking - this is the animation that plays when the unit moves from one location to another. Generally it will have some 'move' instructions which tells the graphic to move forward X pixels on the screen. Note that if the graphic is a unit graphic, and the flingy.dat entry that is associated with the animation set has its 'Move Control' variable set to something other than 'iscript control' (see a DAT editor like Arsenal III), then any 'move' instructions here will be ignored. For many flying units like the scourge, movement speed and acceleration is controlled by flingy.dat and not the actual animation. That is why when you look at the walking animation for the scourge it doesn't contain any 'move' instructions. Though it does contain the instructions to make the graphic bob up-and-down while it flies.
Other -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).
BurrowInit - Some graphics can start out burrowed when they are spawned (e.g., Zerg units when a game begins, or are created with the 'Create Units with Properties' trigger). Instead of the Init animation playing, this one is played instead.
ConstrctHarvst - This is the animation that plays when a building is being construted (for the building) or when peons (SCVs, Drones, Probes) harvest minerals.
IsWorking - This is the animation for buildings which plays when the building is "working." E.G., when it is training a unit or upgrading an ability.
Landing - This is the animation that plays when a Terran building lands.
LiftOff - This is the animation that plays when a Terran building lifts off.
As you can see number 18-24 are still Unknown. They are rarely used, so you probably don't have to worry about them. If you want to help, you can try to figure out what they are for.
Burrow - This is the animation that plays when the unit burrows.
Unburrow - This plays when the unit unburrows.
Number 27 is also unknown.
There are several different 'Type' numbers which you can give to a header. Generally, you will keep the one that is already there. Each type contains a different number of animations, here are the ones that are known (see the beginning of this section for the tags the numbers refer to):
Type 0 - Uses animations 0 to 1.
Type 1 - Uses animations 0 to 1.
Type 2 - Uses animations 0 to 3.
Type 12 - Uses animations 0 to 13.
Type 13 - Uses animations 0 to 13.
Type 14 - Uses animations 0 to 15.
Type 15 - Uses animations 0 to 15.
Type 20 - Uses animations 0 to 21.
Type 21 - Uses animations 0 to 21.
Type 23 - Uses animations 0 to 23.
Type 24 - Uses animations 0 to 25.
Type 26 - Uses animations 0 to 27.
Type 27 - Uses animations 0 to 27.
Type 28 - Uses animations 0 to 27.
Type 29 - Uses animations 0 to 27.
Remember, just because a set type contains a set of animations, doesn't mean it uses all of them. Any one can have a [NONE] label to signify that no animation is used (but make sure it really doesn't need it!). Take a browse through the iscript if you want to get an idea of what kinds of animation sets use which types. The pattern should be pretty intuitive.
Appendix B: Instruction Listfile.dat
This is a list of instructions which can be used in scripts. There are some that are unknown. This does not mean they will crash your script or anything (though they might), it just means that I haven't taken the time to test them. (These are usually recognized because their name is just usually just '__' prefixed to some hex number) If you would like to help, you can try these out and see what they do. To get a better idea, you can decompile the original iscript and see how it uses them. Each instruction may take a number of arguments. This is usually a couple of numbers (frame number to play, images.dat entry to use as an overlay graphic, etc.). For "jump" instructions like goto, this may also be a label (the label to "jump to"). A few examples:
Description: playfram
Example: playfram 10
Description: goto
浙公网安备 33021202002483