Home

Creating mods with sideloader

IMPORTANT: This guide is technical and is aimed at people who work on UI tools for sideloader and those who want to make mesh/prefab/material replacements.
If you want to make skin mods, use SkinPacker for now.

Sideloader mod format

A sideloader mod is a ZIP archive renamed to .h3mod that contains the following files:

• PNG files (optional, used for textures)
• Unity asset bundles (for meshes, prefabs and materials)
• manifest.json (required)

For now, to create mesh/prefab/material replacements, you have to manually create asset bundles via Unity. A preferred way for now is to use AssetBundle Browser tool for Unity which allows you to easily compose and build asset bundles.

manifest.json

Manifest file contains metadata about the mod as well as information for sideloader about how to map the assets in the zip archive to in-game assets.

For more technically inclined, check out manifest's schema file and schema docs that contain technical info about the schema file.

Example manifest file:

{
  "manifestRevision": "1",
  "guid": "horse.coder.carrot_gun",
  "name": "Carrot Thompson M1A1",
  "version": "1.0.0",
  "description": "This is an example gun",
  "assetMappings": [
    {
      "type": "Texture",
      "target": "::m1a1_BaseColor:",
      "path": "thompson.png"
    }
  ]
}

Explanation of each value

• manifestRevision -- MUST be "1"
• guid -- A unique ID of the mod. Any string is a allow with the following limitations:
  • ID must only contain lowercase latin characters (a-z) or numbers 0-9
  • Only the following punctuation is allowed: ., -, _
  • No whitespace is allowed
• name -- Human-readable name of the mod. Must not contain newlines.
• version -- version of the mod. Must be of form <major>.<minor>.<fix> as per semver spec
• description -- Human-readable description of the mod. Can contain newlines.
• assetMappings -- Tells sideloader how to find assets to replace and what assets to replace them with.
  • type -- Type of the replacements. Allowed values are
    • Texture -- the mapping targets a texture inside a prefab
    • Mesh -- the mapping targets a mesh inside a prefab
    • Material -- the mapping targets a material inside a prefab
    • Prefab -- the mapping targets a whole prefab
  • target -- a template string that tells sideloader what asset to replace. The value is of form <value1>:<value2>:<value3>... where <value> defines an optional value that depends on the selected type. If a value is not specified, any asset is matched. Allowed values:
    • for Texture type, value in form <prefabPath>:<materialName>:<texName>:<texParam> where
      • prefabPath -- full path to the prefab. Must start with h3vr_data and be lowercase. Example: h3vr_data\streamingassets\assets_resources_objectids_weaponry_smg\thompsonm1a1 to target ThompsonM1A1 prefab in assets_resources_objectids_weaponry_smg asset bundle
      • materialName -- name of the Material instance
      • texName -- name of the texture to replace. Must be the same as defined in asset bundles (but without .png)
      • texParam -- shader parameter name to which attach the texture. If not specified, defaults to _MainTexture. This allows to swap normal maps.