-
Notifications
You must be signed in to change notification settings - Fork 81
1 Introduction to zipmod format
This is an in-depth explanation of the zipmod format. It contains a description of why zipmods are better than directly modifying game files, how zipmods are made, and how they work.
See this guide for a step-by-step walkthrough of how to make a simple texture mod. Leave this page open in case you need to check any details of the provided steps.
You can download an example zipmod here to study as you read this guide. You can use it as a base for your own zipmods if you want to.
Zipmod (also known as zip mod, sideloader mod, soft mod) is a format for self-contained and easy-to-install-and-remove content mods (not code). Zipmods were created as a solution to many issues present when creating mods for Illusion games. They were first created for use in Koikatu, but were later ported to EmotionCreators and AI-Shoujo. Zipmods usually have the .zipmod extension, but they can also have .zip extension for testing and limited distribution.
Zipmods are loaded by the plugin Sideloader. Without the plugin they will not work. It is included in BepisPlugins for your particular game. Most if not all repacks and patches include Sideloader.
Zipmods are distributed as a single file that should never be extracted by the user. They have to be placed in a directory labeled /mods/ in the game's root directory (where the .exe is). The directory has to be manually created if it doesn't already exist. Subfolders can be created for organization - everything inside mods folder will get loaded, including files inside subfolders.
Using the zipmod format for your mods yields many benefits. At the time of writing, the notable gains are:
- List loading is done via plain, loose .csv files instead of having to place them in an asset bundle.
- Easy distribution/installation/uninstallation - it's just dragging and dropping a single file. Thanks to the standardized manifests contained in all zipmods, mod managers are very easy to implement.
- Missing mod warnings - in case a mod is missing, it's guid will be shown to the user to help track down missing mods used by a character card or a scene.
- It's possible to override only some assets in game's asset bundles, and the original files are never replaced. Multiple mods can override different parts of the same asset bundle with no issues.
- Low to no chance of mod conflicts - it's perfectly acceptable to install ALL zipmods released for a game, and expect them to work with no issues (unless multiple zipmods try to override the same game asset, in which case a random one is picked).
What the universal auto ID resolver means for you:
- You can use multiple mods together with conflicting IDs, and it'll automatically shift them for you without needing to do anything
- This is also carried over to loading/saving cards, so you can share cards made with this with other people who have this plugin without fear of wrong IDs
- This is all done in a decentralized way (in other words, without a centralized database), meaning you don't have to register anything, anywhere.
There are some catches that need to be taken into account when creating zipmods:
- Only mods loaded via the .zipmod (renamed .zip) format are supported
- Cards that use hardmods are not guaranteed to be compatible (sideloader will attempt to load them, but it will not be able to resolve any conflicts). HOWEVER you are able to give cards that use zipmods to people without the plugin, and it'll work fine assuming that they have the necessary harmods.
- Your manifest GUID cannot change and must be unique to the mod, otherwise the old cards using your mods will be broken.
- Your item IDs cannot cannot change either for future versions of your mod to work as expected (which is the case for normal mods anyway).
- Your item IDs cannot conflict with themselves, i.e. you can't have two hairs in the same mod with the same ID (which is also the case for normal mods). You can hovewer make two separate zipmods with conflicting IDs, and the conflicts will be correctly resolved.
- The CAB-string of any unity3d files must be unique (which is also the case for normal mods).
- Your item IDs need to be numbers under 100 million (100,000,000).
If you can satisfy all this, then everything is all done behind the scenes to make this as painless as possible, for both modders and end users.
Right now you can use either asset emulation (raw .png files in the .zip file, similar to the existing asset emulation), or you can have the actual .unity3d files in the zip.
Examples:
If you have a file named bundle.unity3d, and you want it to appear to the game to be in the abdata/custom/ folder, it's pretty much the same directory structure as the normal game. So if you wanted to put this into a zip file, the filename in the zip file should be:
abdata/custom/bundle.unity3d
where abdata and custom are folders, and the custom folder is inside the abdata folder.
When zipping a mod containing a unity3d file you can choose to zip it without compression. This will allow it to be streamed directly from the .zip instead of needing to load the whole thing in to memory, significantly reducing the performance impact and RAM usage. Be warned that CAB string randomization does not work together with streaming so you must manually give all of your unity3d files unique CAB strings.
For asset emulation, say you had a texture named eye.png, and wanted it inside an asset bundle called mt_eye.unity3d which was placed inside abdata/custom/. In this case, you should pretend the asset bundle is actually a folder. The path in the zip file for this would be:
abdata/custom/mt_eye/eye.png
Note that currently only Texture2D assets are supported via asset emulation, and they have to have the .png extension. This will most likely not be extended to include other types of assets.
Every .zip needs a manifest with information about the mod itself. This is required, and the .zip will not be loaded if this file is not included. This information needs to be placed in manifest.xml, and needs to be in the root of the .zip, i.e. not in any folders.
Here is an example manifest.xml:
<manifest schema-ver="1">
<guid>com.bepis.bepiseyes</guid>
<name>Test eyes</name>
<version>1.0.0</version>
<author>Bepis</author>
<description>shitty eye pack</description>
<website>abc.xyz</website>
<game>Koikatsu</game>
</manifest>A description of each entry:
guid - The unique ID of the mod. Required. To help ensure that these are unique to you, you can do what I do and use something similar to Java's package naming convention. A good example template is com.[your name].[name of your mod].
name - The display name of your mod. Optional.
version - The display version of your mod. Can be any text, but for the versioning to work correctly it's recommended to use the major.minor[.revision] format (e.g. 4.8.1, 1.0, 6.9, 13.3.7). If the user has two mods with the same guid (e.g. he updated your mod without removing the old version) this entry is used to determine which one to load - only the highest version number will be loaded. If version is missing or two zipmods have the same version, a random one is loaded. Optional.
author - The name of the person who created the mod. Should be in a single line and below 50 characters. Optional.
description - A description of your mod, and/or what it does. Optional. Can be as big as you want. Completely up to you about whatever goes in here.
website - A http link to your website/page for this mod. Optional.
game - Specify a game the mod should load on. If left empty, the mod will load for any game that supports Sideloader. Currently "Koikatsu", "EmotionCreators", "AI Girl", and "Honey Select 2" are the only valid options. This should be left blank for the majority of mods and only specified if a mod breaks another game, in which case game-specific versions of those mods should be created and the game specified. Optional.
If you want a bare minimum template, you can use this:
<manifest schema-ver="1">
<guid>com.bepis.bepiseyes</guid>
</manifest>Lists located inside .unity3d do not work in the .zip mod loader, so you need to use the .csv format to load lists into the game. All .csv files located in list\characustom\ and any subfolders from there in the zip will be loaded, and not from anywhere else. They must also have the .csv extension.
Here's an example of one:
408
0
Assets/Illusion/assetbundle/chara/list/characustom/00/mt_eye_00.bytes
ID,Kind,Possess,Name,MainAB,EyeTex,ThumbAB,ThumbTex
9999,0,1,Spurdo Spärde,chara/mt_eye_00.unity3d,cw_t_hitomi_9999,chara/thumb/mt_eye_00.unity3d,thumb_hitomi_9999
The first 4 lines must exist, while the first 2 strictly must be numbers only, with no commas.
The first line (408) is the category number for this list, and each one defines what category this list is for (iris textures, highlight textures, back hair etc.). You can get this number from SB3U.
The second line (0) is the distribution number. This line is not used by the game but must exist, put anything you like.
The third line (Assets/Illusion/assetbundle/chara/list/characustom/00/mt_eye_00.bytes) is the file path of the list, before being packed into an asset bundle. This line is not used by the game but must exist, put anything you like.
The fourth line are the names of the columns, separated by commas. This information you can also get from SB3U. These are different for every category number.
All lines onward are the comma separated data, which match the positioning of the column names. Note that if the amount of commas in these lines do not match the amount of commas in the column line (line 4), you will cause really weird character model bugs, due to causing the list loader to crash half-way through loading.
Zipmods should be zipped without compression so that Sideloader can stream the asset bundle directly from the .zip file. Zipmods with compression will be loaded in to memory which, with enough mods, can quickly consume all of the user's available RAM, resulting in game crashes. To reduce the file size of mods, it is recommended to compress the asset bundle with LZ4 compression either in Unity editor when building the asset bundle or with SB3UGS.