Hey everyone, look at this little demo mod:
https://www.dropbox.com/s/ymktu7q1dd33u0j/iscript%20demo.7z?dl=1

It makes following changes to units:
- Guardian becomes transparent (like cloaked, without requiring detection), while becoming visible while moving.
- Marines can't attack while stimmed
- Overlords have random player colors
- Archon's color changes depending on mouse x/y coordinates (This one is 1.16.1 only though :l)
- Once cloaked, ghosts can't decloak unless they nuke. I didn't test if they can decloak if their energy runs out but that shouldn't work either

So how is this done? You might think there's some mpqdraft plugin doing code edits, but this all is done with iscript!
Most of these tricks use the little-known iscript command "warpoverlay", which is normally only used in the warp texture iscript. What it does is not limited to the warp texture, it sets the parameter for images.dat draw function. The effect varies on drawfunc set there, here's the (almost) full list:

• Drawfunc 0x0 = Normal draw, may switch to hallucination or cloaking drawfuncs, parameter does nothing
  
• Drawfunc 0x1 = Normal draw, parameter does nothing
  
• Drawfunc 0x2 = Enemy unit is starting to cloak, parameter specifies state (in lowest signed byte), and timer (in second lowest unsigned byte). Bw reduces timer by 1 every frame, and once it reaches 0, it is resetted back to 3, and state is increased by 1. Once state is 8 or more and timer exactly 0, bw considers unit to be fully cloaked and switches to drawfunc 0x3 (Fully cloaked enemy). Depending on the state, unit appears to be completely uncloaked (state 0), completely cloaked (state 8), or something inbetween.
  I used this on the demo mod's guardian's iscript: every animation expect GuardianWalking runs constantly command "warpoverlay 65344", which in hex is 0xff40. It means that the "timer" is 0xff (255), and the "state" is 0x40 (64), though anything between 8 and 0x80 is same, causing guardian to appear as transparent.
  However, GuardianWalking uses "warpoverlay 65408" (0xff80), and bw considers 0x80 (-127) to be less than 0, making guardian completely visible. The "timer" is set to 255, as reaching 0 with state 0x40 would cause drawfunc to be switched to 0x3, making guardian permamently transparent. Even though all this looks like there is cloaking happening, the guardian is always targetable without detection.
  HOWEVER! If the drawfunc would be switched to 0x3, unit becomes properly, permamently cloaked. (I haven't tested this but it should work, feel free to prove me right/wrong)
  Setting drawfunc from images.dat directly to 0x3 does not make unit cloaked, it has to switch from 0x2 -> 0x3.
  
• Drawfunc 0x3 = Enemy unit is cloaked, parameter does nothing. This makes unit just look transparent without being actually one. All the cool stuff happens in drawfunc 0x2.
  
• Drawfunc 0x4 = Enemy unit is starting to decloak, paremeter specfies state and timer like in 0x2, but now state counts down from 8 -> 0. Once it reaches state 0, unit becomes visible without detection. I used this in the demo mod's ghost iscript, preventing state from ever reaching 0 (with warpoverlay 65408), causing ghost to be "stuck" in cloaked state.
  
• Drawfunc 0x5 = Detected unit is starting to cloak: Same as 0x2, but makes image appear as detected
  
• Drawfunc 0x6 = Same as 0x3, but makes image appear as detected
  
• Drawfunc 0x7 = Same as 0x4, but makes image appear as detected
  
• Drawfunc 0x8 = ???, parameter does nothing
  
• Drawfunc 0x9 = Remap, parameter is pointer to remap table. Sadly warpoverlay can't be used to write pointers (It can use write only 2-byte values), using it here will crash the game.
  
• Drawfunc 0xa = Shadow, parameter does nothing.
  
• Drawfunc 0xb = Hp bar, parameter is pointer to owning unit. This requires very specific setup by bw and cannot be used by anything else than the hp bar image. The hp bar image can be changes to something completely unrelated though.
  
• Drawfunc 0xc = Warp texture, parameter specifies the grp frame. This is the one intented use for the warpoverlay command, but I think it is hardcoded to only work with protoss building warpins. But you can edit the WarpOverlayInit animation and it will work.
  
• Drawfunc 0xd = Selection circle, parameter specifies player alliance color (0 = red/enemy, 1 = green/own 2 = yellow/ally) or something like that. If you look at the selection circle .grp, you notice it only uses this "unknown/blue" color, more specifically palette entries 1 to 9. These get replaced by red/green/yellow as specified by the drawfunc parameter. However, if you use warpoverlay xxx to set the parameter to something larger than 2, it will overflow to other memory and use them as colors for the image! This overflow is version specific, and as such you might as well code code editing plugin if you need dynamic colors. In theroy you could overflow to colors which are used by terrain animation (color cycling), and create some neat animation. Usually it causes just garbage colors though
  The demo exe archon changing colors with mouse position uses this trick, though it uses different drawfunc (Hallucination one)
  
• Drawfunc 0xe = Override player colors, parameter specifies player. This overflows when parameter is greater than 11 (neutral), causing similiar garbage colors in place of player colors. Or you can use it to have every kind of unit look as if it is owned by certain player
  
• Drawfunc 0xf = ???
  
• Drawfunc 0x10 = Hallucination, parameter should be 0, or the colors overflow once again
  
• Drawfunc 0x11 = Warp flash, parameter contains state (in lowest byte), and timer (in second lowest byte). This is the warp flash effect that happens when protoss buildings are warped in, quickly fading away. "State" specifies which horizontal line in ofire.pcx should be used to draw the grp, and "timer" counts down from 3 to 0, increasing state by 1 when timer reaches 0. I can't think any use for this function other than very limited special effects
  

Alright, that was the warpoverlay command...
I'm not done yet though

gotorepeatattk in iscript may be thought as some sort of command which jumps to GndAttkRpt/AirAttkRpt if the unit is still attacking. In reality it never jumps, it only gives the permission to jump once cooldown (counted from previous AttkRpt) has been finished. This means, that if you would insert gotorepeatattk before attack/attackwith/attackmelee, bw will execute the attack command only if cooldown is high enough to reach it. This is what happens with marines in the demo I linked. If you look at the marine's iscript, I had to remove nobrkcodestart/end and add some waits for it to work though, so it is usually not ideal.

But now I got an idea of using the call opcode with early gotorepeatattk to detect if unit has attack speed upgrade/is stimmed. What call exactly does, is that it jumps to specified label, and every following return will jump to the command below latest call. You can't return back from two-or-more deep calls If you were to write iscript so that GndAttkInit instantly uses gotorepeatattk and calls an label, lets say AttackSpeedCheck, and this AttackSpeedCheck waits a moment, which is longer than cooldown after attack speed upgrade, but shorter than cooldown without, and after this wait it would call another label. Now GndAttkRpt will only contain one line: return. This would jump to either the line after first call, if the unit had attack speed upgrade, or to the line after second call if it didn't. I can't see any reason why this would not work.
EDIT: It seems that bw resets the return position every time it jumps to different animation

Other miscellaneous little understood iscript opcodes are __2d, which I call hidecursormarker. It hides the cursor marker sprite, the "green circle" appearing when you right click somewhere. And yes, it hides always this single sprite, no matter which image uses this command. Also ignorerest only pauses the script execution as long as unit has target, if it dies suddenly the command following ignorerest is ran.

Sorry for the block of rambling, hope someone finds this useful

tl;dr iscript can be used to one-way permamently cloak units, and gotorepeatattk with call/return can be used to emulate an imaginary "attackspeedupgradecondjmp"

Post has been edited 2 time(s), last time on Mar 31 2015, 4:03 pm by Neiv.

Did you find these just by screwing around with them or by disassembling? I've been disassembling some of the iscript functions and stuff to figure out better how they actually work, and if it's already done there is no need to do it again.

I disassembled warpoverlay as well as I could, and skimmed over some others, but disassembling it all is kinda huge task.. I haven't touched sprol/imgol etc at all because there's bit too many variants of them

I've already got most (if not all) of imgol, it's really actually pretty simple (basically just grabs an unused image id and adds it to a list found in the sprite struct and initializes everything). I haven't gotten to sprol since it's much more complicated, but I will soon. .. I've got quite a bit, but as I said in the shoutbox I haven't really studied it since I'm trying to get it all more readable at the moment.

But do you still have the most "fun" part remaining? That is comparing all those similiar commands and trying to understand where they differ?
Or do you have it done already?

It looks like I have all of the IMG ones except IMGULUSELO (which should just be a copy of IMGOLUSELO) .. I haven't started any of the SPR ones because I haven't gotten to the called functions to know what all the arguments are.

There may be some errors ... the // ? stuff I haven't checked since disassembling the functions


IMGOLORIG and SWITCHUL are the complementary OL/UL opcodes, so SWITCHUL is badly named. also SPRULUSELO does in fact not use *LO.

IMGOLUSELO arguments are not X/Y, they are the overlay type to use (in order listed in DatEdit) and the LO? graphic offset index within the lo? file itself (most use 0, as most only have 1). I've also learned about some of the sprite LO? usage, such as creategasoverlays, from creating a program to emulate iscript ...

Post has been edited 1 time(s), last time on Mar 3 2015, 10:32 am by FaRTy1billion.

nice findings! Not sure where I might use these but they certainly seem interesting.

So, image overlay opcodes seem to work like this?
-Imgul and imgol are the basic, well-understood opcodes without any surprises.
-Imgulnextid does not provide anthing over imgul, other than saving precious iscript.bin filesize.
-Switchul should be named imgulorig, and together with imgolorig they add overlays always at same point, even if parent image has inconsistent position due to sethorpos/setvertpos?
-Imguluselo and imgoluselo are useful if you need the x/y coordinates change depending on parent image's direction? LO? files had offsets for each direction, right?

Yes.

The only thing is imgulorig and imgolorig also have a check that calls "updateImagePositionOffset", but I haven't figured out what that function does yet (maybe it's the source of the additional behavior that seems to be attributed to the opcodes?).

Also I did IMGULUSELO today, as I suspected it was the same as IMGOLUSELO.

Alright, here is what I have so far ... Here I'll only point out things that in IceCC are listed as unknown or things that have quirks that might otherwise go unnoticed. When I'm actually done with figuring out all or most of the iscript stuff (which probably won't be any time soon) I'll write up more complete documentation with more specifics on each opcode too (such as updated flags, called functions, etc.).

I've loosely sorted them to make comparing similar functions easier...


Frame & Position functions

0x01 - PLAYFRAMTILE <frame#>
- plays frame# + tileset. If (frame# + tileset) is >= number of frames in the GRP, it does nothing.

0x1D - FOLLOWMAINGRAPHIC
- Copies frame, flipstate, and direction of primary image in the sprite. Reapplies palette?

0x2B - ENGFRAME <frame>
- Sets current image's frameset to <frame> and copies the primary image's direction. (Basically followmaingraphic, but without copying the parent image's frameset)

0x2C - ENGSET <framemult>
- Copes primary image's direction, and sets the frame to the primary image's GRP's frame count * framemult + primary image's frameset. (Use with caution! There are no checks on the multiplied framecount )

0x03 - SETVERTPOS <y>
- If the unit is cloaked, does nothing.

0x04 - SETPOS <x> <y>
- Does not have the SetVertPos check.

0x22 - TURNRAND <turnamount>
- if (randomshort & 3) == 1 then turn ccwise, else turn cwise. (Hence the "heavy bias" towards cwise. )

0x23 - SETSPAWNFRAME <direction>
- Seems to set the target coordinates, but I haven't done the called function yet.

0x37 - SETFLSPEED <speed>
- Sets flingy top speed for current unit/thing.



Weapon & Attack functions

0x1B - DOMISSILEDMG & 0x44 - DOGRDDAMAGE
- As best I can tell, these are exactly the same.

0x31 - ATTKSHIFTPROJ <distance>
- Sets Weapons.dat - Graphics Offset X for the unit's groundweapon to the specified parameter, and calls AttackWith 1



Jump & Control functions

0x1E - RANDCONDJMP <chance> <label>
- if (randomshort & 0xFF) <= chance then goto label

0x39 - PWRUPCONDJMP <label>
- Jumps if the curret image is not the primary image (I assume that means when a worker picks up a powerup the primary image becomes the worker).

0x3B - TRGTARCCONDJMP <angle1> <angle2> <label>
- if the difference between angle1 and the angle to the target unit is less than angle2, then goto label
- (angleToTarget - angle) <= angle2, do jump.
- Values for angle1: 0 = up, 64 = right, 128 = down, 192 = left. If angle2 had a value of 32, then there would be a 64 (90-degree) wedge centered on angle1 that, containing the target unit, will satisfy the jump.

0x3C - CURDIRECTCONDJMP <angle1> <angle2> <label>
- Same as trgtarccondjmp, except instead of angle to target unit it is the angle the unit is currently facing.

0x30 - IGNOREREST
- If current unit has a target, wait 10 and repeats, otherwise calls "IgnoreAllScriptAndGotoIdle" .. haven't looked in to what that does yet.

0x24 - SIGORDER <signal>
- OR-Masks thingy's orderSignal with <signal>, usually a bit or flag. (This was already documented elsewhere)

0x41 - ORDERDONE <signal>
- Like SIGORDER, but clears the given flags/bits.

0x2D - __2D
- Sets 0x652920 to 0. What that does is explained above.

0x0C - __0C (and also __3E and __43)
- Does not exit. Does nothing. Any invalid opcode (> 0x44) are also just ignored.



Images & Sprites

0x0B - SWITCHUL <image#>
- UL equivalient of IMGOLORIG
*EDIT* These seem to have something that relates to LO? files, but I'll have to look in to the called function then I'll confirm that here...

0x0D - IMGOLUSELO and 0x0E - IMGULUSELO <image#> <oltype> <graphicOffset>
- Creates image over/underlay using lo? graphicoffset, from the overlay type specified by oltype
oltype values (as ordered in DatEdit, which is correct):
0 - Attack
1 - Damage
2 - Special
3 - Landing Dust
4 - List-off Dust
Higher values overflow in to Images Array and will surely crash.

0x3D - IMGULNEXTID <x> <y>
- I don't know what "shadow level animation" is, this is just IMGUL x y (current image ID + 1)

0x38 - CREATEGASOVERLAYS <overlay>
- Creates image overlay with an id of 435 (Vespene Geyser Smoke1 Overlay) + overlay, at coordinates specified by the lo? offset also specified by "overlay".
- Uses oltype 2 - Special Overlay. If the vespene geyser resource amount is 0, then it subtracts 5 from the image ID.
This one is of interest to me because it may have the potential for some tricks. overlay is a signed byte, so it has the potential to reach some other image IDs.
Other values that share the same address as resource amount that may be able to be exploited:
- resource -> resourceCount
- nydus -> CUnit* exit
- ghost -> CSprite* nukeDot
- Pylon -> CSprite* pPowerTemplate
- silo -> CUnit* pNuke
- hatchery -> rect harvestValue
- powerup -> POINTS origin
- gatherer -> CUnit* harvestTarget
Maybe a particular overlay on a nydus canal if it has an exit? Or on a nuke silo if it is loaded? (assuming, of course, the value is 0 if there is none)

0x0F - SPROL <sprite#> <x> <y>
- Works as advertised, except if called by a bullet launched by a goliath (regular or hero), and if owning player has goliath weapon upgrade or unit is hero & playing in Brood War, then it will instead create a sprite with an ID of 505 (Halo Rocket Trail).

0x10 - HIGHSPROL <sprite#> <x> <y>
- Creates a sprite underlay, with no extra conditions, checks, or special functions.

0x11 - LOWSPRUL <sprite#> <x> <y>
- Creates sprite at elevation 1 (I don't know if that is the lowest, I just felt it worth mentioning.)

0x13 - SPRULUSELO <sprite#> <x> <y>
- Does nothing if the calling unit is cloaked, else creates a sprite at the same elevation. Nothing related to lo? files (iirc this is only used by high templar, which has no lo files specified). Inherits direction.

0x14 - SPRUL <sprite#> <x> <y>
- Does nothing if the calling unit is cloaked. Inherits direction.

0x15 - SPROLUSELO <sprite#> <oltype>
- Creates sprite with lo, see IMGOLUSELO for oltypes. Inherits direction.

0x42 - GRDSPROL <sprite> <x> <y>
- Checks if a marine can fit at x,y. If it can, creates overlay sprite at x,y.



Hopefully I'll be able to provide more information as I learn more quirks about these and delve deeper into called functions.

Post has been edited 6 time(s), last time on Feb 24 2016, 4:54 am by FaRTy1billion. Reason: Shield lo is a different array

grdsprol actually uses units.dat boundaries for marine, or just a set of constants that equàl marines?

So using this, would I be able to make detection-needing cloaked broodlings when they are not moving, and visible broodlings when they move? This actually fits what I was trying lore-wise a lot better. I'll probably need help.

While I'm not exactly sure about all these cloak tricks, it seems that only the following are possible:

1) Any unit can permamently cloak using iscript, but this cannot be reverted, it will drain energy, and it will appear always as "enemy cloaked unit", even if you own it.

2) Unit having ghost's/wraith's cloaking skill can be allowed to decloak only when certain parts of iscript are ran, but they will always be able to cloak.

"Visual cloak", which does not require detection but looks like normal cloak is easier to control.

I have not tested what happens when bringing detectors are near these "pseudo-cloaked" units, or if can they run out of energy and become decloaked anyways. Also it would be interesting to know how burrowing works with all this, as burrowed units work similiarly to cloaked units.

If you need broodlings to swap between cloaked/uncloaked states, you have to use some code-editing plugin
(At least as far as I can tell)

Success! I have created nuke silo that looks different when it is loaded!



Here's what I did:
1) I searched with datedit images.dat for an unused image which is close to image 425 (Vespene smoke), and has another unused image located at ID-5. I could not find two unused images, so I used image 510 (Guardian acid spore hit), and image 505 (Unused plasma drip).

2) I changed image 510's iscript to the following:

The image will simply disappear without even showing anything.

3) Image 505 got more changes: Its draw function was changed to 12 (Warp texture), and .grp was set to terran\nukesilo.grp. Any normal overlay would have worked as well, I just wanted to experiment with the warp texture Iscript was changed to the following

It loops the warp texture back and forth, taking 20 frames total.

4) I modified nuke silo's iscript to contain "creategasoverlays 75" command, like this:

The magic number 75 comes from Image IDs: 510 - 435 = 75. Having "wait 1" before creategasoverlay is necessary to prevent crashing, it seems that active iscript unit is not set when first frame of Init/Built script is executed? It is important to have a loop calling constantly creategasoverlays, as that keeps the game rechecking whether the silo contains nuke or not. Because of that, both created images can't have infinite loops, or there would be images created on top of each other until the 5000 image limit is reached. Wait 20 was how long it takes for image 505 to disappear.

5) Creategasoverlays also requires the silo to have an LO? file in the special slot. As I was too lazy to edit images.tbl to create new LO? file, I just took unit\terran\starport.lod and broke starport dust overlay The overlay had to be changed in pyLO as following:

That is a lot of (127, 127)... There is copypaste for each frame (Completed silo and AlmostBuilt silo), both of them have 75 unused offsets, and the 76th is used for placing image - because I used creategasoverlays 75.

6) Loaded the changes and it works perfectly!

As creategasoverlays uses signed byte, it is only possible to use creategasoverlays with values -128 to 127. However there is no LO? editor that allows specifying negative indexed offsets, so one would have to hex edit them in. Maybe we need an LO? editor which is able to handle this abuse case of creategasoverlays

Post has been edited 1 time(s), last time on Mar 4 2015, 4:07 pm by Neiv.

We're talking about an OR mask, not AND mask?

Cool feature Neiv. I'm not sure if I would use it, I'm usually averse to salvaging other assets, but that certainly looks neat.

It's an OR mask, as it sets the flags. It would be actually interesting to disassemble the orders and see where they use these sigorder flags. Only issue is that there are 189 orders (and the meanings of the flags are usually easy to guess)

You can always relocate the salvaged images and update their sprites to point to relocated images, it's just more work. Just avoid the ones which seem to have some hardcoded surprises

Okay, that's good. I'm supposed to know this since I have a feeling Farty was referring to the article I wrote about using SIGORDER with plugins. x3

Indeed, order disassembly would be a huge asset, especially since there are at least a few that are unknown. I have a feeling that it also has to do with how the interface responds to them, since certain orders, particularly with Cast Spell ones, will cause the interface to prompt the user for a target. Having the ability to define more cases wherein the user is asked to specify a target would go a long way to creating entirely new spells that minimally impact existing orders and spells.

Ye, but that usually takes so much work! D:

Nice work guys.


You could always use the source version of PyMS and modify PyLO to your liking. I wouldn't mind doing some stuff as well, all this new stuff is giving me the itch to work on this stuff again

It actually checks with the marine:


Awesome! So it does work, just requires a bit of work. xD

Sorry, I didn't notice I just put 'masks' xD

Only 5 sigorder flags are ever used: 0x01, 0x02, 0x04, 0x10, and 0x40 (which is only on valkyrie, so I assume it's to do with afterburners).
Orders are quite complex ... I got the assembly for all the relevant functions for junk yard dog and there are a lot in there. Though I'm sure once you start with them all the functions will be recycled (as they are either other orders, functions for setting orders, or AI functions), making it significantly less work. Although I'm sure JYD is a particularly complex order (since it seems to queue lots of different orders).

EDIT:
It might not work if detection relies on the cloaked or needs detection flags.

I didn't really consider the signed part with the lo? file ... it will just read backwards in memory to before the lo?s position in memory, and I don't know what would be there (unless it's more lo? files).

Post has been edited 2 time(s), last time on Mar 4 2015, 8:05 pm by FaRTy1billion.

Nice, thanks for the clarification on the Marine. So odd, I wonder what one might use it for?

I presume that orderSignal persists across frames. I still haven't tested this conjecture lol.
My other conjecture is that in general, the game only accesses orderSignal in a few specific contexts, so my personal reckoning is that it is generally safe to use any flags that aren't normally set on each particular unit. In my personal maps, I haven't seen any problems with this sort of usage.