Modding:Modder Guide/APIs/Manifest

From Stardew Valley Wiki
Jump to: navigation, search
Modder's guide to creating mods SMAPI mascot.png

Every SMAPI mod or content pack must have a manifest.json file in its folder. SMAPI uses this to identify and load the mod, perform update checks, etc. The manifest info is also available to any mod in code (using this.ModManifest for the current mod's manifest, or mod registry for other mods' manifests).

Basic examples

Here's the basic format (see below for details on each field):

For a SMAPI mod For a content pack
{
   "Name": "YourProjectName",
   "Author": "your name",
   "Version": "1.0.0",
   "Description": "One or two sentences about the mod.",
   "UniqueID": "YourName.YourProjectName",
   "EntryDll": "YourDllFileName.dll",
   "MinimumApiVersion": "2.0",
   "UpdateKeys": []
}
{
   "Name": "YourProjectName",
   "Author": "your name",
   "Version": "1.0.0",
   "Description": "One or two sentences about the mod.",
   "UniqueID": "YourName.YourProjectName",
   "MinimumApiVersion": "2.0",
   "UpdateKeys": [],
   "ContentPackFor": {
      "UniqueID": "Pathoschild.ContentPatcher", // the ID of required mod
      "MinimumVersion": "1.3.0" // optional
   }
}

Fields

Basic fields

All mods should specify the following fields.

field description
Name The mod name. SMAPI uses this in player messages, logs, and errors. Example:
"Name": "Lookup Anything"
Author The name of the person who created the mod. Ideally this should include the username used to publish mods. Example:
"Author": "Pathoschild"
Version The mod's semantic version. Make sure you update this for each release! SMAPI uses this for update checks, mod dependencies, and compatibility blacklists (if the mod breaks in a future version of the game). Examples:
"Version": "1.0"
"Version": "1.0.1-beta.2"
Description A short explanation of what your mod does (one or two sentences), shown in the SMAPI log. Example:
"Description": "View metadata about anything by pressing a button."
UniqueID A unique identifier for your mod. The recommended format is <your name>.<mod name>, with no spaces or special characters. SMAPI uses this for update checks, mod dependencies, and compatibility blacklists (if the mod breaks in a future version of the game). When another mod needs to reference this mod, it uses the unique ID. Example:
"UniqueID": "Pathoschild.LookupAnything"
EntryDll or ContentPackFor

All mods must specify either EntryDll (for a SMAPI mod) or ContentPackFor (for a content pack). These are mutually exclusive — you can't specify both.

For a SMAPI mod, EntryDll is the mod's compiled DLL filename in its mod folder. Example:
"EntryDll": "LookupAnything.dll"

For a content pack, ContentPackFor specifies which mod can read it. The MinimumVersion is optional. Example:

"ContentPackFor": {
   "UniqueID": "Pathoschild.ContentPatcher",
   "MinimumVersion": "1.0.0"
}

Minimum SMAPI version

The MinimumApiVersion fields sets the minimum SMAPI version needed to use this mod. If a player tries to use the mod with an older SMAPI version, they'll see a friendly message saying they need to update SMAPI. This also serves as a proxy for the minimum game version, since SMAPI itself enforces a minimum game version. Example:
"MinimumApiVersion": "1.10"

Dependencies

The Dependencies field specifies other mods required to use this mod. If a player tries to use the mod and the dependencies aren't installed, the mod won't be loaded and they'll see a friendly message saying they need to install those. Example:

"Dependencies": [
   {
      "UniqueID": "Entoarox.Framework",
      "MinimumVersion": "1.7.9" // optional. If specified, older versions won't meet the requirement.
   }
]

You can mark a dependency as optional. It will be loaded first if it's installed, otherwise it'll be ignored.

"Dependencies": [
   {
      "UniqueID": "Entoarox.Framework",
      "IsRequired": false
   }
]

Update checks

SMAPI can detect new versions of your mod and alert the user with a link to your mod page. You can enable this by setting the UpdateKeys field in your manifest.json with one of the following values, which tells SMAPI where to check.

mod site description
Chucklefish Make sure you have a mod release page (with a URL containing /resources/ instead of /thread/) and it has a semantic version, then specify the mod ID (it's in the mod page URL).
"UpdateKeys": [ "Chucklefish:4250" ]
Nexus Mods Make sure the Nexus mod has a semantic version, then specify the mod ID (it's in the mod page URL). When creating a new mod on Nexus, the ID is added to the URL after the first step, before you need to upload the file.
"UpdateKeys": [ "Nexus:541" ]
GitHub Make sure your GitHub project has at least one release and the latest release's tag is a semantic version, then specify your GitHub username and project name.
"UpdateKeys": [ "GitHub:Pathoschild/LookupAnything" ]

If you set multiple values, SMAPI will check them all and show an alert for the latest version it finds. (If multiple sites have the latest version, it will link to the earlier one in the list.)

"UpdateKeys": [ "Chucklefish:4250", "Nexus:541", "GitHub:Pathoschild/LookupAnything" ]

Anything else

Any other fields will be stored in the IManifest.ExtraFields dictionary, which is available through the mod registry. Extra fields are ignored by SMAPI, but may be useful for extended metadata intended for other mods.