View source for Koikatsu/Extracting

{{Note|This article needs to be rephrased to be more impersonal.}}{{Stub}}

= Koikatsu Porting for cuties like (You), (You), and (You) =

This guide was originally by nabutso#3918 but updated by Beef#3096. The way I port koikatsus isn't the definitive way, this is just way I get things done.

If you find out cool/easier ways to do something, do it! Let me know on discord too (Beef#3096) and I'll try to add it to the guide.

== Required Downloads ==

* Koikatsu: [https://www.betterrepack.com/public/ Koikatsu BetterRepack RX7] (or whatever the latest version you can find is). This will contain everything you need to use Koikatsu for either playing the game itself, and editing, or creating cards (characters).
* The updated [[Media:PMXExporter.dll.zip|PmxExporter.dll]]. Edited for me by some dude on the Koikatsu discord (https://discord.gg/VXbT3PD). Better than the IQE exporter or whatever, and works with the bonemod.
**A better PMX exporter is being developed as of September 2021 by June.
* [https://www.mediafire.com/file/z1w91t5keytvq3r/ninjaripper1.7.1_with_new_script.7z Ninjaripper] for extracting the textures
* [https://www.imagemagick.org/script/download.php#windows ImageMagick] for quickly decomposing the images, too.

I <b>recommend</b> [https://www.gimp.org/downloads/ GIMP Image editor] (especially if you don't want ImageMagick) or [https://www.dotpdn.com/files/paint.net.4.2.7.install.zip paint.net] for image editing.

* [https://blender.org Blender] 2.9
** [https://github.com/GiveMeAllYourCats/cats-blender-plugin CATS]
** [https://github.com/fblah/ShapeKeyTransferBlender Shape Key Tools] (Download as ZIP to downloads, then install the ZIP)
* VRChat SDK

== Card Resources (not an exhaustive list)==

Koikatsu cards store the information for the model. You can load a card in whole or in parts, so you can easily swap outfits!

* [https://www.pixiv.net/search.php?s_mode=s_tag_full&word=%E3%82%AD%E3%83%A3%E3%83%A9%E9%85%8D%E5%B8%83%28%E3%82%B3%E3%82%A4%E3%82%AB%E3%83%84%29 Pixiv card release tag]
* [https://illusioncards.booru.org/index.php?page=post&s=list&tags=koikatsu Illusioncards booru]
* [https://boards.4chan.org/h/catalog#s=kkg Koikatsu General on /h/]

== Getting ready to launch Koikatsu ==

If you're starting Koikatsu for the first time just to play around, you should stop reading now and come back to this guide when you're ready to actually port something.

If you do not run through Ninja Ripper, you won't be able to extract the textures. The PmxExport may cause gameplay problems, too. Try adding it only when you're porting.

# Unzip Koikatsu
# Place the PmxExport.dll in your <code>Koikatsu\BepInEx</code> folder.
# Unzip Ninja Ripper and put it anywhere
# Open Ninja Ripper. Change the exe target to point to your Koikatsu.exe
# Click "Run" in Ninja Ripper.

== Loading a card, exporting the model and texture ==

=== Things you should know beforehand: ===
'''Accessory hair by default will export with conflicting weights.''' It is easy to separate the hair weights for dynamic bones, though it is tedious.

If you don't want to deal with creating new hair bones and separating them, <b>use the normal hair selections.</b> Also if you want to port a model with a lot of pieces of hair, you can port normal hair more than once. 

The pose and mesh are exported as-is. In addition to the way the eyes are facing, the facial expression, etc., that means <b>if your model is wearing clothes that tighten/hold the breasts, they will export that way</b>... usually.

If you want the breasts to look right, you may need to export the nude version later and fit the clothes around the breasts instead. It depends on what clothing you picked.

# Click "Char Maker", then "Female". If it's a Male card then click "Male" instead. Note: If you exit the Char Maker, restart the game (something to do with the exporter being weird).
# Next to the "BGM ON/OFF" button at the top is a file icon. Click this to see your cards. Click your card and click "Load" at the bottom.
# Select the outfit you'd like to export. Note: All layers of the current outfit are exported (Naked, Underwear, Clothed), but only the current outfit is exported.
# Using the Control Panel on the right, Disable Blinking, set the Gaze Direction to Upward with Eye Adjustment Tuning at 0, and Pose as T-Pose.
# Click "Export" at the top left (that's the PmxExporter, this exports the model). When the export is finished, press F9 to extract the textures with Ninja Ripper.

The default destination folder for the PmxExport (model) export: <code>C:\koikatsu_model\xxxx\..</code>

The default destination folder for the Ninja Ripper (texture) export: <code>C:\Users\(You)\NinjaRipper\_NinjaRipper\..</code>

== Blender - SAVE EVERY TIME YOU DO ANYTHING, AND SAVE TO A NEW FILE ==

# Import the PMX into Blender using the CATS Blender plugin.
# Use Fix Model but with "Combine Same Materials" unchecked. This will break your hair if you forget to do it. This is because the hair <i>appears</i> to be the same material to CATS.
# Separate by Material in CATS. <b>Separating by materials will drastically reduce your filesize and remove useless shape keys.</b>
# <b>Remember to join all the meshes that will make up your Head/Face etc though, so that eye tracking and visemes all works correctly.</b>
Then, rename the mesh that contains your Body/Face etc to Body (for VRChat stuff to work properly). In the end, your Blender hierarchy should look [[Media:589047fd601048ea80cdc1f7a9084ff7.png|something like this]], with the Body mesh materials shown as well.
# For optimization's sake, I recomend deleting any meshes or materials you do not intend to use, as well as combining any identical materials manually (these will be appended with .001, .002 etc). <b>If you exported with accessory hair, leave your hair alone for now.
leaving it seperated will make dealing with conflicting weights easier</b>
# Delete the shadowcast mesh, its use to cast shadows in koikatsu scenes, it does nothing for us in VRChat.
# In my experience, the Lower Eyeline mesh/material (cf_m_eyeline_down (Instance)) is useless because it isn't affected by it's shape keys. I delete this mesh/material. We will recover your eyeline easily later in Unity.
# These [[Media:869420ee66be046364f886de2c7515a6.jpg|2 vertices]] in your face will interfere with our eye tracking, delete them.

== Accessory Hair ==
Like I mentioned earlier, if you export with accessory hair then some pieces have weights that share the same name due to accesory vertex groups only be allowed the names joint 0 through 5

# In CATS > Model Options > Show More Options you need to click on delete zero weight vertex groups. That will clean up 400+ vertex group list so you can only focus on the hair
# On your character there probably is only 1 bone chain for multiple parts of your model, what you need to do now is create new bone chains and rename the vertex groups to those new bones to seperate the weights
# Rinse and repeat for any other conflicting parts

== Blinking + Eye Tracking ==
We need to create a mix of shape keys for Blinking, as Koikatsu moves individual parts for each.

A (probably) universal blink can be created by combining the <b>eye.face.f00_def_cl</b> (aka eye, face, default, closed... I think) and <b>eyeline_u.elu00_def_cl</b> (aka eyeline upper, default, closed) keys. Take note of the strength of the blink when creating the mix. Check the eye_naM.Nam00_def_cl shapekey too!

You can combine shape keys in Object mode in Blender. Select a Shape Key and [[Media:E4ef940cb720deb72100ad3aca52f3c0.png|set it's value to 1.0]], and then select another and set it's value to 1.0, etc. You can combine as many as you like.

Use this new combined blink shape key for creating native VRChat blinking or your own blink animation in Unity later.

The eye bones themselves are already properly weighted: <b>Eyex_L</b> and <b>Eyex_R</b>.

I use a high Eye Movement Range (max in CATS), but you can adjust this to your liking.
Depending on the size of your eyes, you may want to move the eyes (the mesh, not bone) backwards a little bit since they may clip outside while tracking. Try this later if you experience it.

== Visemes ==
Similar to Blinking, the Visemes are a mix of other shape keys.

There are seperate keys for Mouth, Teeth, and Tongue movements. You may want to consider creating your own "Hide Tongue" and "Hide Teeth" Keys to make it easier to make Visemes and do gestures later.

I recommend the following shape key mixes for Aa, Oh, and Ch:

;Aa
:1.0 kuti_face.f00_a_l_op
:1.0 kuti_nose.nl00_a_l_op
:1.0 kuti_ha.ha00_a_l_op
:1.0 kuti_yaeba.y00_a_l_op
:1.0 kuti_sita.t00_a_l_op
;Oh
:1.0 kuti_face.f00_o_l_op
:1.0 kuti_nose.nl00_o_l_op
:0.5 kuti_ha.ha00_kisu_op
:1.0 kuti_ha.ha00_a_l_op
:0.5 kuti_yaeba.y00_kisu_op
:1.0 kuti_yaeba.y00_a_l_op
:1.0 kuti_sita.t00_def_op
;Ch
:0.5 kuti_face.f00_e_s_op
:0.5 kuti_face.f00_o_s_op
:1.0 kuti_nose.nl00_e_s_op
:1.0 kuti_ha.ha00_e_s_op

Of course, not all models are the same, these just worked for me.

== Nipple/Boob stuff ==

I'm pretty sure you already noticed that your body doesnt have your nipple texture applied. Heres what you have to do to

# Go back to koikatsu and take off all your clothes and change your bra selection to any of the pasties
# Export just like we did before
# Now all you need to do is seperate by materials and copy and paste the pasties onto your body

Once we get into unity, we will replace the pastie texture to your actual nipple.

If the nipples/boobs clip through the clothing, it means that the clothes did not constrict your body on export.

Now if thats the case, you can use sculpt mode, or any other method you want, and to pull the clothing over your boobs.

If the clothes fit over the boobs perfectly, it's possible that your boobs have been <b>deformed to fit into the clothing</b>. This might make them look worse than you wanted (or at least, won't look like you intended when naked).

Some Koikatsu clothing does not mess with the boobs, usually transparent stuff, or stuff that shows the boobs/nipples even when "fully clothed". 

== Cleaning up ==
Before we get into unity, you should of already notice that you have 400+ shapekeys and 200+ bones, <b>this will significantly bloat your file size and import time into unity</b>. So I recommend that you do these steps to clean up your model before continuing

I also recommend you make 2 files, one that is cleaned up and one that isn't. Just in case you want to go back and add new shapekeys or play with bones we're gonna merge down

# There are tons of face bones we export with that we have no use for in VRChat so lets use the CATS merge weights functions to merge <b>everything that isnt your head bone, hair bones, Eyex_L and Eyex_R</b>
# In your shapekey list there about 400 shapekeys you probably wont use since you mixed some for gestures and what not, so delete everything that isnt your visemes and shapekeys you mixed.
# Now, we are pretty much done in blender, you can now export your fbx to unity.

== Textures ==

This step consists of gathering and matching textures to materials. Yes, the PmxExport exports some textures, but we won't be using those as they're desaturated and lacking many details. 
Before we really do texture stuff, let's get all of our texture in one place. Go to <code>C:\Users\(You)\NinjaRipper\_NinjaRipper\..</code> and find the folder with the textures for your export (probably the latest).

If you install [https://www.dotpdn.com/files/paint.net.4.2.7.install.zip paint.net] and set it to open .dds files by default, then you will see previews of .dds files in the folder, super useful!

Many Koikatsu textures need to be decomposed into their color channels and flipped to be used. If you installed ImageMagick, you can place a .bat file with the following script in the same folder as your textures and run it to do this automatically.

 for %%f in (*.dds) do 
   magick convert %%f -flip -separate -swap 0,2 -combine %%f.flipped.png
 for %%f in (*.flipped.png) do 
   magick convert %%f -channel RGBA -colorspace sRGB -separate %%f.png
 
<b>Some</b> Koikatsu textures have no additional textures, but many have a base texture, RGB (Shine, Detail, Outline) mask texture, normal map, and even colormasks.

If you use the material editor in Koikatsu, you can idnetify which materials use detail, normal and colormask.

<b>You need to manually identify what is what since the naming scheme from Ninja Ripper is simply sequential.</b>

The base texture for most things should be obvious. Shine is appended with a -0, Detail is -1, and Outlinemasks are -2. 

<b>Hair is more complicated. It has no base texture. It uses color mask and RGB masked textured (shine/detail/outline) only. </b>Hair tends to look [[Media:51ec1dcde725ce944b1bbe2f97aac819.png|like this]].

Also depending on how you choose to apply things, you may want to invert the colors of things, or even recolor them. I don't remember what I had to color invert or not. If something looks weird, try color inverting it (like an outline mask etc).

<b>If you still have a hard time identifying what is what, you can simply do trial and error in Unity later. Don't use the textures exported from Material Editor directly, though.</b>


I use [https://github.com/poiyomi/PoiyomiToonShader/releases Poiyomi's Shader] since you can apply color masks and detail maps very easily. This part of the process is <b>very subjective.</b> If you don't want to use poiyomi, you can apply the color masks and detail maps in an image editor easily.

<b>The deleted lower eyeline</b>: Simply "fix" this by taking the lower eyeline's texture and overlaying it along side the upper eyeline's texture, like [[Media:Eyeline.png|this]].

== Your boring basic bitch face ==

Koikatsu suffers from sameface, especially if you're using a lightly touched card. Before we fix that though, there's more overlaying to do here like you did with the eyeline and eyes:

# First, you want to make sure you have any makeup etc on the face texture <i>somewhere</i>. Recoloring your mouth line from black to a pink color is also super nice looking and compliments the under-mouth shine if you extend the line a bit too.
# I also place the nose onto the face texture. No more weird aliased/disappearing nose. [[Media:Faceexample.png|Here's an example showing my face.]]
# As far as your basic bitch dead expression goes, that's because you exported with that expression when we first started. Set a cute mouth blend shape and see how much nicer you look! I use kuti_face_f00_doya_cl and kuti_face.f00_neko_cl at 25 strength.

== Misc color or aliasing issues with the eyebrows, eyeline, eyes, etc ==
Use Cutout, not Transparency for these, and make sure Alpha To Coverage is disabled. My [[Media:7c24df0c747891eec80566d7e0a911d8.png|eyebrow Alpha options]].
Some stuff comes uncolored. Don't be afraid to recolor them or to use a different Color & Alpha setting than pure white in the shader.

== Normal Maps ==

Normal maps need a little bit more work to function properly; you need to decompose and recompose them with the alpha slot replacing the red slot.

To do this in GIMP:

* Colors-> Components-> Decompose to RGBa
* Colors-> Components-> Recompose
* Colors-> Components-> Compose, put the alpha channel in the red slot