From 186e37ede9461e09baf9bbe615d4f3b3ae45ccc6 Mon Sep 17 00:00:00 2001 From: haykam821 <24855774+haykam821@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:39:29 -0400 Subject: [PATCH] Revamp README to address project state --- CONTRIBUTING.md | 9 +++--- README.md | 85 ++++++++++++++++++++++++++++++++++--------------- 2 files changed, 64 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04f6c1f8f7..e159007b0d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,7 @@ # Contributing -Please remember that copying and pasting mappings from alternate projects under more restrictive licenses (such as MCP or Mojang's obfuscation maps) -is **completely forbidden** without explicit permission from the owners of said mappings to distribute the names under the CC0 license. -This includes using the names from those mappings for inspiration. Discussing the naming approaches used in said projects -is also not welcome - you have been warned. However, it is a good idea to consult name changes with other people - use pull requests or our community spaces to ask questions! +Please remember that copying and pasting mappings from alternate projects under more restrictive licenses (such as MCP, Spigot's or Mojang's obfuscation maps), as well as unobfuscated Minecraft releases, is **completely forbidden** without explicit permission from the owners of said mappings to distribute the names under the CC0 license. This includes using the names from those sources for inspiration. Discussing the naming approaches used in said projects is also not welcome - you have been warned. However, it is a good idea to consult name changes with other people - feel free to use pull requests or issues to ask questions! -Please have a look at the [naming conventions](/CONVENTIONS.md) before submitting mappings. +Feel free to contribute pull requests adding names and documentation from newer Yarn releases to branches focusing on older Minecraft versions ("backports"). Just make sure what you are backporting is still accurate for the older Minecraft version! + +Please have a look at the [Yarn naming conventions](/CONVENTIONS.md) before submitting mappings. diff --git a/README.md b/README.md index 6bbd79ae33..4515dd425e 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,37 @@ # Yarn -Yarn is a set of open, unencumbered Minecraft mappings, free for everyone to use under the Creative Commons Zero license. The intention is to let -everyone mod Minecraft freely and openly, while also being able to innovate and process the mappings as they see fit. +> [!NOTE] +> Yarn is no longer being updated to new Minecraft versions past Minecraft 1.21.11. The goal now is to make the best mapping set for these obfuscated versions of Minecraft! -Some icons in Filament, which we use to develop Yarn, are licensed under Apache-2.0. These can be found in `filament/src/main/resources/icons`. -These icons are not shipped with Yarn. +Yarn is a set of open, unencumbered Minecraft mappings, free for everyone to use under the [Creative Commons Zero license](/LICENSE). The intention is to let everyone mod Minecraft freely and openly, while also being able to innovate and process the mappings as they see fit. -To see the current version being targeted, check the branch name! +Some icons in Filament, which we use to develop Yarn, are licensed under Apache-2.0. These icons can be found in the `filament/src/main/resources/icons` directory. They are not shipped with releases of Yarn. + +Yarn has been released for Minecraft 1.14 through 1.21.11 across hundreds of Git branches. To see the Minecraft version being targeted, check the branch name! ## Usage -To use yarn-deobfuscated Minecraft for Minecraft modding or as a dependency in a Java project, you can use [loom](https://github.com/fabricmc/fabric-loom) Gradle plugin. See [fabric wiki tutorial](https://fabricmc.net/wiki/tutorial:setup) for more information. -To obtain a deobfuscated Minecraft jar, [`./gradlew mapNamedJar`](#mapNamedJar) will generate a jar named like `-named.jar`, which can be sent to a decompiler for deobfuscated code. +To use the Yarn-mapped Minecraft API for Minecraft modding or as a dependency in a Java project, you can use the [Fabric Loom](https://github.com/fabricmc/fabric-loom) Gradle plugin. With Fabric Loom, you can configure your `build.gradle` file to indicate that you would like to use the Yarn mappings: + +```gradle +dependencies { + minecraft "com.mojang:minecraft:${project.minecraft_version}" + mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2" + modImplementation "net.fabricmc:fabric-loader:${project.loader_version}" + + // Plus any other dependencies you are using! +} +``` -Please note to run the yarn build script **Java 17** or higher is required! +You can find the latest Yarn version for a given Minecraft version from the [developing with Fabric](https://fabricmc.net/develop) page. ## Contributing -Please remember that copying and pasting mappings from alternate projects under more restrictive licenses (such as MCP, Spigot's or Mojang's obfuscation maps) -is **completely forbidden** without explicit permission from the owners of said mappings to distribute the names under the CC0 license. -This includes using the names from those mappings for inspiration. Discussing the naming approaches used in said projects -is also not welcome - you have been warned. However, it is a good idea to consult name changes with other people - use pull requests or our community spaces to ask questions! +Please remember that copying and pasting mappings from alternate projects under more restrictive licenses (such as MCP, Spigot's or Mojang's obfuscation maps), as well as unobfuscated Minecraft releases, is **completely forbidden** without explicit permission from the owners of said mappings to distribute the names under the CC0 license. This includes using the names from those sources for inspiration. Discussing the naming approaches used in said projects is also not welcome - you have been warned. However, it is a good idea to consult name changes with other people - feel free to use pull requests or issues to ask questions! -Please have a look at the [naming conventions](/CONVENTIONS.md) before submitting mappings. +Feel free to contribute pull requests adding names and documentation from newer Yarn releases to branches focusing on older Minecraft versions ("backports"). Just make sure what you are backporting is still accurate for the older Minecraft version! + +Please have a look at the [Yarn naming conventions](/CONVENTIONS.md) before submitting mappings. ### Getting Started @@ -31,31 +40,57 @@ Please have a look at the [naming conventions](/CONVENTIONS.md) before submittin 3. Commit and push your work to your fork 4. Open a pull request with your changes +Please note that to run the Yarn build script, **Java 21** or higher is required! + ## Gradle -Yarn uses Gradle to provide a number of utility tasks for working with the mappings. + +Yarn uses [Gradle](https://gradle.org/) to provide a number of utility tasks for working with the mappings. ### `yarn` -Setup and download and launch the latest version of [Enigma](https://github.com/FabricMC/Enigma) automatically configured to use the merged jar and the mappings. -Compared to launching Enigma externally, the gradle task adds a name guesser plugin that automatically maps enums and a few constant field names. +This task downloads and launches the latest version of [Enigma](https://github.com/FabricMC/Enigma), which is automatically configured to use the merged Minecraft JAR and the local directory's mappings. + +Compared to launching Enigma externally, the Gradle task adds enhancements such as a plugin to automatically suggest certain names, including the names of enum members, constant fields, and record components. ### `yarnCommon` -Same as `yarn`, but will only show common classes. + +This task is similar to `yarn`, but will only show "common" classes, which are classes present in both the Minecraft client and dedicated server JARs. ### `build` -Build a GZip'd archive containing a tiny mapping between official (obfuscated), [intermediary](https://github.com/FabricMC/intermediary), and yarn names ("named") and packages enigma mappings into a zip archive.. + +Produces packaged artifacts for the Yarn mappings, including: + +- `build/libs/yarn-{version}-mergedv2.jar`: a JAR containing a [Tiny v2](https://wiki.fabricmc.net/documentation:tiny2) mappings file between the `official`, `intermediary`, and `named` namespaces, as well as extras including Unpick and annotation definitions +- `build/libs/yarn-{version}-v2.jar`: similar to above, but only contains the `intermediary` and `named` namespaces +- `build/libs/yarn-{version}.jar`: a legacy JAR containing only a [Tiny v1](https://wiki.fabricmc.net/documentation:tiny) mappings file between the `official`, `intermediary`, and `named` namespaces +- `build/libs/yarn-{version}-javadoc.jar`: HTML [Javadoc](https://openjdk.org/groups/compiler/javadoc-architecture.html) output representing the Yarn-mapped Minecraft API + +For reference, the mapping namespaces are as follows: + +Namespace|Description|Examples +---|---|--- +`official`|The names found in the unmodified Minecraft JARs, which often change between Minecraft versions.|`dlx`, `ws`, `gS` +`intermediary`|The names assigned by the [Intermediary](https://github.com/FabricMC/intermediary) project, which aim to remain consistent ("[match](https://github.com/FabricMC/Matcher)") across Minecraft versions.|`net/minecraft/class_1802`, `field_8567`, `method_7157` +`named`|The human-readable names provided by Yarn.|`net/minecraft/item/Items`, `POTATO`, `isSmall` ### `mapNamedJar` -Builds a deobfuscated jar with yarn mappings and automapped fields (enums, etc.). Unmapped names will be filled with [intermediary](https://github.com/FabricMC/Intermediary) names. -### `decompileCFR` -Decompile the mapped source code. **Note:** This is not designed to be recompiled. +Produces a deobfuscated Minecraft JAR at `build/{minecraft-version}-named.jar`. Intermediary names are used as fallbacks for Yarn names. + +### `decompileVineflower` and `decompileCFR` + +Produces decompiled, deobfuscated Minecraft source code in the `build/namedSrc` directory using the [Vineflower](https://github.com/Vineflower/vineflower) and [CFR](https://github.com/FabricMC/cfr) decompilers, respectively. -### `download` -Downloads the client and server Minecraft jars for the current Minecraft version to `.gradle/minecraft` +**Note:** The decompiled code is meant for reference and is not designed to be recompiled. + +### `downloadMinecraftClientJar` and `downloadMinecraftServerJar` + +Downloads the Minecraft client and dedicated server JARs for the current Minecraft version to the `.gradle/filament/{minecraft-version}` directory. ### `mergeJars` -Merges the client and server jars into one merged jar, located at `VERSION-merged.jar` in the mappings directory where `VERSION` is the current Minecraft version. + +Merges the Minecraft client and dedicated server JARs for the current Minecraft version into a single JAR at `.gradle/filament/{minecraft-version}/merged.jar`. ### `formatMappings` -Formats and sorts the mappings, ensuring that they are in a consistent order. \ No newline at end of file + +Processes the mappings in the `mappings` directory, ensuring that they are consistently formatted and ordered. When editing mappings with Enigma, the mappings will be formatted in the same way automatically.