### Enigma mapping file format example

Source: https://context7.com/fabricmc/yarn/llms.txt

This example demonstrates the Enigma text format used for mapping files. It includes class, field, and method declarations with comments that translate to Javadoc. Ensure correct class/member descriptors and argument documentation.

```mapping
# mappings/net/minecraft/block/AbstractBlock.mapping

CLASS net/minecraft/class_4970 net/minecraft/block/AbstractBlock
    COMMENT An abstract class that defines some logic for {@link Block Blocks}.
    COMMENT <strong>This class should not be extended directly. Extend {@link Block} instead.</strong>

    FIELD field_26153 cachedState Lnet/minecraft/block/BlockState;
        COMMENT The default block state, cached for fast access.

    METHOD method_9517 getDefaultState ()Lnet/minecraft/block/BlockState;
        COMMENT Gets the default (base) state of this block.

    METHOD method_9516 onBlockAdded (Lnet/minecraft/block/BlockState;Lnet/minecraft/world/World;...)V
        COMMENT Called after this block is placed in the world.
        ARG 1 state
            COMMENT the placed block state
        ARG 2 world
        ARG 3 pos
```

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

### Example Unpick Definition

Source: https://context7.com/fabricmc/yarn/llms.txt

An example of an unpick definition file using v4 syntax. It defines a group for ARGB colors and targets specific methods for parameter mapping.

```unpick
# Example unpick definition (unpick-definitions/colors.unpick):
unpick v4

group int argb_color
    @format hex
    net.minecraft.util.Colors.*

target_method net.minecraft.util.math.ColorHelper getArgb (IIII)I
    return argb_color
target_method net.minecraft.util.math.ColorHelper getAlpha (I)I
    param 0 argb_color

```

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

### Javadoc Linking Example

Source: https://github.com/fabricmc/yarn/blob/1.21.11/CONVENTIONS.md

Demonstrates how to use @link, @linkplain, and @see tags to refer to other code elements. Simple names can be used for classes from java.lang, the same package, or those used in signatures. Otherwise, fully qualify the name.

```java
/**
 * Assume this class is from the {@code net.example.stuff} package.
 *
 * <p>You can link to {@link Optional} as it's part of the class signature (type parameter bound).
 *
 * <p>You must fully qualify {@link net.example.stuff.basic.BasicStuffUser} when linking as it is not in
 * any signature and is from a different package.
 */
public class Stuff<T extends Optional<?>> {
	/**
	 * You can link to {@link Listener} with the simple name as it's part of a field's signature.
	 */
	protected Listener listener;

	/**
	 * You can link to {@link List} with the simple name as it's part of a method's signature.
	 *
	 * <p>You must fully qualify {@link net.example.util.UtilityClass} when linking because it is not part
	 * of any signature (even though it is used in code) and is from a different package.
	 */
	public Stuff(List<Integer> opt) {
		UtilityClass.callMethod(opt);
	}
}
```

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

### Example annotations.json structure

Source: https://context7.com/fabricmc/yarn/llms.txt

This JSON file defines annotations for methods and fields within Minecraft classes. Ensure the 'version' and 'namespace' are set correctly, and class/method descriptors match the target JAR.

```json
// annotations.json format example:
{
  "version": 1,
  "namespace": "named",
  "classes": {
    "net/minecraft/util/math/BlockPos": {
      "methods": {
        "add(Lnet/minecraft/util/math/Vec3i;)Lnet/minecraft/util/math/BlockPos;": {
          "add": [
            {
              "desc": "Lorg/jetbrains/annotations/Contract;",
              "values": { "pure": { "type": "boolean", "value": true } }
            }
          ]
        }
      }
    }
  }
}
```

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

### Bad Javadoc Parameter Example

Source: https://context7.com/fabricmc/yarn/llms.txt

Illustrates a Javadoc parameter documentation style violation where the comment ends with a period. Correct style places comments directly on the parameter entry.

```text
# Bad (parameter doc ends with '.'):
ARG 1 blockPos
    COMMENT The block position.

```

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

### Merge Intermediary and Yarn Mappings to Tiny v1

Source: https://context7.com/fabricmc/yarn/llms.txt

Use `MergeMappingsTask` to combine multiple Tiny mapping files. This example merges intermediary and v1 named mappings, setting the source namespace to 'official' and output to Tiny v1 format.

```groovy
import net.fabricmc.filament.task.mappingio.MergeMappingsTask
import net.fabricmc.mappingio.format.MappingFormat

tasks.register('mergeTiny', MergeMappingsTask) {
    group = 'mapping build'
    // Order matters: intermediary first, then yarn named mappings
    mappingInputs.from downloadIntermediary.output       // official→intermediary
    mappingInputs.from convertToV1.output                // intermediary→named (v1)
    output = new File(buildDir, "temp/mappings.tiny")
    outputFormat = MappingFormat.TINY_FILE               // Tiny v1 output
}
```

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

### Launch Yarn Mapping Editor

Source: https://context7.com/fabricmc/yarn/llms.txt

Launches the Enigma GUI mapping editor. Pre-configured with merged intermediary JAR, mappings, unpick definitions, and annotations. Pass extra JVM flags if needed.

```bash
# Open the full (client+server merged) mapping editor
./gradlew yarn

# Open the server-only (common) mapping editor
./gradlew yarnCommon

# Pass extra JVM flags to Enigma (e.g. disable grab for virtual desktops)
./gradlew yarn -Dsun.awt.disablegrab=true
```

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

### Run Full Build for Artifacts

Source: https://context7.com/fabricmc/yarn/llms.txt

Performs a full build to produce all distributable artifacts, including compressed tiny mappings, v1 and v2 tiny JARs, and Javadoc JAR. This task is used in CI.

```bash
# Full build producing all artifacts under build/libs/
./gradlew build

# Artifacts produced:
#   build/libs/yarn-1.21.11+build.42.jar               (v1 tiny, inside mappings/mappings.tiny)
#   build/libs/yarn-1.21.11+build.42-v2.jar            (v2 unmerged + unpick + annotations extras)
#   build/libs/yarn-1.21.11+build.42-mergedv2.jar      (v2 merged official+intermediary+named)
#   build/libs/yarn-1.21.11+build.42-javadoc.jar
#   build/yarn-1.21.11+build.42-tiny.gz
```

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

### Complete Mappings with Intermediary Fallbacks

Source: https://context7.com/fabricmc/yarn/llms.txt

Use `CompleteMappingsTask` to read a Tiny v2 mapping file and fill any unmapped 'named' entries with their 'intermediary' names, ensuring no gaps in the final mapping.

```groovy
import net.fabricmc.filament.task.mappingio.CompleteMappingsTask
import net.fabricmc.mappingio.format.MappingFormat

tasks.register('completeMappings', CompleteMappingsTask) {
    input  = mapSpecializedMethods.output    // Tiny v2 with possible gaps
    output = new File(buildDir, "temp/yarn-mappings-v2.tiny")
    outputFormat = MappingFormat.TINY_2_FILE
}
// All named entries without a mapping now fall back to their intermediary name
```

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

### Publish Yarn Mappings

Source: https://context7.com/fabricmc/yarn/llms.txt

Command to build, Javadoc, check version, and publish Yarn mappings. The build number is injected from GitHub Actions tag counter. Requires Maven credentials.

```bash
./gradlew build javadocJar checkVersion publish \
    -PMAVEN_URL=$MAVEN_URL \
    -PMAVEN_USERNAME=$MAVEN_USERNAME \
    -PMAVEN_PASSWORD=$MAVEN_PASSWORD
```

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

### Configure Filament Gradle Plugin

Source: https://context7.com/fabricmc/yarn/llms.txt

Configure the Filament plugin by setting the target Minecraft version. This is the only required property. Optionally, override the manifest URL.

```groovy
plugins {
    id 'net.fabricmc.filament'
}

def minecraft_version = "1.21.11"

filament {
    minecraftVersion = minecraft_version
    // optional: override the manifest URL
    // minecraftVersionManifestUrl = "https://piston-meta.mojang.com/mc/game/version_manifest_v2.json"
}
```

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

### Format Enigma Mappings In-Place

Source: https://context7.com/fabricmc/yarn/llms.txt

Use the `formatMappings` Gradle task to sort and format all Enigma mapping files. For CI, run this task and then check for git diffs to ensure consistency.

```bash
# Format and sort all mapping files in-place
./gradlew formatMappings

# CI check: run formatMappings then verify git has no diff
./gradlew formatMappings
git add -A && git diff --cached --exit-code   # fails if any file was reformatted
```

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

### Configure MapJarTask for Custom Remapping

Source: https://context7.com/fabricmc/yarn/llms.txt

Use this task to remap JAR files between namespaces using Tiny mappings. Configure input, output, mappings, namespaces, and optional class mappings.

```groovy
import net.fabricmc.filament.task.MapJarTask

tasks.register('myRemap', MapJarTask) {
    input  = file("build/my-mod-intermediary.jar")
    output = layout.buildDirectory.file("my-mod-named.jar")
    mappings = tasks.named("mergeV2").flatMap { it.output }  // merged v2 tiny
    from = 'intermediary'
    to   = 'named'
    classpath.from configurations.minecraftLibraries

    // Optional: remap specific class references (e.g. annotation shims)
    classMappings = [
        "javax/annotation/Nullable" : "org/jetbrains/annotations/Nullable",
        "javax/annotation/Nonnull"  : "org/jetbrains/annotations/NotNull"
    ]
}
```

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

### Configure GzipTask for mapping file compression

Source: https://context7.com/fabricmc/yarn/llms.txt

This Gradle task uses GzipTask to compress mapping files, typically for generating the legacy `yarn-<version>-tiny.gz` artifact. Ensure the input file path and desired output filename are correctly specified.

```groovy
import net.fabricmc.filament.task.GzipTask

tasks.register('compressTiny', GzipTask) {
    group    = 'mapping build'
    input    = mergeTiny.output
    fileName = "yarn-tiny-${yarnVersion}"
    // output defaults to: build/${fileName}.gz
}
// Produces: build/yarn-tiny-1.21.11+build.42.gz
```

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

### Convert Mappings to Tiny v1

Source: https://context7.com/fabricmc/yarn/llms.txt

Converts mappings from Tiny v2 specialized-methods output to Tiny v1 format. Ensure the input and output paths are correctly configured.

```groovy
import net.fabricmc.filament.task.mappingio.ConvertMappingsTask
import net.fabricmc.mappingio.format.MappingFormat

tasks.register('convertToV1', ConvertMappingsTask) {
    input  = mapSpecializedMethods.output          // Tiny v2 input
    output = new File(buildDir, "temp/yarn-mappings.tiny")
    outputFormat = MappingFormat.TINY_FILE         // Tiny v1 output
}
```

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

### Generate Fake Source for Javadoc

Source: https://context7.com/fabricmc/yarn/llms.txt

Uses MappingPoet to generate stub Java source files from Tiny mappings and the named JAR. These stubs include Javadoc from Enigma files and are used by the `javadoc` task. Ensure mappings, minecraftJar, libraries, and output are configured.

```groovy
import net.fabricmc.filament.task.MappingPoetTask

tasks.register('genFakeSource', MappingPoetTask) {
    group       = "javadoc generation"
    mappings    = mergeV2.output                  // merged-v2.tiny
    minecraftJar = mapNamedJar.output             // named JAR for type resolution
    libraries.from configurations.minecraftLibraries
    output      = file(".gradle/temp/fakeSource") // directory of generated .java stubs
}

// Wire into javadoc:
javadoc {
    dependsOn genFakeSource
    source fileTree(genFakeSource.output) + sourceSets.packageDocs.allJava
    classpath = configurations.javadocClasspath + configurations.minecraftLibraries
    // …options…
}
```

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

### Combine Unpick Definitions

Source: https://context7.com/fabricmc/yarn/llms.txt

Merges all `.unpick` files from the `unpick-definitions/` directory into a single output file. This task is already registered as 'combineUnpickDefinitions' by FilamentGradlePlugin, but can be overridden.

```groovy
// Already registered by FilamentGradlePlugin as 'combineUnpickDefinitions'.
// Override input/output if needed:
combineUnpickDefinitions {
    group = 'unpick'
    input  = file('unpick-definitions')           // directory of *.unpick files
    output = new File(buildDir, 'temp/definitions.unpick')
}
```

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

### Merge Mappings to Tiny v2

Source: https://context7.com/fabricmc/yarn/llms.txt

This configuration of `MergeMappingsTask` merges intermediary and proposed named mappings into a Tiny v2 file, ensuring full merging capabilities.

```groovy
// For v2 output with full merging:
tasks.register('mergeV2', MergeMappingsTask) {
    mappingInputs.from downloadIntermediary.output
    mappingInputs.from insertNameProposalMappings.output
    output = new File(buildDir, "temp/merged-v2.tiny")
    outputFormat = MappingFormat.TINY_2_FILE
}
```

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

### Override FormatMappingsTask Input

Source: https://context7.com/fabricmc/yarn/llms.txt

The `formatMappings` task is registered by default. If you need to specify a different input directory for Enigma mappings, override the `input` property.

```groovy
// Task is already registered by Filament; override its input if needed:
formatMappings {
    input = file("mappings")   // default; points to the Enigma dir
}
```

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

### Run Mapping Check

Source: https://context7.com/fabricmc/yarn/llms.txt

Validates mapping files for duplicates and self-mappings. Can be run standalone or as part of the standard check task.

```bash
# Run standalone mapping check
./gradlew checkMappings
```

```bash
# Also runs as part of the standard check task:
./gradlew check
# → checkMappings, checkMergedMappings, checkUnpickDefinitions, checkAnnotations,
#   remapIntermediaryJar, javadocLint
```

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

### Run Javadoc Lint Check

Source: https://context7.com/fabricmc/yarn/llms.txt

Checks for common Javadoc style violations in mapping files, such as incorrect parameter documentation. Fails the build with a count of violations. Can be run standalone or as part of the 'check' task.

```bash
# Run standalone
./gradlew javadocLint

# Runs automatically as part of check:
./gradlew check
```

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

### Local build command for FabricMC Yarn

Source: https://context7.com/fabricmc/yarn/llms.txt

This bash command executes the Gradle build task locally. It generates artifacts with a 'local' build number, useful for testing before publishing.

```bash
# Local build (build_number = "local"):
./gradlew build
# Artifact IDs: yarn-1.21.11+build.local.jar, yarn-1.21.11+build.local-v2.jar, …
```

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

### Convert Enigma to Tiny v2

Source: https://context7.com/fabricmc/yarn/llms.txt

Converts mappings from Enigma format to Tiny v2 format. The input is a directory containing Enigma files, and the output is a Tiny v2 file.

```groovy
// Convert an Enigma directory to Tiny v2:
tasks.register('enigmaToTinyV2', ConvertMappingsTask) {
    input  = file("mappings")
    output = layout.buildDirectory.file("enigma-as-tinyv2.tiny")
    outputFormat = MappingFormat.TINY_2_FILE
}
```

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

### Configure DownloadTask for Cached File Downloads

Source: https://context7.com/fabricmc/yarn/llms.txt

This task downloads a remote file with optional SHA-1 verification, automatically caching it. Use it to download mappings or other necessary files.

```groovy
import net.fabricmc.filament.task.DownloadTask

tasks.register('downloadIntermediary', DownloadTask) {
    group = 'mapping build'
    url = "https://github.com/FabricMC/intermediary/raw/master/mappings/1.21.11.tiny"
    // sha1 is optional; omit it to use default time-based caching
    // sha1 = "abc123..."
    output = layout.buildDirectory.file("intermediary-1.21.11.tiny")
}

// The output is then wired into other tasks:
tasks.named('mapIntermediaryJar').configure {
    dependsOn downloadIntermediary
    mappings = downloadIntermediary.output
}
```

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

### Remap and Decompile JARs

Source: https://context7.com/fabricmc/yarn/llms.txt

Remaps the intermediary JAR to the Yarn 'named' namespace using TinyRemapper. Then, decompiles the resulting JAR using CFR or Vineflower.

```bash
# Produce the named JAR for decompilation
./gradlew mapNamedJar
# Output: build/1.21.11-named.jar

# Then decompile with CFR
./gradlew decompileCFR
# Output: build/namedSrc/

# Or decompile with Vineflower (better generics/lambdas)
./gradlew decompileVineflower
# Output: build/namedSrc/
```

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

### Programmatic usage of MappingNameCompleter

Source: https://context7.com/fabricmc/yarn/llms.txt

This Java code snippet demonstrates how to programmatically use the MappingNameCompleter utility to propose names for unmapped entries in Yarn mappings. Provide correct paths to the intermediary and Yarn mapping files.

```java
// Standalone CLI usage (four positional arguments):
// java -cp filament.jar net.fabricmc.filament.nameproposal.MappingNameCompleter \
//     <intermediaryJar> <inputYarnMappings> <inputIntermediaryMappings> <outputYarnMappings>

// Programmatic usage from a Gradle doLast block:
MappingNameCompleter.completeNames(
    Paths.get(intermediaryJarPath),          // .jar in intermediary namespace
    Paths.get(inputYarnMappingsPath),        // Tiny v2, intermediary→named
    Paths.get(inputIntermediaryMappingsPath),// Tiny file, official→intermediary
    Paths.get(outputYarnMappingsPath),       // Tiny v2 output with proposed names
    NameProposalConfig.DEFAULT               // controls which strategies are enabled
);
// Prints to stdout:
// Found 1234 field names
// Found 56 method names
// Found 89 record names
// Found 23 record constructors
```

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

### Consume Yarn in Fabric Mod Project

Source: https://context7.com/fabricmc/yarn/llms.txt

Configuration for a Fabric mod project's `settings.gradle` or `build.gradle` file to consume Yarn mappings via fabric-loom. Specifies Minecraft, Yarn mappings, and Fabric loader versions.

```groovy
plugins {
    id 'fabric-loom' version '1.12.0-alpha.39'
}
dependencies {
    minecraft "com.mojang:minecraft:1.21.11"
    mappings "net.fabricmc:yarn:1.21.11+build.42:v2"   // v2 classifier
    modImplementation "net.fabricmc:fabric-loader:0.16.10"
}
```

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

### Unpick JAR Task Configuration

Source: https://context7.com/fabricmc/yarn/llms.txt

Configures the `UnpickJarTask` to apply unpick transformations to a JAR file. This replaces inlined integer literals with symbolic constant references. Ensure the input JAR, output file, unpick definition, and classpath are correctly set.

```groovy
import net.fabricmc.filament.task.unpick.UnpickJarTask

tasks.register('unpickIntermediaryJar', UnpickJarTask) {
    group = 'unpick'
    input            = mapIntermediaryJar.output
    output           = layout.buildDirectory.file("1.21.11-intermediary-unpicked.jar")
    unpickDefinition = remapUnpickDefinitionsIntermediary.output  // remapped .unpick
    classpath.from minecraftLibraries                             // for class resolution
}
// The resulting JAR has e.g. GlConst.GL_TRIANGLES instead of the raw int 4
```

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

### Configure CheckAnnotationsTask for annotation consistency

Source: https://context7.com/fabricmc/yarn/llms.txt

This Gradle task validates the annotations.json file against a named Minecraft JAR. Ensure annotations.json is correctly formatted and the target JAR is available.

```groovy
tasks.register('checkAnnotations', CheckAnnotationsTask) {
    group = 'annotations'
    input = file('annotations.json')
    targetJars.from(mapNamedNoUnpickJar)      // named JAR to verify against
    classpath.from(minecraftLibraries)
}
check.dependsOn checkAnnotations
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.