Parchment Mappings

The data migration system allows you to migrate Parchment mapping data between different Minecraft versions. It uses the ParchmentJAM integration (which utilizes the JAMMER/JarAwareMapping tool) to match changed methods between versions and retain data integrity.

Migration is performed using the migrateData task within the parchment task group.

Workflow:

1. Configure the target version (see Configuration).
2. Run the migrateData task.
3. Use the promoteStagingToProduction task to move the migrated data from the staging directory to the production directory (data/).
4. Run sanitizeData and validateData to remove unwanted data fragments and ensure integrity.

# Example command line execution
./gradlew -Pmigration-targetVersion="1.19.4" migrateData

Parchment is a modloader-neutral set of mappings for parameter names and Javadocs designed to augment the official Mojang names.

To use Parchment in your development workspace, follow the official guide at https://parchmentmc.org/docs/getting-started.

To contribute to Parchment mappings (such as writing Javadocs, naming parameters, or correcting typos), follow these steps:

1. Fork the repository on GitHub to create your own copy.
2. Clone your fork to your local machine.
3. Launch the mapping interface by running the enigma Gradle task.
4. Perform mapping tasks within the Enigma interface (see 'Using the Enigma interface' for details).
5. Validate your changes using the validateData Gradle task.
6. Submit a Pull Request for review.

# Example of running the Enigma interface via Gradle
./gradlew enigma

Enigma is the mapping interface used to edit Parchment data. Once launched via ./gradlew enigma, use the following interactions:

• Navigate Classes: Classes are listed in the top-left section. Double-click a class to open it.
• Rename Parameters:
  • Move the cursor to the parameter name, type the new name, and press <kbd>Enter</kbd>.
  • OR right-click the parameter name and select Rename from the context menu.
• Add Javadocs: Right-click a class, field, method, or parameter and select Edit Javadocs from the context menu.
• Save Changes: Press <kbd>Ctrl</kbd> + <kbd>S</kbd> or use File > Save.

To prevent data loss during migration, certain versions (like April Fools versions) should be skipped. The migration system steps through all intermediate versions between the current and target versions unless they are explicitly excluded.

How to exclude versions

You can exclude versions using either the excludedVersions set property in the migrationExtension or the migration-excludedVersions project property (as a comma-separated list).

Warning: Setting your own excluded versions will fully override the default list. If you want to keep the default April Fools exclusions, you must re-specify them in your configuration.

Default Excluded Versions

By default, the following April Fools versions are excluded:

• 15w14a
• 1.RV-Pre1
• 3D Shareware v1.34
• 20w14infinite
• 22w13oneblockatatime
• 23w13a_or_b

The FunctionCommand class contains several inner classes used for managing command execution and results:

• Callbacks: Used to signal results during function execution via signalResult(Object, Identifier, int).
• 1Accumulator: An internal class used to accumulate results via add(int).
• FunctionCustomExecutor: Provides access to arguments from a CommandContext via arguments(CommandContext).

Before submitting a Pull Request, you should ensure your data adheres to the required standards using the following Gradle tasks:

• validateData: Checks for errors in the mapped data, such as mapped or documented synthetic methods. This task is also run by the CI on every Pull Request.
• sanitizeData: If validateData reports errors, run this task to automatically sanitize the data and remove potential causes of errors (e.g., removing synthetic methods).

# Validate your mapping data
./gradlew validateData

# Automatically fix validation errors
./gradlew sanitizeData

Once an argument is parsed, you can retrieve the result using getResourceOrTag. This method returns a Result object which encapsulates whether the input was a resource or a tag.

• parse(StringReader reader): Parses the input string into a Result.
• getResourceOrTag(CommandContext context, String argument, ResourceKey registryKey): Retrieves the result from the command context.
• Result.cast(ResourceKey registryKey): Attempts to cast the result to a specific resource type, returning an Optional.

// Parsing a reader
ResourceOrTagArgument.Result result = argument.parse(stringReader);

// Casting a result to a specific registry key
Optional<ResourceKey> resource = result.cast(registryKey);

The register method is used to attach the SetBlockCommand to the server's command dispatcher during the command registration lifecycle.

METHOD register (Lcom/mojang/brigadier/CommandDispatcher;Lnet/minecraft/commands/CommandBuildContext;)V
	ARG 0 dispatcher
	ARG 1 buildContext

The net/minecraft/commands/arguments/item/ItemArgument class is used to handle item-based arguments within Minecraft commands. It provides methods to initialize the argument with a CommandBuildContext, parse input from a StringReader into an ItemInput, and retrieve specific items from a command context using a name. It also supports generating suggestions for command completion via listSuggestions.

// Example conceptual usage based on mapping signatures
// Initialize the argument
ItemArgument itemArg = ItemArgument.item(context);

// Parse a string reader into an ItemInput
ItemInput input = itemArg.parse(stringReader);

// Retrieve an item from a command context
ItemInput result = itemArg.getItem(commandContext, "item_name");