Hey guys, I'm Shirsh. This guide has some very basic information about editing game graphics for an agent, guard, or NPC in your Invisible Inc. mod. To learn more about modding Invisible Inc., you should read the modding notes written by Jason Dreger from Klei, you'll find those notes in his API example mod, also available on the Steam Workshop.
For starters, check out how Klei's 2D animation works:

http://www.gdcvault.com/play/1020165/2D-Animation-at-Klei

1. API Example Mod: http://steamproxy-script.pipiskins.com/sharedfiles/filedetails/?id=551989114 It contains Klei's kwad builder and several animation files, which are essential as a base for your own character.
2. Strelock's latest KWAD Tool: https://github.com/Psimage/KWADTool/releases Can be useful for unpackaging kwad files.
3. Graphic editor of your choice. I use a raster editor (Photoshop or Gimp), but you can use a vector editor if you prefer. This guide won't cover how to use these graphic editors, but there are many tutorials out there for it if you're interested in learning.
4. Total Commander or a similar file manager will save you an incredible amount of time. It can be easily used with the kwad tool, kwad builder, for zipping/unzipping stuff, and to copy/paste images from place to place (which you will do every three minutes). It's shareware: http://www.ghisler.com/download.htm
5. A small and fast text editor with lua syntax theme like AkelPad or Notepad++ can be very useful. This is mostly used for the lua part of mod (you will need to activate built-in plugins, especially "coder" plugins). They're totally free and opensource: http://akelpad.sourceforge.net/en/download.php https://notepad-plus-plus.org/download/v7.5.8.html
6. A graphic viewer is convenient. If you don't happen to have one, here's link to free XnView (scroll page down a bit for free download link): http://www.xnview.com/en/xnview/#downloads

In the game's folder you will find kwad files. KWAD files are compact light-weighted package files where the game's graphics and sound data is stored. The' KWAD format is unique to Klei, which is why you will need the specialized tool to extract them.

As you can guess, gui.kwad contains gui related files, movie.kwad contains movies, etc. Our first goal is to explore how the data is stored and sorted in characters.kwad, anims.kwad and gui.kwad:

• characters.kwad - The primary file to see what we should do. This KWAD contains sprites and symbols for all components that move in the game: agents, guards, drones, guns.
  
• anims.kwad - Mostly holds different "not character related" animations (for example for different static props like elements of decor) used in the game. Also stored in this folder are the animated portraits called "portraits."
  
• gui.kwad - Contains all gui files, but we mostly just need the images for the agent selection screen, agent splash art, and icons for items. Maybe small portraits of guards for the debriefing screen if you're making a guard mod.

For you to see the contents of these files, you need to extract them using the KWAD Tool. It works through command line. Total Commander (TC) provided a very good way to use the command line:
As you can see, I moved anims.kwad into the KWADTool folder (it stays unchanged so we don't need to copy it, just don't forget to move it back after extraction). On the right TC's panel is active (ie panel where KWADTool folder is opened). Then type "KWADTool -i anims.kwad -o outputDir -e all" into the command line: when I press "Enter" the extraction process will start. For more info about commands check KWADTool info page: https://github.com/Psimage/KWADTool

UPDATE: now with KWADTOOL v 1.1.0 alpha you'd better use command like "KWADTool -i anims.kwad -o outputDir -e anims": it takes longer, but the extracted png sprites will be 100% ready to modding! They will also come with build.xml (it contains info about coordinates of sprites, useful if those are different from Decker's and Banks, like with hacker antenna or something)

You can also save yourself the trouble and access the graphical kwads here, where I uploaded them: https://drive.google.com/drive/folders/0B4g2vwkLZCIwRzl2YlcwQnA1dGs

Now that you've extracted them, just make an o_o expression on your face and explore the output folder for hour or two...

Your mod files are stored in the Invisible Inc. game folder under /mods. Look for the the API example Mod folder (it should be named workshop-551989114) and you'll find the "example anim files" subfolder.

In case you're not good at navigating folders: right click on Invisible Inc in your library in Steam client and press "properties", in a pop-up menu there will be tabs, open the one called "Local files", there will be button "Browse local files". Click it and it should open the game's folder for you, there should be a "mod" subfolder, open it and you should see a bunch of folders named "workshop-xxxxxxxx" (mod number instead of xxxxxxx, in this case workshop-551989114).

Here you'll have a list of anim files. We have the following available to use as a source:

• Banks
  
• Decker
  
• Three types of drones
  
• Two guns (handgun and rifle)
  
• Portrait of common K&O guard

But wait, there are more files?

Right, there's a main animation build ("agent_banks"). This is animation of the character on screen that runs around and does things. The grp/grapple animation build ("grp_agent_banks") is the animation of the character when they are interacting with another character, e.g. attacking a guard or dragging another agent around. The overlay/wireframe build ("overlay_agent_banks") is a grayed out, silhouette-like image of the character that is used while in cover and is layered over the game graphics (beside gui).

• The exact same scheme is applied to guns. For example, the grp gun animation is seen on a couple of frames when you grab/drop a body, so don't miss one if you want to make a new gun. Also note that images.kwad contains images for items when they are dropped on the floor (despite its name it does not contain many other images so you can skip it most of the time), and while making your custom image.kwad you can add a new look for a dropped gun too.

As you know from the GDC page, the animations for the game are made in Flash. Those anim files are the result of exporting a flash animation to a state that the kwad builder can easily interpret, break/convert into several types of files understandable by game's engine (.adef, .abld and sprites/spritesheet, etc.) and packed into a kwad.

Useful for us: the anim file is basically a .zip archive that contains a log of export (just skip it), two xml files (animation.xml, which defines the animation state, and build.xml, which defines the different parts of the agent sprite that move) and a whole bunch of png images. Just open/unpack it with Total Commander.

It's possible the anim.zip contains more sprites than you want or need: e.g. sprites for Decker's hat when your agent will not need a hat. The simplest way to remove unnecessary sprites is to open build.xml and remove the section that defines that part of the sprite.

E.g. if you remove the lines:

<Symbol name="fac_clr_00" >
<Frame framenum="0" duration="1" image="fac_clr_00-0" w="28" h="40" x="0.1255000000000006" y="-6.349499999999999" />...
...<Frame framenum="4" duration="1" image="fac_clr_00-4" w="32" h="36" x="-0.22449999999999992" y="-5.3245" />
</Symbol>

...your agent will be faceless, so check the name of an unneeded piece, search for <Symbol name="Name_You_Need_00" > and delete the corresponding lines in that block.

Strelock has now updated the KWADTool: v1.1.0 Alpha extract png sprites/symbols with their invisible alpha spaces around. But to do this manually, you must use the command like "KWADTool -i your.kwad -e Anims -o yourDir"
See details on: https://github.com/Psimage/KWADTool/releases/tag/v1.1.0-alpha
So now if you want to combine or edit some character's appearance you don't have to manually put hundreds of sprites over Decker's or Banks sprites but simply combine extracted pngs!
You may need to copy/paste their symbol info from build.xml to preserve the right coordinates, like one for face removing as above.

Some small tips:

• Photoshop's "multiply" and "color" layer's types are VERY useful to get colours that will match the game's assets. For example, for my Mist mod I was using archive Shalem's chest sprite over the jacket and the Siren's hips with multiply on the shorts (90%, so it wouldn't be pure greyscale). To make the skin similar to the Siren's skin, I changed saturation to -43 from the default colors of Banks or Internationale's skin. Use default game colors as a base.
  
• Gimp and Photoshop have a "magic wand" tool that selects all areas similar to the colour you just picked, with an adjustable "tolerance" level. You can use these to select similar blocks of colour quickly, just make sure the selection is neat, especially around anti-alised boundaries.
  
• Using adjustment filters (like "hue/saturation/lightness") is very useful to make consistent changes to sprites. You can also select for the change to only apply to certain hues. For example, if you want to recolour archive Sharp's green coat into dark blue, a simple way to do it would be to select the green AND yellow in Hue/Saturation/Lightness, switch the hue to blue, reduce the lightness and possibly the saturation, save it as a preset or just remember/write down the exact value changes, and apply this change to all of Sharp's coat sprites. You can also speed things up with Photoshop's Batch Processing method (https://helpx.adobe.com/photoshop/using/processing-batch-files.html) but be sure to double-check after this. Note that many agent and portrait anims have blue highlights! Take care to preserve them.
  
• If you choose to paint over sprites directly, instead of non-transparent colors, use e.g. 90% and 50% opacity layers over base sprites. Save colour presets and values/write them down if you want to be sure they're consistent.
  
• You should check every change "in action." Added a new hat? Copy files into anim, build kwad, and run the game. Making a guy? Send him on mission with Shalem and compare. Making a gal? Put her on mission with Internationale and compare. Making a rifle...
  What important is that they should match the characters already in the game as much as possible, both in look and in coolness: the gal looks lame near Int? Add some nice details. Internationale overshadowed? Think again, maybe you added to your new gal too much of something and need to simplify her design. Also, check different corporations because each of the corporation's shaders change a lot.
  
• Previous state led to requirement of effective virtual working space layout. I personally use two Total Commander windows.
  In the first window I have a folder full of new sprites and opened target anim that is staying in proper builder's folder "anims/characters/agents/". I edit sprites, press ctrl+A in new sprites folder and then press F5 to overwrite anim.
  In the second window I have builder/exe on one side and the mod folder on other. I build the kwad and press F6 to move it from "out" folder to mod's (more about builder's folders later).
  
• To have less unnecessary work, try to edit sprites with same "last number" first: for example cst_clr_00-1, fac_clr_00-1, abs_clr_00-1 etc. This way, in game you'll have a full set of character's animation from one angle/viewpoint. When there will be almost what you're looking for, edit sprites for other views (with possible comebacks to change details).
  
• Start with character "on the field". At some point, switch to his animated portrait. Then go back and make corrections in the in-game character animation again. Go back and forth between the portrait and in-game character until you get what you want. Even though their artstyle is quite different, the portrait and character should have a synergy. If the portrait doesn't work with that haircut but works with the in-game character it's better to just change a character's haircut.

This is the most time-consuming part, so get inspired and get working.

Jason's modding notes and the readme that comes along with the builder should be enough to know how to use it. I'll just add a couple of tips:

• In my experience, the builder refused to work from Program Files and other adjacent places, but works great when I put it to "C:\builder"
  
• You may skip the part with sprite atlases in the builder when you do "inner builds," and only add it for the release build. It takes longer to generate but nicely reduces the kwad size (very cool when you have many anims).
  
• Don't forget to make backups of source files sometimes. You wouldn't like recreating 107 cloak sprites, I'm sure.
  
• You'd better use the default game paths (it isn't always essential, but it's not fun to search for which file is causing trouble when there's so many of them and everything isn't working).
  
• You can store portraits in the same kwad as the character's animations (even if the game doesn't store them like this). The path is anims/portraits. It will look like "PackageFolder( package, "./anims", true)" in build.lua

For making animated portraits, let's look at the guard build as an example:
Standard guard proportions can be changed by editing the xml file. Portraits do not have much eye movement. It's important to note that eyeballs are paired (this can be a big problem, but more on that later).
This time you will need to not just edit the sprites but also edit the build.xml file (to edit it quickly, use AkelPad/Notepad++ or something) to change the sprite's coordinates, depending how drastically you're changing the sprite. In build.xml you'll see strings like this one:

• <Symbol name="nose" >
  <Frame framenum="0" duration="1" image="nose-0" w="67" h="132" x="0.02549999999999919" y="-0.7994999999999983" />
  </Symbol>

You need a w="67" h="132" to change the coordinates of the nose, here's how it works:

As you see above, it's a direction for increasing or decreasing the numbers.
Want to move your image up? - add numbers to h.
Want to move you image left? - add to w.
Want to move your image right? - make w lower.
Zero is not right enough? Make it w ="-67". Experiment and find what you like.

Note that it doesn't work in the coordinate system of the game player, but in the coordinate system of the sprite (so you will move sprites at some angles).

• Be careful, eyeballs are a bit tricky!
  Eyeball-0 and eye_white-0 sprites are not separated for different eyes, the distance between two eyeballs is defined by the "w" number! When you make "w" lower, the eyeballs move closer to each other, and when you make "w" bigger they move to the opposite edges of the face. This will probably take some trial and error to get right.

As before with characters, check every change in game and take a screenshot every time! Comparing these screenshots is very useful as you move pieces around.

To add your new portrait to your mod you simply need to use the following code in guarddefs (for guards) or in agentdefs (for agents), these two strings:

• profile_anim = "portraits/portrait_animation_template",
  profile_build = "portraits/xxxx",

Where xxxx is name of your new portrait build.
You really should review how agentdefs and guarddefs work in the API example mod.

And if you decide that you can have a static image instead of animation, use a

• profile_icon = "gui/LOCATION OF ICON"

While profile_image = "gui/profile_icons/xxxx.png" is used for small guards portraits used on debrief.

Here's my animated gif. It doesn't cycle so you'll probably need to reload page or open it in another tab/browser:

However, you are NOT limited to using the guard portrait as a base! You can use ANY animated portrait as the 'parent' for a build. For example, in the N-Umi mod, I used:
profile_anim = "portraits/lady_sharpshooter_face",
profile_build = "portraits/nu_lady_face",
That way, N-Umi uses the same portrait animation as Nika, much more articulated than the guard's animation!

• You can change the size of any sprite as you need. But remember that build.xml will always use the upper left corner of the png as the coordinate point in build.xml. On one hand, this means that if you're just painting within the empty area of the png, you don't need to make changes to build.xml. On the other hand, you can change the png dimensions freely as long as you only expand the image to the right and bottom. Want a beard? Extend a hair sprite longer to the bottom and put the beard there. Want some fancy semi-transparent helmet monitor or animated portrait? Simply stretch the ear or hair canvas to the right and attach everything to it.
  
• You should be able to edit static images and icons by yourself, I'm sure. But when/if you make a 1024x1024px agent picture for the upgrade screen (i.e. the splash art), you should take archived Prism or archived Sharp image to use as a base. All other agents have a 1024x1024px picture. Both archived Prism and archived Sharp have a larger 3172x3172 px size. After editing, save your new file at 1024x1024 size (bicubic sharpening rules) and it will be much crisper than if you try to work with 1024px from the start. Plus you'll probably have a better understanding of Cheoljoo Lee's skill and talent in creating them.

Via anim.xml you can change default animations, I did it only once - for the Spider Drone in the N-Umi mod, and I only copied data from the anim.xml of a drone (an old one, unused now, it's stored in the API example mod) to the anim.xml of the new drone which was based on the default Obake drone. It was data about lights on the side panel of the drone, only one or two sprites but it took a lot of time for all the animations in five directions. So changing anim.xml is possible, just tedious and requiring a lot of troubleshooting to get the coordinates right.

To use your animation, for example for a male agent's unarmed state, you'll need to use this trick in scripts.zip/animdefs.lua:

anims = util.tconcat(
commonanims.male.default_anims_unarmed,
{"data/anims/characters/your_agent.adef"}),

I didn't experiment much, so you'll need to try different things on your own, check Tony's animation in animdefs.lua for reference.

Another thing I should say: you don't need to always have anim.xml in your custom .anim, but if it's not there, it will be impossible to properly recreate the source via KWADTool (it will fail to extract it as animation while other ways of extracting do not preserve information about transparent spaces around sprites and build.xml). So I'd not recommend it.

Another thing: in "scripts.zip/client/animdefs.lua", the character animation is described in tables like this:

kanim_stealth_male =
{
wireframe =
{
"data/anims/characters/agents/overlay_agent_deckard.abld",
},
build =
{
"data/anims/characters/agents/agent_deckard.abld",
"data/anims/characters/anims_male/shared_hits_01.abld",
"data/anims/characters/anims_male/shared_attacks_a_01.abld",
"data/anims/characters/anims_male/stealth_basic_a_04.abld",
},
grp_build =
{
"data/anims/characters/agents/grp_agent_deckard.abld",
},
grp_anims = commonanims.male.grp_anims,

anims = commonanims.male.default_anims_unarmed,
anims_1h = commonanims.male.default_anims_1h,
anims_2h = commonanims.male.default_anims_2h,
animMap = AGENT_ANIMS,

symbol = "character",
anim = "idle",
shouldFlip = true,
scale = 0.25,
layer = Layer.Unit,
boundType = BoundType.Character,
boundTypeOverrides = {
{anim="idle_ko" ,boundType= BoundType.CharacterFloor},
{anim="dead" ,boundType= BoundType.CharacterFloor},
},
peekBranchSet = 1,
},

It was better explained in modding info file in API Example mod, but I want to say this about the animMap.
It's a map of animations: It contains data about which animation should be played in what game situation. E.g. a drone's state/event "idle_ko" should play the animation "idle_closed", and for a "walk" it should play the "move" animation (but you can change it to idle_closed" and the drone will be sliding on the floor).

There are several default animMap types now: AGENT_ANIMS, GUARD_ANIMS etc, but you can make a custom one, for example check the N-UMI mod - scripts.zip/animdefs.lua

here's the animMap table of the Spider Drone:

animMap = {
idle_ko = "idle_closed",
cover = "idle",
pin = "idle",

walk_pre = "move_pre",
cover_run = "move_pre",
walk = "move",
walk180 = "move",
snk = "move",
run = "move",
walk_pst = "move_pst",
run_pst = "move_pst",
snk_pst = "move_pst",
pin_pre = "idle",

shoot1 = "shoot",
shoot2 = "shoot",
shoot3 = "shoot",
overwatch_pre = "shoot_pre",
overwatch = "shoot_pre",
pinshoot_pre = "shoot_pre",
pinshoot = "shoot",
pinshoot_pst = "shoot_pst",
pin_stand = "idle",
tinker = "shoot_pre",
tinker_loop = "shoot_pre",
tinker_pst = "shoot_pst",

hitfrt = "hit",
hitbck = "hit",
hitfrt_pst = "hit",
hitbck_pst = "hit",
cover_pre = "idle",

ko = "close",
get_up = "open",
get_up_pst = "open",
idle_pre = "idle",
lean_pre = "close",
lean = "idle_closed",
lean_pst = "open",
hide_pre = "close",
hide = "idle_closed",
hide_pst = "open",

use_comp = "shoot",

hide_peek_pre_L = "open",
hide_peek_pre_R = "open",
hide_peek = "idle",
peek_L = "shoot_pst",
peek_R = "shoot_pst",
hide_peek_pst_L = "close",
hide_peek_pst_R = "close",

door_peek_pre = "shoot_pre",
door_peek_pst = "shoot_pst",
peek_fwrd = "shoot_pre",
peek_bwrd = "shoot_pre",
peek_pst_fwrd = "shoot_pst",
peek_pst_bwrd = "shoot_pst",
lean_peek_pre_R = "open",
lean_peek_pre_L = "open",
lean_peek_R = "idle",
lean_peek_L = "idle",
lean_peek_pst_R = "close",
lean_peek_pst_L = "close",

overwatchcrouch_melee_idle = "idle",
overwatch_melee_pre = "idle",
overwatch_melee = "idle",

hide_throw_L = "shoot_pre",
hide_throw_R = "shoot_pre",
hide_throw_pst_L = "shoot_pst",
hide_throw_pst_R = "shoot_pst",

throw = "shoot_pre",
throw_pst = "shoot_pst",

lean_throw_L = "shoot_pre",
lean_throw_R = "shoot_pre",
lean_throw_pst_L = "shoot_pst",
lean_throw_pst_R = "shoot_pst",

pick_up = "move_pst",
use_door = "shoot_pre",
use_door_pst = "shoot_pst",

hide_reload = "open",
lean_reload = "open",
reload = "shoot_pst",

revive = "shoot_pst",

shrug = "idle",
},

As you can see, for most actions the Spider Drone uses "shoot_pre" and "shoot_pst", and drone's open/close for in-cover animation, a lot of idle everywhere: trick explained.

ON the left, you have "events", i.e. what the game asks to do. On the left, which animation will be played for this - on the right in brackets. I dug through several files to not miss any events, feel free to use the left side as a template if needed.
I can't remember where I get those "shoot_pre", "move_pst" things, sorry, maybe in anim.xml, so it still will be better if you investigate these files yourself. Maybe it was somewhere in commondefs, damn, I totally forgot.

So you can experiment with things like exchanging sneak and run animation etc, I guess you need to make a table with default animations first though. If I make one, I'll post here for sure.

Feel free to ask questions if you have any, there's a chance that I can help answer. If there's anything missing, feel free to tell me, as well. I already said, my English is a quite broken, but Colonel_S edit this document when will he has time for it. Sometimes he misinterpret some of my broken phrases though, so I rewrite them (infinite cycle).
Now it also getting edited and upgraded by Hekateras, unlike me (Shirsh) she much better with PS and knows tricks I have no ideas about.

Have a nice day and awesome holidays. Bye.

Last Edited by Colonel_S January 6, 2016
After that edited by Shirsh (some broken links fixed and couple of new words) January 15, 2016
and later, April 24 and 25
Last edited by Hekateras on July 29th, 2018