Skip to content

Commit

Permalink
Help I can't stop rewriting sentences
Browse files Browse the repository at this point in the history
  • Loading branch information
IotaBread committed Feb 24, 2024
1 parent d0f64e7 commit f22cc9b
Showing 1 changed file with 30 additions and 26 deletions.
56 changes: 30 additions & 26 deletions wiki/misc/mappings/en.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,30 +15,30 @@ the dictionary would help us translate that to plain english.

While a simple obuscated-to-human-readable mapping set would be enough for one minecraft version, the obfuscated names
aren't constant between different minecraft versions: `DirtBlock` could be obfuscated as `abc` in 1.19 but in 1.20 it
could be `def`. From this arises the need to keep the obfuscation changes between versions minimal, and the problem can
could be `def`. From this arises the need to keep the obfuscation changes between versions minimal, a problem that can
be solved with intermediate mappings, that convert those obfuscated names to names that won't change between versions,
but still aren't readable in english. Quilt uses Hashed Mojmap, in which every class, field, and method is prefixed by
`C_`, `f_` and `m_` respectively, followed by an 8-letter hash. While developing mods, most of the time you'll see
Fabric's intermediary instead, which uses `class_`, `field_` and `method_`, followed by a number. Mojang also publishes
official mappings, often called Mojmap (short for Moj(ang)-map(pings)), for every version after 1.14. Since they don't
have an intermediate mapping set, you have to do some extra processing to use them where you'd use other mappings.
Luckily, Loom does this process for you, so you don't have to worry about that and can easily replace the mappings used
in your mod for Mojang's official ones.

There are a few different formats to store mappings, and as of the time this article was written, we are developing a
`C_`, `f_`, and `m_` respectively, followed by an 8-letter hash.
While developing mods, most of the time you'll see Fabric's intermediary instead, which uses `class_`, `field_`, and
`method_`, followed by a number. Mojang also publishes official mappings, often called Mojmap (short for
Moj(ang)-map(pings)), for every version after 1.14. Since they don't have an intermediate mapping set, you have to do
some extra processing to use them where you'd use other mappings. Luckily, Loom does this process for you, so you don't
have to worry about that and can easily replace the mappings used in your mod for Mojang's official ones.

There are a few different formats to store mappings, and, as of the time this article was written, we are developing a
new one with a bunch of improvements. In our ecosystem, the most used format is [Tiny V2], which uses a single `.tiny`
file to store mappings, and places fields and methods as "children" of their parent class.
file to store mappings, and places fields & methods as "children" of their parent class.
Another format we often use is the Enigma format, which uses a directory tree with a file for each top-level class, and
organizes the entries in a tree-like structure, placing each field, method and class as a child of another class or a
organizes the entries in a tree-like structure, placing each field, method, and class as a child of another class or a
top level one.

## Editing your mappings

Mapping sets don't have to contain a mapping for every class, field or method in a jar to be valid, and in fact most
mapping sets aren't complete. For instance, Quilt Mappings (QM for short) has reached 99% completion at most. In a
development environment, unmapped things will use their intermediary name instead of the obfuscated one, so if you have
ever browsed Minecraft's code with QM or Fabric's Yarn applied, it's very likely you have seen quite a few intermediary
names. It gets worse with method parameters: since they are really prone to incompatible changes between versions, they
Mapping sets don't have to contain a mapping for every class, field or method in a jar to be valid; in fact most mapping
sets aren't complete. For instance, Quilt Mappings (QM for short) has reached 99% completion at most. In a development
environment, unmapped things will use their intermediary name instead of the obfuscated one, so if you have ever browsed
Minecraft's code with QM or Fabric's Yarn applied, it's very likely you have seen quite a few intermediary names.
It gets when it comes to method parameters: since they are really prone to incompatible changes between versions, they
(usually) don't have intermediate names, thus the names you see in the code depend on the tooling that you used to
decompile the game.

Expand All @@ -49,25 +49,29 @@ are going to work on QM, we highly suggest taking a look at its [contributing do
contributing your changes to the repository. You'll need some very basic Git knowledge, but it should be fairly easy
to do if you've ever worked with Git before.

To get started, clone or download [Quilt Mappings] (if you want to contribute, [fork the repo][fork qm] and clone said
fork), and run `./gradlew mappings` in your command prompt or terminal. This will launch [Enigma], our tool to edit and
write mappings. Rai wrote a really [great guide on how to edit mappings in Enigma][Enigma guide], so you can take a look
and start mapping! Once you have finished editing, don't forget to save your changes before closing Enigma.
To get started, first get your own copy of [Quilt Mappings]' code by cloning or downloading the repo. If you want to
contribute your changes at some point, directly downloading the code won't work; you'll have to [fork the repo][fork qm]
and clone said fork instead.
Once you have the code, run `./gradlew mappings` in your command prompt or terminal to launch [Enigma], our favorite
tool to edit and write mappings. Rai wrote a really [great guide on how to edit mappings in Enigma][Enigma guide],
so you can take a look and start mapping! Once you have finished editing, don't forget to save your changes before
closing Enigma.

### Contributing the changes back to Quilt

To contribute your changes, you have to add and commit your changes, and then push the changes to your fork of QM. This
is really easy to do with an IDE, as described in [the Setting Up article][setting-up], but you can also do it from the
command prompt or terminal with these commands.
To contribute your changes, you have to add and commit your changes, then push the changes to your fork of QM. This is
really easy to do with an IDE, as described in [the Setting Up article][setting-up], but if you want you can also do it
from the command prompt or terminal with these commands.

```bash
git add . # tell git to track all your changes in the current directory

git commit -m "Blabla" # add those changes into a new commit (replace "blabla" with a short description of your changes)

git push # upload your changes to your fork of QM. You might need to add `origin <minecraft version>` at the end if git complains about a missing upstream branch
git push # upload your commits to your fork of QM. You might need to add `origin <minecraft version>` at the end if git complains about a missing upstream branch
```

Once you pushed your changes to your fork, go to [QM's Pull Requests tab][QM PRs], and click the "Compare & Pull
Once you pushed your changes to your fork, go to [QM's Pull Requests tab][QM PRs] and click the "Compare & Pull
Request" button in the note about your recent changes. Fill in the title and description of your PR, submit it, and wait
for your changes to be reviewed and accepted. Again, there's a more in-depth explanation of the PR process in
[the contributing documentation][QM CONTRIBUTING.md].
Expand All @@ -86,7 +90,7 @@ repositories {
}
```

Once you have `mavenLocal()` in your repositories, you can edit the `libs.versions.toml` file in the `gradle/`
Once you have `mavenLocal()` in your repositories, you can edit the `libs.versions.toml` file, in the `gradle/`
directory, to change the version of the mappings you are using to the one you just edited. In the case of QM, you can
change the `+build.*` suffix to `+local`; other projects may use a different versioning format, so you have to check
their documentation or code to verify the version you want.
Expand Down

0 comments on commit f22cc9b

Please sign in to comment.