{"id":18574130,"url":"https://github.com/viaversion/mappings","last_synced_at":"2025-04-10T07:32:49.745Z","repository":{"id":108065061,"uuid":"609589694","full_name":"ViaVersion/Mappings","owner":"ViaVersion","description":"Mapping generator and mapping files for the Via projects.","archived":false,"fork":false,"pushed_at":"2024-10-29T12:26:02.000Z","size":14383,"stargazers_count":5,"open_issues_count":1,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-29T14:52:43.341Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ViaVersion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-04T16:30:13.000Z","updated_at":"2024-10-29T12:26:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"d8657a13-4b6d-43fa-967f-7a2258fbd513","html_url":"https://github.com/ViaVersion/Mappings","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViaVersion%2FMappings","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViaVersion%2FMappings/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViaVersion%2FMappings/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ViaVersion%2FMappings/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ViaVersion","download_url":"https://codeload.github.com/ViaVersion/Mappings/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223430212,"owners_count":17143625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T23:14:00.506Z","updated_at":"2024-11-06T23:14:01.117Z","avatar_url":"https://github.com/ViaVersion.png","language":"Java","readme":"# Mappings\n\nGenerates and compiles mapping files for Via*. Current mapping files can be found in the `mappings/` directory.\n\n## Generating json mapping files for a Minecraft version\n\nCompile the project using `./gradlew build` and put the jar in some directory, ideally the project root.\n\nThen run the jar with:\n\n```\njava -jar MappingsGenerator.jar \u003cpath to server jar\u003e \u003cversion\u003e\n```\n\nThe mapping file will then be generated in the `mappings/` directory.\n\n## Compiling json mapping files into compact nbt files\n\nIf you want to generate the compact mapping files with already present json files, you can also trigger the optimizer on\nits own by starting the `MappingsOptimizer` class with the two arguments flipped:\n\n```\njava -cp MappingsGenerator.jar com.viaversion.mappingsgenerator.MappingsOptimizer \u003cfrom version\u003e \u003cto version\u003e\n```\n\n### Optional arguments\n\nOptional arguments must follow the two version arguments.\n\n* `--generateDiffStubs` to generate diff files with empty stubs for missing mappings\n* `--keepUnknownFields` to keep non-standard fields from json mappings in the compact files\n\n## Updating version files\nOn Minecraft updates, the `next_release.txt` and `last_release.txt` files need to be updated manually.\n`last_release.txt` needs the last release **ViaVersion requires mappings for**.\n\n## Json format\n\nThe json files contain a number of Minecraft registries in form of json arrays, where the index corresponds to the id of\nthe entry.\n\nDiff files for either ViaVersion or ViaBackwards then contain additional entries for changed identifiers, either in form\nof string→string or int→string mappings. These files need to be manually filled. If any such entries are required, the\noptimizer will give a warning with the missing keys.\n\nJson mapping files are found in the `mapping/` directory and are named `mapping-\u003cversion\u003e.json`. Files containing\ndiff-mappings for added or removed identifiers between versions must be named `mapping-\u003cfrom\u003eto\u003cto\u003e.json` and put into\nthe `mapping/diff/` directory.\n\n## Compact format\n\nCompact files are always saved as [NBT](https://minecraft.fandom.com/wiki/NBT_format). ViaVersion uses its\nown [ViaNBT](https://github.com/ViaVersion/ViaNBT) as the NBT reader/writer. Compact files are found in the\n`output/` directory and subdirectories.\n\n### Identifier files\n\nNext to a standardized compact format for int id mappings, the full identifiers of some registries are also required.\nFor this, we generate a list of *all* identifiers in the registry across all versions, so that their names only need to\nbe stored once, as opposed to storing them again in every new version they are still in. Wherever needed, these\nidentifiers are then referred to via their index in the global list.\n\n### Mapping files\n\nEach mapping file contains a `v` int tag with the format version, currently being `1`.\n\nIn each mapping file, a number of extra objects may be contained, such as string→string mappings for sounds. Most other\nparts (including blockstates, blocks, items, blockentities, enchantments, paintings, entities, particles, argumenttypes,\nand statistics) are stored as compound tags, containing:\n\n* `id` (byte tag) determining the storage type as defined below\n* `size` (int tag) the number of unmapped entries in the registry\n* `mappedSize` (int tag) the number of mapped entries in the registry\n\nThe rest of the content depends on the storage type, each resulting in vastly different storage sizes depending on the\nnumber and distribution of id changes, used to make the mapping files about as small as possible without sacrifing\ndeserialization performance or making the formats *too* complex.\n\n### Direct value storage\n\nThe direct storage simply stores an array of ints exactly as they can be used in the protocol.\n\n* `id` (byte tag) is `0`\n* `val` (int array tag) contains the mapped ids, where their array index corresponds to the unmapped id\n\n### Shifted value storage\n\nThe shifted value storage stores two int arrays: One containing the unmapped ids that end a sequence of mapped ids. For\nan index `i`, all unmapped ids between `at[i] + sequence` (inclusive) and `at[i + 1]` (exclusive) are mapped\nto `to[i] + sequence`.\n\n* `id` (byte tag) is `1`\n* `at` (int array tag) contains the unmapped ids, where their mapped is is *not* simply the last mapped id + 1\n* `to` (int array tag) contains the mapped ids, indexed by the same index as the unmapped id in `at`\n\n### Changed value storage\n\nThe changed value storage stores two int arrays: One containing the changed unmapped ids, and one their corresponding\nmapped ids in a simple int→int mapping over the two arrays.\n\n* `id` (byte tag) is `2`\n* `at` (int array tag) contains the unmapped ids that have been changed\n* `val` (int array tag) contains the mapped ids, indexed by the same index as the unmapped id in `at`\n* Optional: `nofill` (byte tag): Unless present, all ids between the ones found in `at` are mapped to their identity\n\n### Identity storage\n\nThe identity storage signifies that every id between `0` and `size` is mapped to itself. This is sometimes used over\nsimply leaving out the entry to make sure ids stay in bounds.\n\n* `id` (byte tag) is `3`\n\n## License\n\nThe Java and Python code is licensed under the GNU GPL v3 license. The files under `mappings/` are free to copy, use,\nand expand upon in whatever way you like.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviaversion%2Fmappings","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviaversion%2Fmappings","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviaversion%2Fmappings/lists"}