Zipmod format - RobotsOnDrugs/LibMAI GitHub Wiki

Introduction

Zipmods are ZIP archives with the file extension .zipmod that contain sideloader mods for Illusion games. Poses and overlays are not contained in zipmods.

Zipmods may be compressed using the standard Deflate algorithm, but this is not recommended since it results in slower load times.

Zipmods consist of 3 major components - the manifest, metadata in the form of CSV files, and asset bundles. A zipmod may contain more than one item (e.g., multiple studio items or multiple accessories).

Manifest

The manifest is an XML file that contains basic information about the zipmod such as the author's name, the GUID, and version. However, some mods (e.g., uncensors) contain metadata about the mod exclusively in the manifest.

There is only one manifest and it is located at the root of the archive and must be named manifest.xml.

Manifests may contain a standard XML header such as <?xml version="1.0" encoding="utf-8" standalone="no"?>.

Manifest format

<Incomplete>

Head mods, shaders, and uncensors contain metadata in the manifest.

Example minimal manifest:

<manifest schema-ver="1">
  <guid>com.75.analplug</guid>
  <name>[75] Anal plug</name>
  <version>0.0.2</version>
  <author>75</author>
  <description></description>
  <website></website>
  <game></game>
</manifest>

Example head mod manifest:

<manifest schema-ver="1">
  <guid>[DBLin].FF7R Tifa</guid>
  <name>Tifa Lockhart</name>
  <version>1.0</version>
  <author>DBLin</author>
  <description>FF7R Tifa Head mod</description>
  <website>https://www.patreon.com/DBLin</website>
  <game>hs2</game>
  <headPresetInfo preset="preset_head_01">
    <headID>180</headID>
    <headGUID>[DBLin].FF7R Tifa</headGUID>
    <skinGUID>[DBLin].FF7R Tifa</skinGUID>
    <detailGUID></detailGUID>
    <eyebrowGUID></eyebrowGUID>
    <pupil1GUID></pupil1GUID>
    <pupil2GUID></pupil2GUID>
    <black1GUID></black1GUID>
    <black2GUID></black2GUID>
    <hlGUID></hlGUID>
    <eyelashesGUID>[DBLin].FF7R Tifa</eyelashesGUID>
    <moleGUID></moleGUID>
    <eyeshadowGUID>[DBLin].FF7R Tifa</eyeshadowGUID>
    <cheekGUID></cheekGUID>
    <lipGUID>[DBLin].FF7R Tifa</lipGUID>
    <paint1GUID></paint1GUID>
    <paint2GUID></paint2GUID>
    <layout1GUID></layout1GUID>
    <layout2GUID></layout2GUID>
  </headPresetInfo>
  <faceSkinInfo skinID="180" headID="180" headGUID="[DBLin].FF7R Tifa" />
  <faceSkinInfo skinID="181" headID="180" headGUID="[DBLin].FF7R Tifa" />
  <Head_Bundle_Redirect Path="chara/mm_base_Tifa.unity3d" Slot="180" />
</manifest>

Example uncensor manifest:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest schema-ver="1">
	<guid>mikke.puffybeaver</guid>
	<version>1.0</version>
	<author>Mikke</author>
	<description>Puffy uncensor for Beaver</description>
	<website>www.disney.com</website>
	<KK_UncensorSelector>		
		<body>
			<guid>mikke.puffybeaver</guid>
			<displayName>Puffy Beaver</displayName>
			<sex>Female</sex>
			<oo_base>
				<file>chara/PuffyBeaver01.unity3d</file>				
			</oo_base>
		</body>	
	</KK_UncensorSelector>
</manifest>


Asset bundles

Asset bundles consist primarily of game assets such as 3D models and shaders, but in the case of AI/HS2, they may also contain image data used in the game (e.g., HS2 in-game maps).

Asset bundles may be located anywhere in the archive.

Metadata

Metadata for most mod types is located in CSV files in a specific path within the archive and with a specific format depending on the type of mod.

With the exception of bone lists, these CSV files may be named anything as long as they exist in the correct directory. CSV files may be in subdirectories of the listed locations.

A zipmod may contain more than CSV file and each CSV file can contain more than one entry. The sum of entries is equal to the number of mods contained.

Paths

  • Character items: /abdata/chara/list/
    • Clothing
    • Hair
    • Accessories
    • Sunburn
    • Moles
    • Body paint
  • Studio items: /abdata/studio/info/
    • Non-character items such as furniture
    • Gimmicks such as pistons and the dick navigator
  • Maps: /abdata/list/map/
    • Studio maps
    • HS2 in-game maps

Metadata format

Coming soon...

Notes

The sideloader doesn't seem to keep track of zipmods per se, but rather loads the metadata into lists of manifests, asset bundles, migration data, ID conflict resolution data, head presets, face skins, and PNG files associated with mods.

I am currently unsure how these are tied together for each zipmod. It may use a dictionary that maps the slot number to ZipmodInfo objects.

The sideloader also keeps a cache of zipmod information at BepInEx/cache and will not load directly from zipmods that are cached.

See also

To do

  • Complete manifest format
  • Complete metadata format with examples
  • Investigate mods with dependencies listed in the manifest that are spread across multiple zipmod files (e.g., Hooh's corridor map set)
⚠️ **GitHub.com Fallback** ⚠️