Modding:Modder Guide/APIs/Manifest

Creating SMAPI mods

---

• Get started
• Game fundamentals
• Test & troubleshoot
• Release
• API reference

  Basic SMAPI APIs:

  • Mod structure
  • Manifest
  • Events
  • Configuration
  • Load & edit content
  • Data
  • Input
  • Logging
  • Reflection
  • Multiplayer
  • Translation
  • Update checks
  • Utilities

  Advanced SMAPI APIs:

  • Content packs
  • Mod console commands
  • Mod integrations
  • Harmony patching

• Specific guides

← Modding:Index

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": "Your Project Name", "Author": "your name", "Version": "1.0.0", "Description": "One or two sentences about the mod.", "UniqueID": "YourName.YourProjectName", "EntryDll": "YourDllFileName.dll", "UpdateKeys": [] }	{ "Name": "Your Project Name", "Author": "your name", "Version": "1.0.0", "Description": "One or two sentences about the mod.", "UniqueID": "YourName.YourProjectName", "UpdateKeys": [], "ContentPackFor": { "UniqueID": "Pathoschild.ContentPatcher" } }

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.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. For this reason, once you've published your mod, do not change this unique ID in future versions of the same mod. 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 or game version

The MinimumApiVersion and MinimumGameVersion field sets the minimum version of SMAPI or Stardew Valley needed to use this mod. If a player tries to use the mod with an older version, they'll see a friendly message saying they need to update it.

For example:

"MinimumApiVersion": "4.0.0"

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. For example:

"Dependencies": [
   {
      "UniqueID": "SMAPI.ConsoleCommands",
      "MinimumVersion": "3.8.0" // 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": "SMAPI.ConsoleCommands",
      "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, which tells SMAPI where to check.

See update checks for more information.

Specialized fields

⚠️ Most mods shouldn't need to use these fields.

Private assemblies

The following describes the upcoming SMAPI 4.1.0, and may change before release.

A private assembly is a DLL which only one mod can reference. This ensures that the mod has the exact version it was designed for, and lets different mods use different versions of the same assembly. You can use this even if another copy of the assembly was already loaded by SMAPI or another mod.

Caveats:

• Each private copy of a DLL has separate static values. Don't use this for assemblies that need to share global state (e.g. Harmony).
• The DLL needs to be in your mod folder.

You must specify the assembly name (without the version, culture, and private key). For example:

"PrivateAssemblies": [
   {
      "Name": "Newtonsoft.Json"
   }
]

SMAPI will log a warning if it doesn't detect a reference to the DLL, which is usually a mistake. If that's deliberate (e.g. you're accessing it through reflection), you can suppress that warning:

"PrivateAssemblies": [
   {
      "Name": "Newtonsoft.Json",
      "UsedDynamically": true // not recommended -- only set if DLL is accessed in a special way
   }
]

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.