Iskatumesk's StarCraft Editing Bible - Part 1

By Iskatumesk. Edited into an article by Magic.

There are few people who know the art of editing StarCraft and fewer still who have done even more amazing feats in the subject. Iskatumesk has dedicated countless hours and has kindly put some of his experiences into this article, which aims to teach the more in-depth levels of editing StarCraft. The original thread is still available here. While this is several years old, it's nonetheless an epic production and one I'm proud to have hosted on Samods. Enjoy. - Magic

Note I only and only ever will support modding version 1.10. This is directly copied from my post on SME. I probably won't be completing the editing bible now unless I get strong request to do so. - Mesk

---


CONTENTS

PART 1
Overview
Introduction
Tools

Chapter Pi - Iscript
Helpful Knowledge
Introduction to iscript
Quick Facts
Removing the Battlecruiser's Engine Overlay
Quick Fact

Chapter Pib
Adding and scripting an entirely new overlay
Notes
Quick Facts
Update


PART 2
Overview

Segment 1 - The KA-NF42g Black Eagle AMAC
Segment 2 - The Eagle's Wings
Segment 3 - The Eagle's Talons
Segment 4 - The Eagle Has Landed

Segment 42a - AI editing
Introduction

Chaptier PiC - The HK Crit System

1.1 - The Heretic Wizard
What it does
How it works
The Code

1.2 - The Madness Titan

What it does
How it works
The Code

1.3 - The Touch of Anguish
What it does
How it works
The Code


---


OVERVIEW


Welcome. You open this tome in search of knowledge on how to mod StarCraft. In which case, you have come to the right place. Here I shall reveal to the willing individual my methods and tools used to create the most advanced and stunning of Total Conversions for Blizzard's StarCraft and it's expansion. In addition, other masters of modding will lend their hand in their areas of expertise, and this incarnation of a guide to editing will be great in it's coverage.

Notes - This guide is written on the observations and methods used by IskatuMesk. Preferences may vary, but this is how I do things. I will explain to the finest detail, using both words and pictures, to convey how I do everything from model great warships to programming unstoppable AI. I will detail on the advantages and disadvantages of many aspects of SC, and open the world of Iscript to many of those who are afraid of it's complexity. Here I unveil all for those willing to hear.

INTRODUCTION

I started modding SC for kicks. I had a general idea of what I wanted to do, and I went out and experimented. No tutorials or anything were really available at the time [and still remain so], so I picked up the basic tools I found, including StarDraft, and set to work. It was a tough time learning, and I made many mistakes and silly errors in my years of modding, but now I am confident I have learned nearly everything within the range of my tools. I don't yet know ASM much, but that is changing gradually. Yet still, no tutorials are available for anything beyond the absolute basics. I shall now change this.

I treat modding as an art. I aim for absolute perfection in all things. While story is up to the creator, graphics, sounds, AI, gameplay... all things must be equal and absolute in quality and immersion. However, many people overestimate their capabilities, and end up shutting down a mod before it's even playable. Only when you are confident you can at least get a mod going strong should you even attempt to start. So many mods are started, and only a fraction ever get anywhere, let alone finish. This goes for modding period. Save yourself the trouble if you think you can't keep dedicated, and don't even start. I have had trouble with this myself, and I kick myself everytime I think about it. However, I have gained something through my mods, and you will too. That is called experience.

This guide will show you how I mod. I will teach you how to model a basic ship in Rhino 3D 2.0, texture it, render it, convert the frames for usage in StarCraft, convert a special building into it, then alter the building's animations, stats, and special abilities to fit your new unit. I will teach you how to completely change a race and then program a computer player that will savagely rape human players using this new race. I will teach you how to turn a pistol into a cannon through sound effects editing using Cooledit. I will provide source material for everything I create in this guide. I will teach you how to utilise nearly every single tool out now. The things I can't teach you, others will. I will call upon some of the best known names in the StarCraft modding world to help me flush out sections I am not familiar with, such as campaign triggering, cinematics, portrait modelling, and so forth.

Again, this is how I do things. They may be different than what others say to do, but they work, and with these methods great things are crafted. May the doors be opened.


TOOLS

The tools I plan to cover are -

- IceCC, used for editing "iscript.bin", the animations and even special effects of SC.
- SCaiedit 3.1, used for editing "aiscript.bin", the computer player scripts of SC.
- Arsenal 3, Arsenal Zero, Used for editing various ".dat" files, the data of SC.
- TBL edit, binedit, tileedit, used to edit various cosmetics, such as interfaces and text. Tileedit is used for, guess, editing tiles.
- Winmpq, used to edit ".mpq" files, where your data is stored.
- MPQdraft, used to "patch" sc, and make .exe's for your friends to use.
- StarGraft, for editing buttons, and MG 1.10 for converting them. Much of this knowledge can be applied to MG 1.11 and 1.12.
- RetroGRP, used to compile SC sprites from bmps.
- StarEdit, used to create maps, campaigns, and such.
- Photoshop, Paint Shop pro, used to edit sprites and textures as well as menus, interfaces. Most anything graphics are manipulated with these tools.
- Rhino 3D, 3ds max, used to create units, buildings, projectiles, effects, and even menus.
- Audition, Goldwave, used to edit sounds, voice responses, and such.

Many of these tools are available at www.campaigncreations.org, and www.samods.org. Please note that Photoshop, paint shop pro, cooledit pro, Goldwave, Rhino 3d, and 3ds max all require being purchased. However, they are extremely powerful tools and if you are a student you can often acquire a student discount on these applications.

The structure of this guide [once complete] will be similar to the following.

- Basic introduction to the very basics of sc editing, such stat editing, changing names, and adding existing graphics.
- Creating a unit that replaces an existing one, such as a new wraith, right from scratch using Rhino 3D. paint shop pro, Arsenal Zero and RetroGRP.
- Creating a unit that replaces a special structure, such as the overmind cocoon, right from scratch, then tweaking it out with Rhino 3D, paint shop pro, cooledit pro/goldwave, photoshop, retroGRP, Arsenal Zero and stargraft.



CHAPTER PI - ISCRIPT

The power of iscript.bin should never be ignored or misunderstood.

The iscript is a core part of starcraft. It is edited using Icecc (NOT regular ICE. Never. Ever.) which consists of both a command prompt and a java UI that decompile parts or the entire iscript for you to edit using your favourite text editing application (I just use notepad, but context or the like would work fine too.)

Here is a very basic list of what you can and need to do with iscript.

- Edit the frames of units to support different grps.
- Edit overlays, such as engines, muzzle flashes, missile trails, ect.
- Edit effects, such as explosions, sounds, of units and effects.
- Creating new units and weaponry out of unused or different "slots".

Helpful Knowledge
* I refer to every unit as a Slot. An iscript entry is a graphical slot, meaning that most entries can be used for any purpose requiring a new grp.
* Unit "slots" are different than graphical ones. I refer to unit slots as entries in units.dat which are much fewer than in iscript or images.dat. Units.dat slots are limited, so make sure you plan out your new units carefully.
* When decompiling the iscript, you should use the java interface (Grab the latest RLE off of java's site, google for it if you must, I'll include a link whenever I am not lazy) and decompile units one at a time in your mod's data folder for better organization.
* Don't change anything without knowledge on what you are doing, or you will probably cause crashes. Feel free to ask any questions in this forum regarding this section.


Introduction to iscript

Iscript's purpose is two-fold - Functionality and Supportive functionality. To me, functionality is the ability to manipulate how a unit, structure, or effect works. With iscript, I can make an explosion expand to the radius of a map, or a ship fire a sequenced set of weapons, or add two turrets to a marine's face.

However, we won't start off with such complex things. For now, let's say we wanted to remove the Battlecruiser's engine glow. To do this, we must first acquire icecc from smempire.org's download database. I trust you are competent enough to find it. Also be sure to grab Hunter_Killers' iscript definitions which identify many of the unknowns in the java interface.

Make sure the icecc folder is under C:\. It is not known to me why, but the program only functions if it's main under is under C:\ as Icecc.

Now that the java UI is running, you should see something like this:



Note a few features of the interface. First is the columns of names which you probably recognize the names in. The two middle ones I rarely ever use, but the images and units column both are very important. Here's why.

The units.dat only lists units. It's very easy to find a basic unit, such as the selected Battlecruiser, in this column. HOWEVER, if you want to edit something such as an overlay or a projectile, the images column lists those in addition to the basic units. As you can see, the images column is listing the Scourge's birth, shadow, death effect, explosion, and the actual unit. These are all graphics slots - they all have individual GRP's.

Now, select the Battlecruiser as I have done by clicking on it's name. Any thing "selected" will be dumped into a text file, even if you select everything, when you decompile. This can be useful to mass-edit things, but icecc decompiles them in such a way that they can often share local entries or the like, and editing them may unintentionally effect the other units decompiled in the file. To be safe, only select the Battlecruiser for this.

Now, look down a bit. Two boxes can be checked. Seperate headers I have never bothered with figuring out, so always keep it checked. I think it has something to do with how the headers (which I'll be explaining later) are arranged in the text file.

"use Default iscript.bin" when checked will decompile the files from the iscript.bin included with icecc. You'd only uncheck this if you want to specify your own custom iscript.bin. This can be used to extract custom animations from a different mod or to retrieve your own animations from a re-compiled iscript.bin. Leave it checked for now as well.

The Save-to section will specify where to save your text file. You have to manually specify it'll decompile to .txt, which I'm sure you know how to do. Set the .txt file to be saved somewhere where you can easily find it, such as inside your mod folder. Name it something like beecee.txt or ilikegoatslalowskatz.txt. Now, click decompile.

Hunt down your txt file and open it. It should look something like this:


Now the fun begins!

You're probably overwhelmed by this. It's called code. It isn't a very advanced code, but it's realitively easy to screw up in given Starcraft's pickiness. I'll touch on that later.

Quick Facts
- At the very top is a number of lines of text identifying what sections are what. You can tell what most of them are by piecing together the abbreviations. These are called headers. Note that for a lot of things, headers like burrowinit and a lot of the unknowns have many different uses depending on the unit or the effect. These uses are not entirely known but once you become more advanced you'll begin to understand how they are used.
- Don't modify the headers unless you also modify the sections that you can find by scrolling down.
- IsID is the Iscript section's ID. "Type" is related to the headers and refers to how many there is. If you change the number of headers this must change as well. Look at different units to get an idea how this works.


Removing the Battlecruiser's Engine Overlay

Every single line of text in an iscript script is a command. You can guess what many of them are, but here's a list of what they mean.


- playfram designates either a frameset or a single frame. The battlecruiser is one frameset, or 17 frames. This is dependant on the following command. a 0x** tells Starcraft which set to use. Frameset 0x00 is the first 17 frames, 0x11 the next set, ect. Once it reaches 0x99 it can either go into hex or be designated via more numbers, such as 0x122. Inspect large-frame units, such as the ghost, for a better understanding.
- Most air units only have 1 frameset. Animated ones, like mutalisks and overlards, have more to make them animate at all.
- playfram with only a single numberal such as 1 or 42 designate a particular frame and not a set. This is most often seen on buildings and some projectiles which don't turn (face one direction for buildings) and thus have no use for framesets. This is also be used by units such as zerglings to play their death animations which are only a few frames.
- imgul09 stands for Image Underlay. Underlay likely means that the designated ID (an images.dat ID) will always be displayed "under" the unit it's being spawned on, and never on top. Likewise, imgol08 stands for Image Overlay, which is displayed ABOVE the unit, and never under. This can be useful. Note shadows are always underlays, and things like explosions are always overlays. Can you guess why?
- goto tells the running script to go to another segment. In this case, the Idle area, which has the BC either hover or stand until the player issues a command.



Now, scroll down a bit until you find this section.


Now, the Battlecruiser does actually "walk". Walking is a header always ran when a unit enters movement. While the walking animation may direct the running code to an idle animation, like this does, the unit will continue moving.

A possible question is, if the script is telling the walking animation to go to idle... what happens to the Glow?


The "glow" is an engine overlay that makes the engines behind the battlecruiser light up. This glow has it's own iscript entry. When triggered, it has it's own script that runs a looping walk animation. When the battlecruiser stops, the engine's script ends itself, and it ceases to exist until the ship starts moving again. To remove this, you can either replace the grp, or simply -


- nuke it's line of code!

This method of removal only works for overlays and the like. It's not always wise to delete things, but if you want to remove the engine's glow, or even the firing glow (Look at the attk animations and figure out which is making that laser muzzle flash appear), all you need to do is remove that line of text.

Now, to compile our changes!



Obviously, you can access this section by clicking the Compiler tab in the Java ui.

Source files are those added through the Add button. There's two ways to do this.

Merge with the default script button removes the need to add your own. This is useful if you're just testing a single thing in a barely modified engine. However, if you're adding a new script to an existing modified iscript.bin, you want to uncheck the merge with default, and add yours. Make sure the iscript.bin is at the top of the list.

Additional, add your edited battlecruiser's script .txt file to the list. On the bottom of the UI it wants you to put in the path for your new iscript.bin. Note you cannot replace the one it's currently adding or merging, so just specify a new one.

Quick Fact
- The 1.10 iscript.bin's format changed slightly, and this was enough to fuck up icecc's compiler. Use the default.bin are your base iscript.bin or find a 1.09 file. Icecc comes with the 1.07 bin I think, but it supposedly works fine all the way up till the latest patch.

Why?

In 1.10 blizzard changed how the drone's hardcoded command sequencing works to "fix" the floating issue. This not only fucked how the AI handles it, but it also slightly changed how the iscript works, and this desynced icecc. The differences between the 1.10 iscript.bin and the default are virtually unnoticeable so it's perfectly safe to use the default one.


Once you have designated your new file, press COMPILE. It should have created your new file. If a popup appears with errors, however, like this:



There's a good chance you've done something you shouldn't have and should correct it. While the compiler will sometimes just warn you of errors, it's ALWAYS a good idea to correct them. I will touch on the various errors later on, but simply removing the line containing the engine's overlay should produce no errors and you are free to test your new super-cruiser ingame by adding the compiled iscript as scripts\iscript.bin in your custom MPQ.

CONGRATZ! UV LRND HOW 2 RMOV OVARLEYS


This guide is a work in progress. I work on it in my free time, and little else. Please do not rush me in the creation of this guide. Feel free, however, to ask questions about the guide itself.


---


CHAPTER PIB


Adding and scripting an entirely new overlay

Last section, you learned how to extract the Battlecruiser and remove it's engine overlay. Now, I'm going to show you how to add an entirely new overlay, in this case, my firing animation for the blood moon.

Since this method uses core ITAS data which is not available to you, you need not recreate this step-by-step. Instead, pay very close attention to the steps I do. You can use this knowledge to edit existing animations and to further understand the relationship between.

This is a more advanced process. I am writing it now because I am adding the overlay now, and it involves a number of things I feel I should write out as I do them.

Just for reference, the Blood Moon is the big death star-esque thing in this image:



The firing overlay I intend to add will create a glowing chargeup effect that brings prelude to the ship's mighty weapon. Sound difficult? It isn't, really. I'll split it into basic steps.

- Find my Blood Moon text file.
- Compile/convert my overlay frames into a grp which have already been rendered from Rhino.
- Find a slot to use for the firing overlay.
- Figure out the firing overlay's animation sequence.
- Refer to the Battlecruiser's firing overlay to understand how it works.
- Enable the firing overlay on the Blood Moon.
- Test!

Let's begin!

This is what my Blood Moon's script looks like.


That's right, I converted the Defiler Mound into the blood moon, because I no longer have need for the defiler mound's graphic. It now uses the Cerebrat.

You'll probably notice this looks very similar to the Battlecruiser, save the death animation. Can you guess what my new death animation is doing? It's creating a small series of explosions. I will expand this series into a far greater one in this tutorial as well, to show you how co-ordinates work.

Now, I will compile and convert my firing overlay. Since this a process that will be covered elsewhere, I won't touch on how it's done here.

Also note I'll briefly cover the Images.dat process of changing the palette for the firing overlay so it appears as the default zerg green, which I will later change to a blood red.

This is what a frame of my overlay looks like. It will be much more impressive ingame and when it is moving.



Notes
- Overlays, such as this firing/chargeup one, can be very handy for pretty-ing up units. Since they can be given a transparent palette via images.dat, they can be turned into new explosions, glow effects, engines, or anything you want very easily. However, all overlays contribute to a maximum sprite limit that is shared with all overlays and all projectiles. A large number of overlays and projectiles will hit this limit and cause funky shit to happen, like units not attacking. Since ITAS is such a huge TC and there can be thousands of units on the playing field at a time, I am only making overlays and effects for a select few ships that need them to truly shine. I am hoping one day I'll have the power to remove this limit.
- You can have "limitless" numbers of overlays and underlays, but they all contribute to said limit.
- Overlays and underlays follow the movements of their host unit. When the battlecruiser turns, so does the engines. The engines must have the exact number of framesets as the battlecruiser or higher.
- To make an independant overlay, you would use the Sprite overlay, which will be explained in greater detail later on. These overlays use different ID's and are used for things like missile trails and my infamous XenoXallus cannon.


Since I am a noob, I want to use some out-of-the-way grp that I'll probably never have a use for. In this case, I have conveniently layed out my processes in an immensely organized fashion, as shown here:



As you can see, not only have I legally pirated the Batman Begins soundtrack, but I've also selected the Nexus Glow to molest viciously for my unjustified need for destruction. In addition, it's almost lunch time. HORRAY!

Due to the fact that the fifth frameset of my overlay is a goat lover and retrogrp dislikes goat lovers, I will only be using the first four framesets.

The decompiled nexus glow gives something like this,


Obviously, in it's current state, it just won't do. The overlay cannot exist until the ship fires. How do we figure out how to configure it so? The friendly neighbor Guardian Muzzle Flash will help us!



With my friendly neighborhood drunk on my side, no man is safe.


Cool, eh? The Guardian Muzzle flash's script is in the assumption it's created when the Guardian Fires, so it instantly begins playing it's selected frames, then stabs itself in the face with a table when it is done. Let's just copy this over to our misshappen nexus glow...

However, it cannot be lift simply as it is. As I said, the fifth frameset was sodomized by retrogrp in it's mad lust for revenge, and thus it cannot be used lest we make starcraft explode into a gory mess. However, if you look at my Blood Moon script, we must make this firing animation last 2 seconds. To do that, I will do something really neat.

Quick Facts
- Waits are in ticks, timed by the "normal" game speed in starcraft. 10 ticks make a second. Careful use of waits and frame changes can create a very powerful illusion of movement in many different forms.
- I can make the moving energy circle in the firing animation close slowly, then speed up, by first using large waits, then short waits, as I repeat it's animation.
- I want to add a sound for this badass, I can do so by using the command playsnd.
- playsnd calls an ID from sounds.dat.



Ultimately, my new firing animation lasts 24 ticks, not 20. To syncronize it with the attack beam, I must set the wait in my blood moon to 24.



And I end up with this. When the Blood Moon fires, it will play the overlay, which lasts 24 ticks. As the overlay is playing, the unit will wait 24 ticks. A graphic of oscilliating energy circles will appear on it, and then it will unleash all of hell.

Note that the code for the firing animation I placed previously is unstable! Without a nobrkcode command, if the Blood Moon moved or it's target died before it finished charging, the overlay would not end, and since it lacked any animations besides the two it had, it'd try to initiate animations it did not contain, and crash! I have corrected this.

Nobrkcode forces the sequence to execute no matter what. However, the Blood Moon won't fire if it has no target, so now it simply executes the chargeup animation and correctly removes the overlay under any circumstances.


I am not quite done. I want to make the Blood Moon's death explosion a fair bit more dramatic than only five fireballs.


Fiddling with co-ordinates to produce this type of effect has been vastly overlooked by the community. Only one other person has even thought of doing this. Hunter_Killers and myself made it the staple of our works in MFTGATRL by reintroducing this frighteningly simple ability.

Overlays need co-ordinates. Typically, the co-ordinates are 0,0,0, or the dead center of a unit. If you have ANY math knowledge whatsoever (I didn't, I had to have Ojan teach me :P), you'll recognize this:



That's right. It's a chart. Horray! SC works virtually the same way as this chart does. This can be used to create a big glowing 42 out of HK trails, or in this case, a really fucking big explosion.

As you can see in my code, the Blood Moon is currently using the smallest capital explosion set. It spawns four additional Confederate-style explosions. I need to hijack the Dark Archon explosion, conveniently located in my Spirestorm script, and toss it in.


Ignore the commented labels saying those are terran explosions. They are, in fact, purty dark archons giving their lives to make the spirestorm go bang in a satisfying manner. What this part of the script is doing is sending a trail of explosions in four directions - left, right, north, south. But I want to make it even more dramatic for a star-sized warship. I will expand this explosion even further!


*laughs maniacally* IT IS DONE!

UPDATE:

After setting the new overlay to turn in images.dat and giving it a palette, I was rewarded with a very pretty show.




UPDATE II:

Next time, I'll show you how I'll create the Blood Moon's Plasma Vortex projectile. It will be delicious!


To Part 2

---