Mapping generator and mapping files for the Via projects.
Go to file
automation 4da8229258 Update: 1.21 2024-06-13 15:25:57 +00:00
.github/workflows Update jdk used in actions 2024-04-03 16:07:36 +02:00
gradle/wrapper Update mappings 2024-03-27 18:56:03 +01:00
mappings Support enchantment tags 2024-06-12 23:23:43 +02:00
src Support enchantment tags 2024-06-12 23:23:43 +02:00
.gitignore Add items to identifiers and compact identifier files 2024-04-21 20:19:47 +02:00
LICENSE Init 2023-03-04 19:54:11 +01:00 Add items to identifiers and compact identifier files 2024-04-21 20:19:47 +02:00
build.gradle.kts Update vianbt 2024-05-13 10:49:35 +02:00 Don't write to last_release file 2023-08-11 14:56:41 +10:00
gradlew Update Gradle wrapper 2023-11-03 01:34:30 +10:00
gradlew.bat Update mappings 2024-03-27 18:56:03 +01:00
last_release.txt update versions 2024-04-23 17:23:16 +02:00
last_snapshot.txt Update: 1.21 2024-06-13 15:25:57 +00:00
next_release.txt update versions 2024-04-23 17:23:16 +02:00
output_hashes.json Support enchantment tags 2024-06-12 23:23:43 +02:00
requirements.txt Add workflow to autogen mappings 2023-03-05 09:33:54 +01:00
settings.gradle.kts Move to Gradle 2023-10-03 11:46:28 +10:00


Generates and compiles mapping files for Via*. Current mapping files can be found in the mappings/ directory.

Generating json mapping files for a Minecraft version

Compile the project using ./gradlew build and put the jar in some directory, ideally the project root.

Then run the jar with:

java -jar MappingsGenerator.jar <path to server jar> <version>

The mapping file will then be generated in the mappings/ directory.

Compiling json mapping files into compact nbt files

If you want to generate the compact mapping files with already present json files, you can also trigger the optimizer on its own by starting the MappingsOptimizer class with the two arguments flipped:

java -cp MappingsGenerator.jar com.viaversion.mappingsgenerator.MappingsOptimizer <from version> <to version>

Optional arguments

Optional arguments must follow the two version arguments.

  • --generateDiffStubs to generate diff files with empty stubs for missing mappings
  • --keepUnknownFields to keep non-standard fields from json mappings in the compact files

Updating version files

On Minecraft updates, the next_release.txt and last_release.txt files need to be updated manually. last_release.txt needs the last release ViaVersion requires mappings for.

Json format

The json files contain a number of Minecraft registries in form of json arrays, where the index corresponds to the id of the entry.

Diff files for either ViaVersion or ViaBackwards then contain additional entries for changed identifiers, either in form of string→string or int→string mappings. These files need to be manually filled. If any such entries are required, the optimizer will give a warning with the missing keys.

Json mapping files are found in the mapping/ directory and are named mapping-<version>.json. Files containing diff-mappings for added or removed identifiers between versions must be named mapping-<from>to<to>.json and put into the mapping/diff/ directory.

Compact format

Compact files are always saved as NBT. ViaVersion uses its own ViaNBT as the NBT reader/writer. Compact files are found in the output/ directory and subdirectories.

Identifier files

Next to a standardized compact format for int id mappings, the full identifiers of some registries are also required. For this, we generate a list of all identifiers in the registry across all versions, so that their names only need to be stored once, as opposed to storing them again in every new version they are still in. Wherever needed, these identifiers are then referred to via their index in the global list.

Mapping files

Each mapping file contains a v int tag with the format version, currently being 1.

In each mapping file, a number of extra objects may be contained, such as string→string mappings for sounds. Most other parts (including blockstates, blocks, items, blockentities, enchantments, paintings, entities, particles, argumenttypes, and statistics) are stored as compound tags, containing:

  • id (byte tag) determining the storage type as defined below
  • size (int tag) the number of unmapped entries in the registry
  • mappedSize (int tag) the number of mapped entries in the registry

The rest of the content depends on the storage type, each resulting in vastly different storage sizes depending on the number and distribution of id changes, used to make the mapping files about as small as possible without sacrifing deserialization performance or making the formats too complex.

Direct value storage

The direct storage simply stores an array of ints exactly as they can be used in the protocol.

  • id (byte tag) is 0
  • val (int array tag) contains the mapped ids, where their array index corresponds to the unmapped id

Shifted value storage

The shifted value storage stores two int arrays: One containing the unmapped ids that end a sequence of mapped ids. For an index i, all unmapped ids between at[i] + sequence (inclusive) and at[i + 1] (exclusive) are mapped to to[i] + sequence.

  • id (byte tag) is 1
  • at (int array tag) contains the unmapped ids, where their mapped is is not simply the last mapped id + 1
  • to (int array tag) contains the mapped ids, indexed by the same index as the unmapped id in at

Changed value storage

The changed value storage stores two int arrays: One containing the changed unmapped ids, and one their corresponding mapped ids in a simple int→int mapping over the two arrays.

  • id (byte tag) is 2
  • at (int array tag) contains the unmapped ids that have been changed
  • val (int array tag) contains the mapped ids, indexed by the same index as the unmapped id in at
  • Optional: nofill (byte tag): Unless present, all ids between the ones found in at are mapped to their identity

Identity storage

The identity storage signifies that every id between 0 and size is mapped to itself. This is sometimes used over simply leaving out the entry to make sure ids stay in bounds.

  • id (byte tag) is 3


The Java and Python code is licensed under the GNU GPL v3 license. The files under mappings/ are free to copy, use, and expand upon in whatever way you like.