Using Mâché Artifacts

Mâché produces a single artifact, which is a zip archive that provides all of the necessary information needed to remap, decompile, and patch the Minecraft server into a usable workspace.

There are 2 major components of a Mâché artifact:

1. The mache.json config file
2. The patches/ directory

The patches/ directory is a copy of the patches provided in the version definition, to be applied after the code has been decompiled.

The mache.json file describes the versions of each of the tools used, how to run them, and where to find them.

Example JSON:

{
  "version": "23w31a",
  "dependencies": {
    "codebook": [
      {
        "group": "io.papermc.codebook",
        "name": "codebook",
        "version": "1.0.6"
      }
    ],
    "paramMappings": [
      {
        "group": "org.parchmentmc.data",
        "name": "parchment-1.20.1",
        "version": "2023.07.30",
        "extension": "zip"
      }
    ],
    "constants": [
    ],
    "remapper": [
      {
        "group": "net.neoforged",
        "name": "AutoRenamingTool",
        "version": "1.0.5"
      }
    ],
    "decompiler": [
      {
        "group": "org.vineflower",
        "name": "vineflower",
        "version": "1.9.2"
      }
    ]
  },
  "repositories": [
    {
      "url": "https://maven.fabricmc.net/",
      "name": "FabricMC",
      "groups": [
        "net.fabricmc"
      ]
    },
    {
      "url": "https://maven.neoforged.net/releases/",
      "name": "NeoForged",
      "groups": [
        "net.neoforged",
        "net.minecraftforge"
      ]
    },
    {
      "url": "https://repo.papermc.io/repository/maven-public/",
      "name": "PaperMC",
      "groups": [
        "io.papermc"
      ]
    },
    {
      "url": "https://maven.parchmentmc.org/",
      "name": "ParchmentMC",
      "groups": [
        "org.parchmentmc"
      ]
    }
  ],
  "decompilerArgs": [
    "-nns=true",
    "-tcs=true",
    "-ovr=false",
    "-vvm=true",
    "-iec=true",
    "-jrt=current",
    "-ind=    ",
    "-jvn=false",
    "-dcc=true",
    "-sef=true",
    "-nls=1"
  ],
  "additionalCompileDependencies": {
    "compileOnly": [
      {
        "group": "org.jetbrains",
        "name": "annotations",
        "version": "24.0.1"
      }
    ]
  }
}

Full JSON schema definition:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/PaperMC/mache/mache.schema.json",
  "title": "Mache",
  "description": "The Mache artifact configuration",
  "type": "object",
  "properties": {
    "version": {
      "description": "Minecraft version name",
      "type": "string"
    },
    "dependencies": {
      "description": "Build tool dependency definitions",
      "type": "object",
      "properties": {
        "codebook": {
          "description": "codebook dependencies",
          "$ref": "#/$defs/dependencies"
        },
        "paramMappings": {
          "description": "Parchment parameter mappings",
          "$ref": "#/$defs/dependencies"
        },
        "constants": {
          "description": "Constant unpick definitions",
          "$ref": "#/$defs/dependencies"
        },
        "remapper": {
          "description": "AutoRenamingTool dependencies",
          "$ref": "#/$defs/dependencies"
        },
        "decompiler": {
          "description": "VineFlower decompiler",
          "$ref": "#/$defs/dependencies"
        }
      },
      "required": [ "codebook", "paramMappings", "constants", "remapper", "decompiler" ]
    },
    "repositories": {
      "description": "Maven repositories necessary for resolving all dependencies, excluding Maven Central",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "description": "The Maven repository URL",
            "type": "string"
          },
          "name": {
            "description": "The name of the Maven repository",
            "type": "string"
          },
          "groups": {
            "description": "The Maven group names to limit this repository to",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [ "url", "name" ]
      }
    },
    "decompilerArgs": {
      "description": "The base set of arguments to pass to VineFlower for decompilation",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "additionalCompileDependencies": {
      "description": "Additional dependencies required for compiling the sources after patching",
      "type": "object",
      "properties": {
        "compileOnly": {
          "description": "Dependencies which will be applied to the 'compileOnly' configuration",
          "$ref": "#/$defs/dependencies"
        },
        "implementation": {
          "description": "Dependencies which will be applied to the 'implementation; configuration",
          "$ref": "#/$defs/dependencies"
        }
      }
    }
  },
  "required": [ "version", "dependencies", "repositories", "decompilerArgs" ],
  "$defs": {
    "dependencies": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/mavenArtifact"
      }
    },
    "mavenArtifact": {
      "description": "A set of Maven coordinates for a dependency",
      "type": "object",
      "properties": {
        "group": {
          "description": "The groupId of the Maven artifact",
          "type": "string"
        },
        "name": {
          "description": "The artifactId of the Maven artifact",
          "type": "string"
        },
        "version": {
          "description": "The version of the Maven artifact",
          "type": "string"
        },
        "classifier": {
          "description": "The optional classifier of the Maven artifact",
          "type": "string"
        },
        "extension": {
          "description": "The optional extension of the Maven artifact",
          "type": "string"
        }
      },
      "required": [ "group", "name", "version" ]
    }
  }
}