2 How to create a simple zipmod
This guide will walk you through the process of creating your own zipmod. Specifically, you'll be adding a new body paint, but the process is very similar for creating any texture mod. Instructions will be provided on how to adapt this guide to other categories than body paints, but it may be best to follow the guide from start to finish and create your first working mod before attempting something else.
This guide only covers creating a zipmod using asset emulation (using loose .png files) and does not cover how to create a mod using .unity3d files.
See this page for a detailed explanation of the zipmod format. Keep it open in case you need to check detailed explanations for any of the steps below.
- SB3Utility
- Image editing software
For this example, we will be creating a new body paint. Create a new 512x512 .png image and fill it with whatever you like. A basic body paint should be white on a transparent background. Other colors can be used but only white will be modified by the color sliders in game. Save your file as example_clamp.png. Now reduce the size to 256x256 and save another copy as example_clamp_low.png.
The lower resolution image will be what displays in the school exploration mode, while the higher resolution image display in the character maker, studio, and H scenes. Putting 'clamp' in the filename indicates to the mod loader that the image should only display once instead of tiling over the entire body.
The thumbnail is what will be displayed in the list of items in the character maker. Create a 128x128 .png file and make it look however you like. Ideally it should somewhat resemble your body paint so the user knows what to expect at a glance. Name it example_thumb.png.
From this point forward it will likely be easiest to work backwards from an existing zip mod. Download the finished example mod here and unzip it. Open the manifest.xml file.
Fill out this information as you see fit. All fields except guid are optional and can be left blank or simply deleted. The guid must be unique and you will run in to conflicts if your mod shares a guid with another mod. Using YourName.ModName as a template is a good enough way to ensure uniqueness since it is very unlikely two mods will have both the same name and mod name by accident. If you are using this example as a template it is very important to change the guid to something else.
<manifest schema-ver="1">
<guid>YourName.ModName</guid>
<name>Name of your mod pack</name>
<version>1.0</version>
<author>Your Name Here</author>
<description>A description of your mod pack.</description>
<website>Somewhere people can find your mods</website>
</manifest>Next, you'll need to create a list file. The list tells the game where your files are located so they can be loaded. Open abdata\list\characustom\00\example.csv from the example mod you extracted. Also start SB3Utility and open Koikatu\abdata\list\characustom\00.unity3d (or the equivalent for your game) from your game installation files. Since you're making a body paint, select mt_body_paint_00.
Although the information in the .csv is already filled out for you, it's important to know where this information comes from in case you want to make anything other than body paints. The first line of your .csv file is the category number. 421 is the category for body paints, you should see the same number on the top tab of SB3Utility. Line 4 of your .csv is the comma separated list of field names. These field names will match the field names of the table in SB3Utility. Line 5 and onward is your list data. You can have as many lines as you have items in your mod, but for now there's only just one. These lines are a comma separated list that will contain the data for each field that match to the field names on line 4. Note that the _low file is not in this list; the game automatically assumes that every texture has a _low version and will automatically attempt to load it when necessary.
Now open the abdata\chara\mt_body_paint_00 folder from the extracted mod and place your example_clamp.png and example_clamp_low.png files here, replacing the existing ones. Next open the abdata\chara\thumb\mt_body_paint_00 folder and place your example_thumb.png here, replacing the existing one.
Finally, zip it all back up and place the .zip file in your Koikatu\mods folder.
If all goes well you should see your body paint in the character maker next time you start the game.
Make sure your .csv data matches the location of your .png file. If your thumbnail .png file is located at abdata\chara\thumb\mt_body_paint_00\example_thumb.png then your .csv file should have chara/thumb/mt_body_paint_00.unity3d set for ThumbAB and example_thumb set for ThumbTex. Note that example_thumb does not have a .png file extension in the list.
Same as above, make sure your list matches the file location and file names.
Many other categories of mods are created in a similar way. For example, if you open mt_face_paint_00.unity3d and select and item you'll see that each one is a 512x512 image with a 256x256 _low version, same as the body paint. Open the 00.unity3d list, select mt_face_paint_00, and you'll see that the category number is 405 and the field names are the same as the body paint field names. Make a copy of your example.csv file, name one example_bodypaint.csv and the other example_facepaint.csv and change the category of the example_facepaint.csv to 405. All the items in the face .csv are pointing to the same .pngs as the body paint .csv, no need to make a separate copy of each .png for your face paints. Now you have two .csv files each with a different category. A zip mod can contain any number of .csv files for as many different categories as you like.
example_bodypaint.csv:
421
0
Assets/Illusion/assetbundle/chara/list/characustom/00/mt_body_paint_00.bytes
ID,Kind,Possess,Name,MainAB,PaintTex,ThumbAB,ThumbTex
1,0,1,Example,chara/mt_body_paint_00.unity3d,example_clamp,chara/thumb/mt_body_paint_00.unity3d,example_thumb
example_facepaint.csv:
405
0
Assets/Illusion/assetbundle/chara/list/characustom/00/mt_face_paint_00.bytes
ID,Kind,Possess,Name,MainAB,PaintTex,ThumbAB,ThumbTex
1,0,1,Example,chara/mt_body_paint_00.unity3d,example_clamp,chara/thumb/mt_body_paint_00.unity3d,example_thumb
Clothing patterns are a bit different than body paints. If you open mt_pattern_00.unity3d you'll see that the image is 128x128 and the _low version is 64x64. Unlike body paints, clothing patterns do not support transparency and any color information will be ignored; only black and white images are supported.
Some other categories are comprised of multiple parts. If you open the 00.unity3d list and select mt_eyeline_up_00 you'll see that upper eyeliners have a field for EyelineUpTex and EyelineShadowTex. Open mt_eyeline_up_00.unity3d and you'll find the textures for both the eyeliner and the shadow. When making an upper eyeliner mod you'll need to include a .png file both the eyeliner and shadow for it to work correctly, and a _low version for each.
There's a few things you'll want to do before you release your mod to the public.
- Make sure your guid is unique. It's very important that you don't use the same one as used in the example, or the same one you used in a previous mod. Sideloader will only ever load one guid; any other mods in the folder with the same guid will be ignored.
- Make sure your guid is sensible. If someone downloads a card which uses your mod but they don't have your mod installed they will get a missing mod warning containing your mod's guid. If you set the guid to a string of random numbers and letters it may be very difficult for people to track down your mod. Something easy to type in to Google or ask others about is ideal.
- Change your folder names. In this example we used abdata\chara\mt_body_paint_00 to contain the example.png but you can change that to anything you like. You can create a folder at abdata\chara\your_name\mod_name and put your .pngs in there, just remember to update your .csv file to match. Putting your files in a different folder can help avoid conflicts; sideloader mimics a normal file structure, and like a normal file structure no two files with the same name can exist in the same folder. If someone else makes a mod with the same file names in the same folders your mod uses, only one of them will load.
- Test your mod. Click on every item you added and make sure they show up on the character correctly. Don't release your mod after some last minute changes that "shouldn't break anything".
- Rename your .zip to .zipmod. Sideloader loads both the same way, but .zipmod will make it less likely that someone extracts your mod and wonders why it doesn't work after not reading the installation instructions.
- Include some installation instructions. Many people coming from Honey Select and other Illusion games are used to extracting the mods. Include along side your mod some simple instructions on where to put the .zipmod file and you will hopefully have to deal with less tech support questions.