Environment

The mapping environment is a Git repository with the Gradle build system. The Compass plugin is installed through the buildscript.

The environment in the working directory is designed to hold the mapping data for a specific Minecraft version, as configured through the compass extension in the buildscript. It is intended that versions are managed by using different branches in the Git repository.

There are three main directories:

• The production data storage directory (data/), containing the mapping data in obfuscated names.
• The inputs directory (input/), containing the input files used in the generation of the staging mapping data. Ignored by Git.
• The staging data directory (staging/), containing the mapping data as modified by the input files. Ignored by Git.

Production vs. Staging

The mapping environment has a distinction between the production mapping data and the staging data.

The production data is the mapping data tracked by Git, and is the definitive version of the data. This is not modified directly by neither the user nor Compass, but the staging data is promoted to this after verifications are done (by the user and by the program).

The staging data is a copy of the production mapping data, which may be modified by the input files. This allows a flexible system of using the input files to gradually introduces changes in batches, and to avoid modifying the production data until the user is satisfied with their changes. This is ignored by Git.

Exports can be produced from either data stage. An export produced from the staging data will be marked and timestamped, to clearly differentiate this from actual production exports.

As a side-note, because Git is configured to ignore the staging data, this can be used to compare data across different commits, by first generating staging data without any inputs, then checking out to the desired commit. Through this, the prodution mapping data matches the commit, while the staging data from the previous state is retained.

Intermediate Formats

The mapping environment is extensible in the way of different intermediate formats. An intermediate format is a format used by a mod development framework to allow marking classes, functions, and fields with unique names that can be persisted across versions. There are two main intermediate formats in the modding community: SRG from the Minecraft Forge project, and Intermediary from the FabricMC project. Note that other mod development frameworks do exist, but do not rely on any intermediate format (such as the SpongePowered project).

In the context of the mapping environment, intermediate formats are used as a means of having inputs and exports in the preferred native intermediate formats of the supporting projects behind ParchmentMC. This allows a layer of abstraction between the actual intermediate format used in the stored mapping data, and the input and exports handled by Compass.

An intermediate format in Compass has a corresponding intermediate format provider, with a unique name associated. As of writing, there are three intermediate format providers available:

• obf - Obfuscated names, based on the Mojang obfuscation maps. Always available.
• official - Official (colloquially called Mojmap) names, based on the Mojang obfuscation maps. Always available.
• srg - SRG names, from the MCPConfig data provided by the Minecraft Forge project.

Input Files

Input files are files under the subdirectories of the inputs directory which are used in modifying the production data to produce staging data. These files are formatted using the Simple Input File Format (though there are future plans to introduce a JSON-based input format for use by automation).

Each subdirectory under the inputs directory must be named with one of the intermediate providers as listed above. This denotes what names to use when parsing the input files within that subdirectory (for example, files under the official subdirectory will be interpreted using official/mojmap names).