Item Porting Guide
This guide will walk you through the process of creating a mod using KoikatsuModdingTools.
First, you want to download Unity and the KoikatsuModdingTools project files.
- Download Unity 5.6.2 which is the version that Koikatsu uses.
- Download the repository by clicking the green "Clone or download" button on Github, up in the top right of the main project page.
- Open the project in Unity.
Once you've opened it you should see an Examples folder and a Mods folder. The Examples folder contains example projects for several different types of mods which will be useful after learning the basics from this walkthrough.
Create a new folder within the Mods folder for your mod. Each mod should be inside its own folder within the Mods folder for organization purposes. With the new folder open, right click in the empty area at the bottom and click Create->Manifest.xml
This will create manifest.xml file which all sideloader mods require. Select in and in the Inspector window you'll see options for editing it. A manifest.xml requires a GUID, other fields are optional. For the Game field, leave it as Koikatsu And Emotion Creators. If set to Koikatsu it will prevent the mod from loading on Emotion Creators, this is only useful if you make a separate, Emotion Creators exclusive version of your mod.
Now, right click in the Project area at the bottom and select Show in Explorer. This will open the folder containing this project. Now add the mesh of the object you want to add as a mod. It helps to create new folders to organize your assets. The mesh can be a variety of file types: .obj, .fbx, and even .blend files if you also have Blender installed. Textures likewise can be various formats, .png, .jpg, and .psd which is very convenient as is allows you to keep all your layers intact unlike other image formats.
When you switch back to Unity, the assets you added should be imported. Meshes will display a preview in the Project window at the bottom. No need to worry about any of the import settings.
Drag and drop the mesh from the Project area to the Hierarchy window and you should see it in the main Scene view. Press F to center the camera on the object if you can't see it. Select it in the Hierarchy and make sure the position, rotation, and scale are all default values, click the gear icon and Reset if not. Change the Layer to Chara and there should be a popup that asks if you want to apply the change to all child objects, click yes. Setting the proper layer is important, if not set your object will be invisible in game.
Remove the Animator if it has one, this is only useful for objects with associated animations which yours likely does not. Click Add Component and add the ChaAccessoryComponent. All accessories require this.
Next, set the size of the Rend Normal array to 1 and next to the first element click the circle. This should pop up a list of any meshes currently in the scene. If your object has multiple meshes, change the size of the RendNormal array and make sure each mesh is added to this array.
Use Color 01, 02, and 03 will indicate to the game whether to show the color picker options in the character maker, make sure to enable these if your object is colorable and disable any unused colors to prevent users being confused. Def Color 01, 02, and 03 determine the default color the accessory will be when selected in the character maker. Choose some nice colors to best show off the accessory.
Next, expand the object in the Hierarchy and find the Mesh Renderer. Each one will have an associated material, in this case a material was imported along with the mesh and already has one attached. If yours does not (i.e. uses some default Unity material) right click Project area at the bottom and Create->Material. Name it what you like and assign it to the MeshRenderer. Change the shader of the material to ShaderForge/main_item which is the shader that most accessories use.
Assign any textures associated with this object and configure your material properties. If you have no idea what any of this does, don't worry over it for now. Later on once you have your accessory in game you can use the MaterialEditor plugin to modify the material properties and see in real time what each of them do. Use that as a reference and configure your material later on.
Textures require a bit of configuration as well. Textures should all use compression High Quality as Medium Quality and lower cause horrible looking compression artifacts. In this particular case, these textures have already been compressed using a lower quality setting and so won't benefit from High Quality settings, but any textures you create yourself or otherwise haven't been ruined yet should use High Quality compression. Most textures should have Mipmaps enabled, only specific textures don't benefit from them (although they are harmless in such cases). Note that any changes you make here will not affect your original images, the source material in your project files will remain untouched.
The MainTex should have Alpha Is Transparency enabled.
Normal Map textures should be of the Normal Map Texture Type. Likely once you assigned the Normal Map texture to your material Unity will already have converted it for you.
Other texture types such as the DetailMask and ColorMask should have sRGB (Color Texture) disabled and Alpha Is Transparency disabled.
Now that everything is properly configured, drag and drop the the object from the Hierarachy window to the Project window at the bottom. I've added it to a separate Prefab folder for organization. Select it and in the bottom for the Inspector window you should see a place to assign it to an AssetBundle. Anything you name your AssetBundle is fine so long as it doesn't conflict with another, either from the base game or another modder's mods. To avoid conflict you can use your name and your mod name in the file path, for example chara/modder_name/mod_name.unity3d.
Accessories should have a thumbnail which will appear in the character maker. This one is just an image with the word Example on it, but yours should contain an image of your item. Later on once your get the object in to the character maker you can screenshot it and edit the thumbnail image. As with the prefab object, the thumbnail should be assigned to an asset bundle. You can assign it to the same asset bundle or another asset bundle just for thumbnails.
Next you need a list file which will indicate to the game what type of item this is and where to add it. Create a .csv file inside a folder at List/Maker, or copy the one from the accessory example project to your mod and edit it. The exact contents of this list are outside the scope of this guide, check the guides on the BepisPlugins wiki for more details.
- https://github.com/IllusionMods/BepisPlugins/wiki/1-Introduction-to-zipmod-format#lists
- https://github.com/IllusionMods/BepisPlugins/wiki/2-How-to-create-a-simple-zipmod#step-4-creating-the-list
The MainAB is the AssetBundle you assigned the prefab to, the MainData is the name of the prefab. ThumbAB is the AssetBundle the thumbnail is assigned to, ThumbTex is the name of the image.
Finally, it's time to build the mod. Click Window->AssetBundle Browser and on that window click Build. I have mine docked next to the Hierarchy for easy access. Fill in the Koikatsu Path with the path of your Koikatsu install, this is required since during the build process the shaders from the original game files will be injected in to the asset bundles that have been built. Click Build Asset Bundles and Unity will compile all of your assets in to the AssetBundle they've been assigned to. Once that has finished, click Build Zipmod and these AssetBundles will be zipped up along with the list files an manifest.xml. If you have Copy Mods checked, this .zipmod file will be copied directly in to your mods folder so you can just launch the game to see your mod in action.
If all goes well you should be able to find your item in game.
Most likely something will go wrong, unfortunately. There's a lot to learn when it comes to modding.
- If your item doesn't show in the list make sure you have the proper category number in your list file
- If the item shoes in the list but doesn't show up when selected make sure the prefab has been assigned to an asset bundle and that asset bundle is what is listed in the list file. You may also want to check that the Layer of the object is set to Chara. Your object could also be really huge, really tiny, or very off center, try scaling the accessory and moving the camera around to look for it.
- If your thumbnail appears as a white square make sure you have the thumbnail texture assigned to an asset bundle and the list file is correct.
- If your item appears correctly but cannot be moved around by the in game adjustment menu, make sure you have a transform named N_move. This is the transform the game manipulates when you modify the in game adjustments.
This guide only covers how to create an accessory, but what you've learned here will help you create most any other type of item. Included with the KoikatsuModdingTools project are a set of example projects that contain fully functional mods. Open them and read the readme for details on those particular types of mods. Some details may be different like different list files or item categories but the principles of importing assets, assigning them to asset bundles, and building the mod are the same.