MixinGradle

https://github.com/spongepowered/mixingradle
Admin
A Gradle plugin that simplifies build-time complexity when working with the SpongePowered Mixin...
Tokens:34,119
Snippets:254
Trust Score:9.9
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Creating an ArtefactSpecificRefmap in configure()

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension-tasks.md

Example from MixinExtension.configure() that creates a task-specific refmap file using the parent directory and the user-specified refmap name.

```groovy
// From configure(): the per-task generated refmap is copied into an
// ArtefactSpecificRefmap that carries the user's chosen refmap filename.
File taskSpecificRefMap = new ArtefactSpecificRefmap(refMapFile.parentFile, compileTask.ext.refMap)
```

--------------------------------

### Example generated imports file content

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Example content of the generated imports file, showing lines with mixin and target class names separated by spaces.

```plaintext
com/example/MixinFoo    com/example/TargetBar
com/example/MixinFoo    com/example/OtherTarget
com/example/external/MixinBaz   net/other/plugin/Thing
```

--------------------------------

### Example usage of mapToArg and listToArg

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Shows example calls to `MixinExtension.mapToArg` and `MixinExtension.listToArg` with expected output. `mapToArg('tokens', [modid: 'x'])` produces `-Atokens=modid=x`; `listToArg('mappingTypes', ['tsrg'], ",")` produces `-AmappingTypes=tsrg`.

```groovy
// MixinExtension.mapToArg('tokens', [modid: 'x'])        // -> "-Atokens=modid=x"
// MixinExtension.listToArg('mappingTypes', ['tsrg'], ",") // -> "-AmappingTypes=tsrg"
```

--------------------------------

### Mixin extension usage example

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Example of using the mixin extension to configure a mixin config and extra mappings.

```groovy
mixin {
    config 'my-mod.mixins.json'
    extraMappings 'extra/mappings.tsrg'
}
```

--------------------------------

### MixinExtension(Project project)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Constructor for the MixinExtension class, which is installed as the 'mixin' project extension by MixinGradlePlugin. It initializes the extension by detecting the ForgeGradle project type and configuring the Mixin Annotation Processor.

```APIDOC
## MixinExtension(Project project)

### Description
Creates the Mixin extension for a Gradle project, detecting the ForgeGradle project type and configuring the Mixin Annotation Processor.

### Method
Constructor

### Endpoint
`MixinExtension(Project project)`

### Parameters
- **project** (`org.gradle.api.Project`) - Required - The containing project (supplied by Gradle when the extension is created).

### Throws
- `org.gradle.api.InvalidUserDataException` - If neither a `minecraft` nor a `patcher` extension exists on the project.

### Side Effects
- Detects the Gradle major version.
- Enables Eclipse APT integration via `MixinEclipse.configure(this, project)` unless `disableEclipseAddon` is set.
- Registers the `afterEvaluate` handler and `SourceSet`/`AbstractArchiveTask` metaclass accessors.
```

--------------------------------

### Minimal build.gradle setup for MixinGradle

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-plugin.md

Configures the buildscript to use MixinGradle 0.7-SNAPSHOT and applies the plugin. Requires ForgeGradle (userdev or patcher) to be applied first. The mixin block adds a refmap for the main source set.

```groovy
// build.gradle — minimal setup
buildscript {
    repositories {
        mavenCentral()
        maven { url = 'https://maven.minecraftforge.net/' }
    }
    dependencies {
        classpath 'org.spongepowered:mixingradle:0.7-SNAPSHOT'
    }
}

apply plugin: 'net.minecraftforge.gradle'    // ForgeGradle (userdev or patcher variant)
apply plugin: 'org.spongepowered.mixin'      // this plugin

mixin {
    add sourceSets.main, 'main.refmap.json'
}
```

--------------------------------

### Configure Mixin Messages

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Configures Mixin messages using the messages block. The example sets MESSAGE_HINT to 'warning', which produces the compiler argument -AMSG_MESSAGE_HINT=warning.

```groovy
mixin {
    messages {
        MESSAGE_HINT = 'warning'     // -> -AMSG_MESSAGE_HINT=warning
    }
}
```

--------------------------------

### Configuring tokens in a mixin block

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Example of adding tokens in a Groovy build script using the token, token(value), and tokens(Map) methods. The bulk form uses tokens(Map<String, ?>) and the single-argument form sets the value to "true".

```groovy
mixin {
    token 'disableTargetExport'          // boolean token, value "true"
    token 'mixin.debug', 'true'          // explicit value
    tokens([ 'modid': 'my-mod' ])        // bulk form: tokens(Map<String, ?>)
}
```

--------------------------------

### Catching MixinGradleException in Consumer Code

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-exception.md

Examples of how to catch MixinGradleException in Gradle build scripts or plugin code. Since it extends GradleException, it can be caught specifically or as a general GradleException.

```APIDOC
## Catching MixinGradleException

### Description
MixinGradleException extends GradleException, so it can be caught in Gradle build scripts, plugin code, or CI wrappers. The following examples show how to catch it specifically or as a general GradleException.

### Example 1: Catching MixinGradleException specifically
```groovy
// build.gradle — defensive capture in a custom task
tasks.register('checkMixinSetup') {
    doLast {
        try {
            // force the AP check to run
            project.extensions.getByType(MixinExtension).checkForAnnotationProcessors()
        } catch (org.spongepowered.asm.gradle.plugins.MixinGradleException e) {
            println "Mixin AP configuration problem: ${e.message}"
        }
    }
}
```

### Example 2: Catching the general Gradle failure type
```groovy
// Catching the general Gradle failure type also works, since
// MixinGradleException extends GradleException:
try {
    ...
} catch (org.gradle.api.GradleException e) {
    println "Build configuration error: ${e.message}"
}
```

### Notes
- The exception type is `org.spongepowered.asm.gradle.plugins.MixinGradleException`.
- It inherits methods like `getMessage()`, `getCause()`, `toString()`, and `printStackTrace()` from Throwable.
```

--------------------------------

### ConfigureReobfTask run() method contributing mapping files

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension-tasks.md

Task action that iterates over mappingFiles, logs info for existing files and delegates to addMappingFile, logs debug for missing files and skips them.

```groovy
@TaskAction
def run() {
    for (File mappingFile : this.mappingFiles) {
        if (mappingFile.exists()) {
            this.project.logger.info "Contributing tsrg mappings ({}) to {} in {}", mappingFile, reobfTask.name, reobfTask.project
            this.addMappingFile(mappingFile)
        } else {
            this.project.logger.debug "Tsrg file ({}) not found, skipping", mappingFile
        }
    }
}
```

--------------------------------

### Basic usage of mixin.add

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Shows how to register source sets with explicit refmap names, either by SourceSet object or by name.

```groovy
mixin {
    add sourceSets.main, 'main.refmap.json'
    add 'another', 'another.refmap.json'   // by name
}
```

--------------------------------

### void apply(Project project)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-plugin.md

Applies the MixinGradle plugin to a project. Validates the environment and creates the 'mixin' extension.

```APIDOC
## void apply(Project project)

### Description
Applies the MixinGradle plugin to a project. Validates the environment and creates the 'mixin' extension.

### Method
apply

### Signature
`void apply(Project project)`

### Parameters
- **project** (`org.gradle.api.Project`) - Required - The project the plugin is applied to.

### Returns
`void` - nothing.

### Throws
- `org.gradle.api.InvalidUserDataException` - when environment validation fails (see `checkEnvironment`).

### Behavior
Validates the environment, then creates the `mixin` project extension as an instance of `MixinExtension`. The extension constructor performs project-type detection (`userdev` vs `patcher`) and may itself throw `InvalidUserDataException`.

### Example
```groovy
@Override
void apply(Project project) {
    // This will throw an exception if any criteria are not met
    this.checkEnvironment(project)

    // create the mixin extension
    project.extensions.create('mixin', MixinExtension.class, project)
}
```
```

--------------------------------

### Import read() method

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Fluent method that triggers scanning of the library file. Idempotent: rescans only if not already generated and only if the file exists as a regular file.

```groovy
Import read() {
    if (this.generated) {
        return this
    }

    if (file.file) {
        this.readFile()
    }

    this.generated = true
    return this
}
```

--------------------------------

### Invalid token value example

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Demonstrates the configuration error when a token value contains a semicolon. The checkTokens() method throws InvalidUserDataException with the message 'Invalid token value 'a;b' for token 'bad''.

```groovy
mixin {
    token 'bad', 'a;b'
    // Fails with: InvalidUserDataException: Invalid token value 'a;b' for token 'bad'
}
```

--------------------------------

### void add(String set)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers an existing sourceSet by name. Delegates to add(SourceSet) and requires the sourceSet to exist.

```APIDOC
## void add(String set)

### Description
Registers an existing sourceSet by name. Delegates to add(SourceSet) and requires the sourceSet to exist.

### Method
N/A (Groovy method)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **set** (String) - Required - Name of an existing sourceSet

### Request Example
```groovy
mixin {
    add 'another'
}
```

### Response
#### Success Response (200)
No return value.

#### Response Example
N/A

### Error Handling
- Throws InvalidUserDataException if the sourceSet does not exist or has no refMap defined.
```

--------------------------------

### Build MixinGradle with Gradle

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Build MixinGradle using Gradle.

```shell
gradlew build
```

--------------------------------

### getMappings() method

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Returns the SRG mapping file. If reobfSrgFile is set, returns that file; otherwise returns the first output of createMcpToSrg (userdev) or createMcp2Srg (patcher) task; null if none apply.

```groovy
Object getMappings() {
    if (this.reobfSrgFile != null) {
        return project.file(this.reobfSrgFile)
    } else if (this.projectType == 'userdev') {
        return project.tasks.createMcpToSrg.outputs.files[0]
    } else if (this.projectType == 'patcher') {
        return project.tasks.createMcp2Srg.outputs.files[0]
    }
    return null
}
```

--------------------------------

### Enable Eclipse APT plugin

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Enable the Eclipse APT plugin to receive annotation processor support within Eclipse when using MixinGradle.

```groovy
apply plugin: 'com.diffplug.eclipse.apt'
```

--------------------------------

### void add(SourceSet set)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a SourceSet object. Requires the sourceSet to have a refMap or ext.refMap property defined, otherwise throws InvalidUserDataException.

```APIDOC
## void add(SourceSet set)

### Description
Registers a SourceSet object. Requires the sourceSet to have a refMap or ext.refMap property defined, otherwise throws InvalidUserDataException.

### Method
N/A (Groovy method)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **set** (org.gradle.api.tasks.SourceSet) - Required - SourceSet to process; must define a refMap

### Request Example
```groovy
mixin {
    add sourceSets.main
}
```

### Response
#### Success Response (200)
No return value.

#### Response Example
N/A

### Error Handling
- Throws InvalidUserDataException if the sourceSet has no refMap or ext.refMap property.
```

--------------------------------

### void add(SourceSet set, Object refMapName)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a SourceSet object and assigns a refmap resource name to it.

```APIDOC
## void add(SourceSet set, Object refMapName)

### Description
Registers a SourceSet object and assigns a refmap resource name to it.

### Method
N/A (Groovy method)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **set** (SourceSet) - Required - SourceSet to process
- **refMapName** (Object) - Required - Refmap name (stringified)

### Request Example
```groovy
mixin {
    add sourceSets.main, 'main.refmap.json'
}
```

### Response
#### Success Response (200)
No return value.

#### Response Example
N/A

### Error Handling
No explicit error handling documented.
```

--------------------------------

### MixinExtension constructor

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Constructor for MixinExtension. Detects the Gradle major version, determines the project type by checking for 'minecraft' or 'patcher' extensions, throws InvalidUserDataException if neither is present, configures Eclipse APT integration unless disabled, and initializes the extension.

```groovy
MixinExtension(Project project) {
    this.project = project
    this.majorGradleVersion = MixinExtension.detectGradleMajorVersion(project)

    if (project.extensions.findByName('minecraft')) {
        this.projectType = 'userdev'
    } else if (project.extensions.findByName('patcher')) {
        this.projectType = 'patcher'
    } else {
        throw new InvalidUserDataException("Could not find property 'minecraft', or 'patcher' on $project, ensure ForgeGradle is applied.")
    }

    if (!this.disableEclipseAddon) {
        MixinEclipse.configure(this, this.project)
    }

    this.init(this.project, this.projectType)
}
```

--------------------------------

### Object getMappings()

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Returns the SRG mapping file for the project. It checks for an explicitly configured reobfSrgFile, then the first output of the createMcpToSrg task for userdev projects, then the first output of the createMcp2Srg task for patcher projects, otherwise null.

```APIDOC
## GET /getMappings

### Description
Returns the SRG mapping file for the project. It checks for an explicitly configured reobfSrgFile, then the first output of the createMcpToSrg task for userdev projects, then the first output of the createMcp2Srg task for patcher projects, otherwise null.

### Method
GET

### Endpoint
/getMappings

### Parameters
None

### Response
#### Success Response (200)
- **result** (Object) - The SRG mapping file, or null if none apply.

#### Response Example
```json
{
  "result": "path/to/mappings.srg"
}
```
```

--------------------------------

### Method-call style for systemProperties

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/dynamic-properties.md

Method-call style is also supported. Calling systemProperties.debug('true') is equivalent to setting debug = true.

```groovy
// equivalent to debug = true:
systemProperties.debug('true')
```

--------------------------------

### Basic usage of directive methods

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Shows how to use the directive methods in a Gradle build script. The overwriteErrorLevel method can be used with an equals sign or without, and the zero-argument directives are used without parentheses.

```groovy
mixin {
    disableTargetExport        // directive form
    disableTargetValidator
    overwriteErrorLevel = 'ERROR'   // or: overwriteErrorLevel 'ERROR'
}
```

--------------------------------

### void manuallyAdd(SourceSet set)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a SourceSet manually, disabling default behavior and scheduling configuration for afterEvaluate.

```APIDOC
## void manuallyAdd(SourceSet set)

### Description
Registers a SourceSet manually, disabling default behavior and scheduling configuration for afterEvaluate.

### Method
N/A (Groovy method)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **set** (SourceSet) - Required - SourceSet to register

### Request Example
```groovy
mixin {
    manuallyAdd sourceSets.main
}
```

### Response
#### Success Response (200)
No return value.

#### Response Example
N/A

### Error Handling
No explicit error handling documented.
```

--------------------------------

### void config(String path)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a mixin config resource. The path is added to the configNames collection and included in every run configuration via --mixin.config and in reobf'd jar manifests as the MixinConfigs attribute.

```APIDOC
## POST /config

### Description
Registers a mixin config resource. The path is added to the configNames collection and included in every run configuration via --mixin.config and in reobf'd jar manifests as the MixinConfigs attribute.

### Method
POST

### Endpoint
/config

### Parameters
#### Request Body
- **path** (String) - Required - Mixin config resource name; added to every run configuration via --mixin.config <path> and to reobf'd jar manifests as the MixinConfigs attribute

### Request Example
```json
{
  "path": "my-mod.mixins.json"
}
```

### Response
#### Success Response (200)
No response body.

#### Response Example
```json
{}
```
```

--------------------------------

### Throw site in MixinExtension.checkForAnnotationProcessors

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-exception.md

Shows the only production throw site. If the major Gradle version is 5 or higher, throws MixinGradleException; otherwise logs the error.

```groovy
// MixinExtension.groovy, line ~695 (inside checkForAnnotationProcessors)
if (this.majorGradleVersion >= 5) {
    throw new MixinGradleException(message)
} else {
    this.project.logger.error message
}
```

--------------------------------

### MixinEclipse.configure() - Eclipse JDT APT integration

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-eclipse.md

Configures Eclipse JDT annotation processing for the Mixin Annotation Processor. Registers tasks 'mixinEclipseJdtApt' and 'mixinEclipseFactorypath' to generate '.settings/org.eclipse.jdt.apt.core.prefs' and '.factorypath'. If the 'eclipse' extension is missing, logs a lifecycle message and returns. If the 'com.diffplug.eclipse.apt' plugin is not applied, logs a lifecycle message and returns without wiring dependencies. Otherwise, makes the diffplug tasks depend on the registered ones.

```groovy
static void configure(MixinExtension extension, Project project) {
    def hasEclipseModel = project.extensions.findByName('eclipse')
    if (!hasEclipseModel) {
        project.logger.lifecycle 'MixinGradle is skipping eclipse integration, extension not found'
        return
    }

    def hasEclipseAptPlugin = project.plugins.findPlugin('com.diffplug.eclipse.apt') != null

    def settings = project.tasks.register('mixinEclipseJdtApt', EclipseJdtAptTask.class) {
        inputs.files project.tasks.createSrgToMcp
        inputs.files project.tasks.createMcpToSrg
        description = 'Creates the Eclipse JDT APT settings file'
        output = project.file('.settings/org.eclipse.jdt.apt.core.prefs')
        mappingsIn = extension.mappings
        hasDiffplug = hasEclipseAptPlugin
    }

    def factories = project.tasks.register('mixinEclipseFactorypath', EclipseFactoryPath.class) {
        config = project.configurations.annotationProcessor
        output = project.file('.factorypath')
    }

    if (!hasEclipseAptPlugin) {
        // These tasks don't do any useful work unless the diffplug APT plugin is applied.
        project.logger.lifecycle 'MixinGradle did not locate the diffplug APT plugin, skipping eclipse task configuration'
        return
    }

    project.tasks.eclipseJdtApt.dependsOn(settings)
    project.tasks.eclipseFactorypath.dependsOn(factories)
}
```

--------------------------------

### Enable Eclipse integration in build.gradle

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-eclipse.md

Configures Eclipse integration for MixinGradle. Requires the 'eclipse', 'com.diffplug.eclipse.apt', 'net.minecraftforge.gradle', and 'org.spongepowered.mixin' plugins. Running `gradle eclipse` (or eclipseJdtApt/eclipseFactorypath) generates .settings/org.eclipse.jdt.apt.core.prefs and .factorypath.

```groovy
// build.gradle — Eclipse integration is automatic once the eclipse extension
// and the diffplug APT plugin are present:
apply plugin: 'eclipse'
apply plugin: 'com.diffplug.eclipse.apt'
apply plugin: 'net.minecraftforge.gradle'
apply plugin: 'org.spongepowered.mixin'

mixin {
    add sourceSets.main, 'main.refmap.json'
}
// Running `gradle eclipse` (or eclipseJdtApt/eclipseFactorypath directly)
// produces:
//   .settings/org.eclipse.jdt.apt.core.prefs   (AP options for the IDE)
//   .factorypath                               (AP factory classpath)
```

--------------------------------

### config(String path) method

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Adds a mixin config resource name to the configNames list. The path is added to every run configuration via --mixin.config <path> and to reobf'd jar manifests as the MixinConfigs attribute.

```groovy
void config(String path) {
    this.configNames += path
}
```

--------------------------------

### void extraMappings(Object file)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Adds an extra mapping file to the project. The file is appended to the extraMappings collection and emitted as a -AreobfTsrgFiles=... argument.

```APIDOC
## POST /extraMappings

### Description
Adds an extra mapping file to the project. The file is appended to the extraMappings collection and emitted as a -AreobfTsrgFiles=... argument.

### Method
POST

### Endpoint
/extraMappings

### Parameters
#### Request Body
- **file** (Object) - Required - Object resolvable to a file; appended to extraMappings and emitted as -AreobfTsrgFiles=...

### Request Example
```json
{
  "file": "extra/mappings.tsrg"
}
```

### Response
#### Success Response (200)
No response body.

#### Response Example
```json
{}
```
```

--------------------------------

### Import Configuration and Library Methods

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Declares the importConfig and importLibrary methods. importConfig adds a Gradle Configuration whose files are scanned for Mixin annotations, throwing InvalidUserDataException for null arguments. importLibrary adds a single library file, also throwing InvalidUserDataException for null.

```groovy
void importConfig(Object config)    // line 1129
void importLibrary(Object lib)      // line 1136
```

--------------------------------

### Import constructor

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Constructor for the Import class. Stores the library file to be scanned for mixin classes.

```groovy
Import(File file) {
    this.file = file
}
```

--------------------------------

### @TaskAction run() contributes refmaps and MixinConfigs to reobf'd jars

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension-tasks.md

For each reobf task, finds jar tasks that depend on remappedJar (including ForgeGradle 5 producer tasks). Adds refmaps from jarRefMaps and sets MixinConfigs manifest attribute when configNames is non-empty and not already present.

```groovy
@TaskAction
def run() {
    // Add the refmap to all reobf'd jars
    this.reobfTasks.each { reobfTask ->
        def jarTasks = reobfTask.dependsOn.findAll { it == remappedJar }.toSet()
        // ForgeGradle 5 uses a mapped task output provider instead of explicitly depending on the jar task.
        // So, we need to find that task here.
        try {
            if (reobfTask.input instanceof org.gradle.api.internal.provider.ValueSupplier) {
                reobfTask.input.producer.visitProducerTasks {
                    if (it == remappedJar) {
                        jarTasks.add it
                    }
                }
            }
        } catch (Throwable e) {
            // Swallow any issues, since ValueSupplier doesn't exist on Gradle 5 and lower
        }
        jarTasks.each { jar ->
            jarRefMaps.each { artefactSpecificRefMap ->
                project.logger.info "Contributing refmap ({}) to {} in {}", artefactSpecificRefMap.refMap, jar.hasProperty('archiveFileName') ? jar.archiveFileName.get() : jar.archiveName, reobfTask.project
                jar.getRefMaps().from(artefactSpecificRefMap)
                jar.from(artefactSpecificRefMap) {
                    into artefactSpecificRefMap.refMap.parent
                }
            }
            if (this.extension.configNames && !jar.manifest.attributes.containsKey("MixinConfigs")) {
                def configNamesCsv = this.extension.configNames.join(',')
                project.logger.info "Contributing configs ({}) to manifest of {} in {}", configNamesCsv, jar.hasProperty('archiveFileName') ? jar.archiveFileName.get() : jar.archiveName, reobfTask.project
                jar.manifest.attributes['MixinConfigs'] = configNamesCsv
            }
        }
    }
}
```

--------------------------------

### MixinExtension.generateImportsFile excerpt using Imports[lib]

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Excerpt from MixinExtension.groovy showing how Imports[lib] is used to append each import to the writer. This is part of the generateImportsFile method that writes the concatenation of all imports to mixin.imports.json.

```groovy
// MixinExtension.groovy — generateImportsFile (excerpt)
for (File lib : libs) {
    Imports[lib].appendTo(writer)
}
```

--------------------------------

### void add(String set, Object refMapName)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a sourceSet by name and assigns a refmap resource name to it. Throws InvalidUserDataException if the sourceSet does not exist.

```APIDOC
## void add(String set, Object refMapName)

### Description
Registers a sourceSet by name and assigns a refmap resource name to it. Throws InvalidUserDataException if the sourceSet does not exist.

### Method
N/A (Groovy method)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **set** (String) - Required - Name of the sourceSet
- **refMapName** (Object) - Required - Refmap resource name, assigned to ext.refMap

### Request Example
```groovy
mixin {
    add 'another', 'another.refmap.json'
}
```

### Response
#### Success Response (200)
No return value.

#### Response Example
N/A

### Error Handling
- Throws InvalidUserDataException if no sourceSet with that name exists.
```

--------------------------------

### Imports.getAt(File) implementation

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Defines the Imports class with a static cache and the getAt method. Returns the cached Import for the given file, creating and scanning it on first access. Groovy's array-subscript syntax Imports[file] maps to getAt(file).

```groovy
class Imports {

    /**
     * Import cache
     */
    private static Map<File, Import> imports = [:]

    /**
     * Get import for file using array syntax
     *
     * @param file Import jar file
     * @return new or existing Import
     */
    static Import getAt(File file) {
        Import imp = Imports.imports.get(file)
        if (imp == null) {
            imp = new Import(file).read()
            Imports.imports.put(file, imp)
        }
        return imp
    }
}
```

--------------------------------

### Configure mixin block with sourceSets and refmap names

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Create a mixin block to specify which sourceSets to process and provide refmap resource names for each one. The generated refmap will be added to the compiler task outputs automatically.

```groovy
mixin {
        add sourceSets.main, "main.refmap.json"
        add sourceSets.another, "another.refmap.json"
}
```

--------------------------------

### MixinExtension accessor delegation to DynamicProperties

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/dynamic-properties.md

Shows how MixinExtension delegates its system-property accessors to the DynamicProperties tree. The getter and setter for env forward to this.systemProperties.env, and the same pattern applies to debug, checks, dumpTargetOnFailure, ignoreConstraints, hotSwap, and initialiserInjectionMode.

```groovy
// MixinExtension.groovy — representative accessor
def getEnv() {
    return this.systemProperties.env
}
def setEnv(def value) {
    this.systemProperties.env = value
}
```

--------------------------------

### Publish MixinGradle to local Maven repository

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Add the compiled jar to the local Maven repository.

```shell
gradlew publishToMavenLocal
```

--------------------------------

### add(SourceSet set) — line 887

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a source set, but first verifies it has a `refMap` or `ext.refMap` property. Throws `InvalidUserDataException` if the refMap is missing.

```groovy
void add(SourceSet set) {
    try {
        set.getRefMap()
    } catch (e) {
        throw new InvalidUserDataException(sprintf('No \'refMap\' or \'ext.refMap\' defined on %s. Call \'add(sourceSet, refMapName)\' instead.', set))
    }
    this.manuallyAdd(set)
}
```

--------------------------------

### Import appendTo(PrintWriter) method

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Fluent method that ensures the import is scanned and writes each target line to the provided PrintWriter.

```groovy
Import appendTo(PrintWriter writer) {
    this.read()
    for (String target : this.targets) {
        writer.println(target)
    }
    return this
}
```

--------------------------------

### Import readFile() method

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Package-scope method that scans the jar file for classes annotated with @Mixin and populates the targets list. Uses ASM ClassReader with SKIP_CODE, SKIP_DEBUG, and SKIP_FRAMES flags. Callable from the same package; invoked across packages through read().

```groovy
@PackageScope void readFile() {
    this.targets.clear()

    new ZipInputStream(this.file.newInputStream()).withStream { zin ->
        for (ZipEntry entry = null; (entry = zin.nextEntry) != null;) {
            if (entry.directory || !entry.name.endsWith('.class')) {
                continue
            }

            // Read the inner classes from the class file
            MixinScannerVisitor mixin = new MixinScannerVisitor()
            new ClassReader(zin).accept(mixin, ClassReader.SKIP_CODE | ClassReader.SKIP_DEBUG | ClassReader.SKIP_FRAMES)

            for (String target : mixin.targets) {
                this.targets.add(sprintf("%s\t%s", mixin.name, target))
            }
        }
    }
}
```

--------------------------------

### importLibrary(Object lib)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Adds a single library file to be scanned for Mixin annotations. Throws InvalidUserDataException if the argument is null.

```APIDOC
## importLibrary(Object lib)

### Description
Adds a single library file to be scanned for Mixin annotations. Throws `InvalidUserDataException("Cannot import null library")` for `null`.

### Method
void

### Signature
void importLibrary(Object lib)

### Parameters
- **lib** (Object) - Required - The library file (or path string) to import.

### Exceptions
- **InvalidUserDataException** - Thrown when `lib` is `null`.

### Example
```groovy
mixin {
    importLibrary 'libs/other-mixin-deps.jar'
}
```
```

--------------------------------

### add(String set) — line 877

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a source set by name. The source set is fetched using array syntax and must exist. Delegates to `add(SourceSet)`.

```groovy
void add(String set) {
    this.add(project.sourceSets[set])
}
```

--------------------------------

### Apply MixinGradle plugin

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Apply the MixinGradle plugin to the build. This is required after adding the dependency.

```groovy
apply plugin: 'org.spongepowered.mixin'
```

--------------------------------

### Static argument helpers mapToArg and listToArg

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Defines two static helper methods for serializing maps and lists into annotation processor arguments. `mapToArg` returns `-A<argName>=key=value;...` (empty string for empty map); `listToArg` returns `-A<argName>=item1;item2` (empty string for empty list). Both use a configurable separator (default `;`).

```groovy
@PackageScope static String mapToArg(String argName, Map<?, ?> map, String separator = ";") {
    map.size() < 1 ? "" : "-A${argName}=" + map.collect { token -> token.key << "=" << token.value }.join(separator)
}

@PackageScope static String listToArg(String argName, List<Object> list, String separator = ";") {
    list.size() < 1 ? "" : "-A${argName}=${list.join(separator)}"
}
```

--------------------------------

### Basic mixin block system-property usage

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/dynamic-properties.md

Basic usage of the mixin block's system-property accessors. Setting debug, env.remapRefMap, and ignoreConstraints builds the nested node tree; getArgs() returns the flattened map shown in the comment.

```groovy
mixin {
    debug = true                    // sets node mixin.debug = true
    env.remapRefMap = 'true'        // creates mixin.env, then mixin.env.remapRefMap = 'true'
    ignoreConstraints = true
}
// getArgs() yields:
// [ 'mixin.debug': true, 'mixin.env.remapRefMap': 'true', 'mixin.ignoreConstraints': true ]
```

--------------------------------

### Error handling: add without refMap

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Demonstrates the failure when `add` is called without a refMap, resulting in an `InvalidUserDataException`.

```groovy
mixin {
    add sourceSets.main
    // Throws: InvalidUserDataException: No 'refMap' or 'ext.refMap' defined on
    // source set 'main'. Call 'add(sourceSet, refMapName)' instead.
}
```

--------------------------------

### add(String set, Object refMapName) — line 903

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a source set by name and assigns a refmap resource name. Throws `InvalidUserDataException` if the source set does not exist.

```groovy
void add(String set, Object refMapName) {
    SourceSet sourceSet = project.sourceSets.findByName(set)
    if (sourceSet == null) {
        throw new InvalidUserDataException(sprintf('No sourceSet \'%s\' was found', set))
    }
    sourceSet.ext.refMap = refMapName
    this.manuallyAdd(sourceSet)
}
```

--------------------------------

### apply(Project project) - Groovy

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-plugin.md

Called by Gradle when the plugin is applied. Validates the environment and creates the 'mixin' extension. Throws InvalidUserDataException if environment validation fails.

```groovy
@Override
void apply(Project project) {
    // This will throw an exception if any criteria are not met
    this.checkEnvironment(project)

    // create the mixin extension
    project.extensions.create('mixin', MixinExtension.class, project)
}
```

--------------------------------

### Configure Mixin imports with importConfig and importLibrary

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/meta-import.md

Configure the Mixin extension in a build.gradle file to scan dependencies for @Mixin targets. Use importConfig to scan every file of a configuration (e.g., 'compile') and importLibrary to scan a specific jar. Each referenced jar is cached via Imports[file] and its @Mixin targets are aggregated into mixin.imports.json, which is passed to the annotation processor as -AdependencyTargetsFile=...

```groovy
// build.gradle — configuring imports for the AP
mixin {
    importConfig 'compile'                    // scan every file of the 'compile' configuration
    importLibrary 'libs/shared-mixins.jar'    // scan one specific library
}
// Each referenced jar is cached via Imports[file] and its @Mixin targets are
// aggregated into mixin.imports.json, passed to the AP as -AdependencyTargetsFile=...
```

--------------------------------

### Complete MixinGradle configuration block

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/configuration.md

Complete MixinGradle configuration block for a Gradle build script. It adds refmap files, specifies the mixins config, defines a token, sets extra mappings, disables target validation and export, sets the default obfuscation environment to notch, enables quiet mode, and sets debug to true.

```groovy
mixin {
    add sourceSets.main, 'main.refmap.json'
    add 'client', 'client.refmap.json'
    config 'example.mixins.json'
    token 'modid', 'example'
    extraMappings 'extra/mappings.tsrg'
    disableTargetValidator
    disableTargetExport
    defaultObfuscationEnv notch
    quiet
    debug = true
}
```

--------------------------------

### add(SourceSet set, Object refMapName) — line 919

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Registers a source set and assigns a refmap resource name. The refMapName is stringified and stored in `ext.refMap`.

```groovy
void add(SourceSet set, Object refMapName) {
    set.ext.refMap = refMapName.toString()
    this.manuallyAdd(set)
}
```

--------------------------------

### EclipseJdtAptTask run() task action

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-eclipse.md

Task action for EclipseJdtAptTask that writes Eclipse JDT APT preferences and processor options to the output file. When hasDiffplug is false, it includes the standard Eclipse preference boilerplate; with diffplug, only processor options are written. Options are sourced from the resolved MixinExtension, including reobfTsrgFile, outTsrgFile, outRefMapFile, pluginVersion, and conditional options.

```groovy
@TaskAction
def run() {
    MixinExtension extension = project.extensions.findByType(MixinExtension.class)
    def props = new OrderedProperties()
    if (!hasDiffplug) {
        props.put('eclipse.preferences.version', '1')
        props.put('org.eclipse.jdt.apt.aptEnabled', 'true')
        props.put('org.eclipse.jdt.apt.reconcileEnabled', 'true')
        props.put('org.eclipse.jdt.apt.genSrcDir', genDir.canonicalPath)
        props.put('org.eclipse.jdt.apt.genSrcTestDir', genTestDir.canonicalPath)
    }
    props.arg('reobfTsrgFile', mappingsIn.canonicalPath)
    props.arg('outTsrgFile', mappingsOut.canonicalPath)
    props.arg('outRefMapFile', refmapOut.canonicalPath)
    props.arg('pluginVersion', MixinGradlePlugin.VERSION)

    if (extension.disableTargetValidator) { props.arg('disableTargetValidator', 'true') }
    if (extension.disableTargetExport)   { props.arg('disableTargetExport', 'true') }
    if (extension.disableOverwriteChecker) { props.arg('disableOverwriteChecker', 'true') }
    if (extension.overwriteErrorLevel != null) { props.arg('overwriteErrorLevel', extension.overwriteErrorLevel.toString().trim()) }
    if (extension.defaultObfuscationEnv != null) { props.arg('defaultObfuscationEnv', extension.defaultObfuscationEnv) }
    if (extension.mappingTypes.size() > 0) { props.arg('mappingTypes', extension.mappingTypes.join(',')) }
    if (extension.tokens.size() > 0) { props.arg('tokens', extension.tokens.collect { token -> token.key + ' ' + token.value }.join(';')) }
    if (extension.extraMappings.size() > 0) { props.arg('reobfTsrgFiles', extension.extraMappings.collect { file -> project.file(file).toString() }.join(';')) }

    props.store(output.newWriter(hasDiffplug), null);
}
```

--------------------------------

### Set default obfuscation environment

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Set the default obfuscation environment for generated refmaps. This environment will be contributed to the refmap's mappings node. Specify "notch" or "searge".

```groovy
mixin {
        // Specify "notch" or "searge" here
        defaultObfuscationEnv notch
}
```

--------------------------------

### Set mixin AP options as directives

Source: https://github.com/spongepowered/mixingradle/blob/master/README.md

Alternatively, configure the same mixin AP options by issuing them as directives in the mixin block.

```groovy
mixin {
        disableTargetExport
        disableTargetValidator
}
```

--------------------------------

### extraMappings(Object file) method

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Appends a file to the extraMappings list. The file is emitted as -AreobfTsrgFiles=... in the build.

```groovy
void extraMappings(Object file) {
    this.extraMappings += file
}
```

--------------------------------

### Configure Mixin Imports

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Configures Mixin imports using the mixin block. importConfig adds a configuration named 'compile', and importLibrary adds a library file. Imports are resolved into mixin.imports.json and passed to the annotation processor as -AdependencyTargetsFile.

```groovy
mixin {
    importConfig 'compile'
    importLibrary 'libs/other-mixin-deps.jar'
}
```

--------------------------------

### importConfig(Object config)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Adds a Gradle Configuration (or configuration-name string) whose files will be scanned for Mixin annotations. Throws InvalidUserDataException if the argument is null.

```APIDOC
## importConfig(Object config)

### Description
Adds a Gradle Configuration (or configuration-name string) whose files will be scanned for Mixin annotations. Throws `InvalidUserDataException("Cannot import from null config")` for a `null` argument.

### Method
void

### Signature
void importConfig(Object config)

### Parameters
- **config** (Object) - Required - The Gradle Configuration object or configuration-name string to import.

### Exceptions
- **InvalidUserDataException** - Thrown when `config` is `null`.

### Example
```groovy
mixin {
    importConfig 'compile'
}
```
```

--------------------------------

### showMessageTypes()

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Sets the showMessageTypes property to true, enabling message type display.

```APIDOC
## showMessageTypes()

### Description
Sets `showMessageTypes = true`.

### Method
N/A (Directive method)

### Endpoint
N/A

### Parameters
None

### Request Example
```groovy
mixin {
    showMessageTypes
}
```

### Response
#### Success Response
- **showMessageTypes** (boolean) - Set to `true`

#### Response Example
N/A
```

--------------------------------

### Add tokens with token and tokens methods

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/configuration.md

Adds tokens using the token method with an explicit value and the tokens method with a map. The tokens method does not return this, so it evaluates to null.

```groovy
mixin {
    token 'my.option', 'value'
    tokens([ 'modid': 'example' ])   // method-call form; despite the declared
                                     // MixinExtension return type there is no
                                     // `return this`, so it evaluates to null
}
```

--------------------------------

### token(Object name, Object value)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-extension.md

Adds a token with the given name and value. Both name and value are trimmed to their string representations before being stored.

```APIDOC
## token(Object name, Object value)

### Description
Adds a token with the given name and value. Both name and value are trimmed to their string representations before being stored.

### Method
void

### Signature
`void token(Object name, Object value)`

### Parameters
- **name** (Object) - Required - The name of the token.
- **value** (Object) - Required - The value of the token. The string representation is trimmed.

### Example
```groovy
mixin {
    token 'mixin.debug', 'true'
}
```

### Notes
- The name is trimmed using `name.toString().trim()`.
- The value is trimmed using `value.toString().trim()`.
```

--------------------------------

### Applying MixinGradle without ForgeGradle (fails)

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-plugin.md

Shows the failure when applying the MixinGradle plugin without ForgeGradle. Throws InvalidUserDataException at apply time because the 'minecraft' or 'patcher' property is missing.

```groovy
// build.gradle — applying MixinGradle without ForgeGradle
apply plugin: 'org.spongepowered.mixin'
// FAILS at plugin application:
// InvalidUserDataException: Could not find property 'minecraft', or
// 'patcher' on root project 'demo', ensure ForgeGradle is applied.
```

--------------------------------

### Message assembly for missing annotation processors

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-exception.md

Builds the error message listing missing annotation processor configurations and suggests a fix.

```groovy
def message = "$gradleVersion was detected but the mixin dependency was missing from one or more Annotation Processor " +
    "configurations: $missingAPNames. To enable the Mixin AP please include the mixin processor artefact in each Annotation " +
    "Processor configuration. For example if you are using mixin dependency 'org.spongepowered:mixin:$mixinVersion' you " +
    "should specify: dependencies { $addAPName 'org.spongepowered:mixin:$mixinVersion:processor' }$eachOfThese. If you " +
    "believe you are seeing this message in error, you can disable this check via by adding disableAnnotationProcessorCheck() " +
    "to your mixin { } block."
```

--------------------------------

### Constructor with message only

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-gradle-exception.md

Creates a MixinGradleException with a message. The message is shown to the user when the build fails.

```java
public MixinGradleException(String message) {
    super(message);
}
```

--------------------------------

### OrderedProperties with insertion-order keys and arg() helper

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/mixin-eclipse.md

Implements OrderedProperties, a java.util.Properties subclass that retains insertion order. keys() enumerates keys in insertion order, put() records the key before delegating to Properties.put, and arg() stores a value under the Eclipse processor-option key prefix org.eclipse.jdt.apt.processorOptions/<key>.

```groovy
def order = new LinkedHashSet<Object>()

@Override
public synchronized Enumeration<Object> keys() {
    return Collections.enumeration(order)
}

@Override
public synchronized Object put(Object key, Object value) {
    order.add(key)
    return super.put(key, value)
}

public Object arg(String key, String value) {
    return put('org.eclipse.jdt.apt.processorOptions/' + key, value)
}
```

--------------------------------

### DynamicProperties constructor

Source: https://github.com/spongepowered/mixingradle/blob/master/_autodocs/api-reference/dynamic-properties.md

Constructor for a DynamicProperties node. The root node is constructed with "mixin" in MixinExtension.

```groovy
DynamicProperties(String name) {
    this.name = name
}
```
Tokens:
Raw