DOCSEARCHbyAlgolia
Submit Docs

Yarn Minecraft Mappings

repository·1.21.11·Indexed 22 days ago

https://github.com/fabricmc/yarn

A set of open, CC0-licensed Minecraft mappings providing human-readable names for obfuscated code to facilitate modding and development. Includes comprehensive naming conventions for classes, methods, and variables, Javadoc standards, and Gradle tasks for generating deobfuscated Minecraft jars and editing mappings via Enigma.

Tokens
101.2K
Snippets
160
Records
363
Agent score
78%

What's inside Yarn

  1. Follow Mojang name mapping conventions

    1.21.11

    When naming members, follow these rules regarding Mojang's terminology:

    1. Avoid Mojang obfuscation names: Do not use names from Mojang's obfuscation maps. Use names that match strings in the vanilla code.
    2. Prefer official names: Even if a name doesn't appear in a string, use the official Mojang name if it accurately describes the purpose (e.g., use BedrockBlock even if it's used for something else, rather than inventing a name like NoSpawningBlock).

    Required Terminology Overrides: To maintain consistency with Yarn standards, use these specific terms instead of Mojang's:

    • Use world instead of Mojang's level.
    • Use screen handler or handler instead of Mojang's menu.
    • Use inventory instead of Mojang's container.

  2. Naming conventions for game content and members

    1.21.11

    Game Content Capitalization

    When describing in-game content, do not use capitalization.

    • Incorrect: The quick Snow Fox jumped over the tamed Wolf.
    • Correct: The quick snow fox jumped over the tamed wolf.

    Method and Class Naming

    • Avoid implementation details: Name methods based on what they do, not how they work.
    • Avoid Java-specific prefixes: Do not prefix class names with I or Enum, and do not prefix methods with private.

  3. How to edit mappings using Enigma

    1.21.11
    To edit mappings using the Enigma user interface, use the yarn Gradle task. This automatically configures Enigma with the merged jar and mappings, and includes a name guesser plugin that automatically maps enums and certain constant field names.

  4. Naming getters, setters, withers, and creators

    1.21.11

    Follow these patterns for property manipulation and object creation:

    • Getters: Use get for non-boolean properties or calculations with no side effects. Use is for boolean getters.
    • Setters: Use set. Name the parameter identically to the property (e.g., setColor(color)).
    • Withers: Use with for methods that return a copy of an object with a modified property (e.g., withColor(color)).
    • Creators: Use create for new instances. Use getOrCreate for methods that return an existing instance or create a new one if it doesn't exist (but do not use this for lazy initialization).

  5. Generate a deobfuscated Minecraft jar

    1.21.11

    To obtain a deobfuscated Minecraft jar that can be sent to a decompiler, run the mapNamedJar Gradle task. This generates a jar named <minecraft version>-named.jar containing yarn mappings and automapped fields (such as enums). Unmapped names will be filled with intermediary names.

    ./gradlew mapNamedJar

  6. Write Javadocs for Yarn members

    1.21.11

    When writing Javadocs for classes, methods, or fields, follow these formatting rules:

    • Sentences: Start with an uppercase letter and end with a period. Method documentation should start with verbs (e.g., Gets, Called).
    • Paragraphs: Use HTML <p> tags for multiple paragraphs. Line wraps are converted to spaces.
    • Parameters and Returns: Use quick descriptions without initial capitalization or punctuation.
      • Example: {@code true} if the block placement was successful, {@code false} otherwise.
    • Indexing: Use {@index} to allow enclosed text to be indexed by the Javadoc search.
    • Parameter Documentation: Avoid using the @param tag on methods. Instead, add documentation directly to the parameter itself. This allows the Matcher tool to update them correctly across Minecraft updates. You may still use @param for type parameters (e.g., <T>).
    • Brief Descriptions: Javadoc uses the first sentence (ending at the first .) as the brief description. Note that abbreviations like i.e. will trigger a sentence end.

  7. Naming factories, builders, and collections

    1.21.11

    Follow these patterns for structural objects:

    • Factories: Use factory for objects whose purpose is creating other objects.
    • Builders: Use builder for objects helping create immutable objects. Name builder methods after the field they set, without a prefix.
    • Collections: Use plural names (e.g., entities) instead of list, set, or array.
    • Maps: Name maps based on the value type, or use the valuesByKeys format (e.g., entitiesByBlockPos).

  8. Check Javadoc validity locally

    1.21.11

    To verify your Javadocs, you can run the following commands:

    Linux/macOS:

    ./gradlew javadoc

    Windows:

    gradlew javadoc

    After the task completes, you can inspect the generated documentation in the build/docs/javadoc directory to ensure it renders correctly. For a full check including mappings, use:

    ./gradlew build javadocJar checkMappings mapNamedJar --stacktrace

  9. Use approved abbreviations and acronyms

    1.21.11

    To maintain readability, avoid most abbreviations unless they are common or already established in Yarn.

    Commonly accepted abbreviations:

    • id (identifier)
    • pos (position)
    • nbt (named binary tag)
    • init (initialize)
    • min/max (minimum/maximum)
    • o (the parameter for equals(Object o))
    • Standard library acronyms like json or html.

    Acronyms: Treat acronyms as single words (e.g., JsonObject instead of JSONObject) to match Mojang's style (e.g., NbtIo).

  10. Naming serialization and conversion methods

    1.21.11

    Use the following terminology for data handling:

    • Serializers: Use serializer for objects that handle serialization/deserialization (e.g., RecipeSerializer).
    • Methods: Use serialize and deserialize only when the method is serializing/deserializing an object other than itself.
    • Static Creation: Use from for static methods creating the owner type (e.g., fromJson, fromNbt).
    • Conversion: Use to for converting to another type (e.g., toString, toNbt).
    • Loading/Saving: Use read for non-static methods loading data into the object, and write for saving data to an existing object passed as a parameter.

  11. Follow Yarn naming conventions

    1.21.11

    When contributing to or using Yarn-style naming, follow these casing and phrasing rules:

    • Classes: UpperCamelCase (e.g., ChunkRegion). Use noun phrases.
    • Methods and Variables: lowerCamelCase (e.g., getCarversForStep). Use verb phrases.
    • Static Final Fields: UPPER_SNAKE_CASE (e.g., MAX_VALUE).
    • Booleans: Use adjective or present tense verb phrases (e.g., powered, canOpen). Avoid is or has prefixes where possible (use colored instead of isColored).
    • Natural Language Order: Name things in natural order (e.g., ChestBlockEntity instead of BlockEntityChest).

  12. Link to other members in Javadocs

    1.21.11

    Use @link, @linkplain, and @see to reference other code elements.

    When to use simple names vs. full binary names:

    • Simple names are acceptable if the class is:
      • In the java.lang package.
      • In the same package as the documented class.
      • Used as part of the API signature (class, method, or field signature).
    • Full binary names (e.g., com.google.common.collect.Lists) must be used if the class does not meet the above criteria. Use dots . to separate packages, not slashes /.

    Referencing Minecraft members: Always use Yarn mappings (e.g., net.minecraft.server.world.ThreadedAnvilChunkStorage) instead of Enigma/Mojang names (e.g., net.minecraft.class_3898).

    /**
 * 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);
	}
}