poly.mod.json

poly.mod.json is a metadata file that lists the mod's ID, version, entrypoints, and dependencies. Poly Mod Loader recognizes a Poly Mod by this file inside the jar.

src/main/resources/poly.mod.json

{
  "schemaVersion": 1,
  "id": "crystal_garden",
  "version": "0.1.0",
  "name": "Crystal Garden",
  "environment": "both",
  "minecraft": [
    "26.*"
  ],
  "entrypoints": {
    "common": ["com.example.crystalgarden.CrystalGardenMod"],
    "client": ["com.example.crystalgarden.CrystalGardenClient"]
  },
  "depends": {
    "poly": ">=0.1.0-alpha <0.2.0"
  }
}

The template's file has no client line. Add it now for the CrystalGardenClient you create in Client code. If the listed class does not exist, the client stops at startup with POLY-ENTRYPOINT-001 (class could not be loaded). To try runClient before you write the client code, remove this line for now.

Fields

Field	Meaning
schemaVersion	Schema version. Currently 1
id	Mod ID. Lowercase letters, digits, underscores
version	Mod version (SemVer)
name	Display name
environment	both (client and server), client, server
minecraft	List of supported Minecraft versions
entrypoints.common	Runs on both sides. Declare content, commands, and network channels here
entrypoints.client	Runs only on the client. Declare key bindings, HUD, screens, and rendering here
entrypoints.server	Runs only on the dedicated server
depends	Required mods and version ranges. poly is Poly Mod Loader itself

Advanced fields such as conflicts, capabilities, replacesSystems, and transforms are in the poly.mod.json schema.

Writing versions in minecraft

The example above uses the wildcard "26.*". An entry in the minecraft list can take three forms. The mod loads if any one entry matches the game version.

Form	Example	Matching versions
Exact version	"26.2"	That one version
Wildcard	"26.*", "26.2.*", "*"	26.* matches the 26 series, such as 26.1 and 26.2.1. 26.2.* matches 26.2 and its hotfixes. * matches every version
Range	">=26.2 <27"	Versions that satisfy every space-separated comparison. The operators are >=, >, <=, <, =

• The mod template and Crystal Garden use "26.*".
• A mod that uses only the Native API, like Crystal Garden, uses a wildcard or a range. When Poly Mod Loader supports a new version, the mod runs on it without a rebuild. This works only if that version's game layer implements every API the mod uses.
• A mod that depends on the game code of one specific version, such as one with transform rules (transforms), lists the exact version.
• A range compares only numbered release versions, so it does not match snapshots. To run on a snapshot, write the exact snapshot ID.
• A malformed entry gives POLY-METADATA-009. If no entry matches, Poly Mod Loader stops and reports POLY-DEPENDENCY-007.

You choose the Minecraft version to run the mod on with polyMinecraft in gradle.properties, not with this list. See Running tests.

Validation

build (check) validates this file with the validatePolyModJson task. It uses the same validator Poly Mod Loader uses at run time, and tells you which field is wrong. The metadata error codes are POLY-METADATA-*.

Next step

Write the entrypoint.