A small JVM mappings library designed to load, modify, and use mappings, for runtime and pre-runtime remapping.
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Koen Oostveen ee939f41b2
All checks were successful
Deploy / Build (push) Successful in 37s
Automatically build docs with forgejo actions
2026-06-05 22:40:18 +02:00
.forgejo/workflows Automatically build docs with forgejo actions 2026-06-05 22:40:18 +02:00
.github/workflows Add packages repository and workflow 2023-10-23 12:31:09 +02:00
conventions Automatically build docs with forgejo actions 2026-06-05 22:40:18 +02:00
converter Vastly improve JarRemapper utility 2026-05-05 00:49:45 +02:00
docs Release v0.2 2026-05-04 01:48:35 +02:00
gradle Get rid of pesky relocator, update dependencies, modernize Dokka 2026-05-03 17:08:49 +02:00
lib Vastly improve JarRemapper utility 2026-05-05 00:49:45 +02:00
remapper Make remapper more posix 2026-05-03 22:16:57 +02:00
samples Improve accuracy of remapper, introduce mappings converter, seal MappingsFormat 2026-05-03 22:15:43 +02:00
sponge-mixin-remapper Release v0.2 2026-05-04 01:48:35 +02:00
tiny-remapper-provider Release v0.2 2026-05-04 01:48:35 +02:00
.gitattributes Initial commit 2023-10-14 23:11:19 +02:00
.gitignore Initial commit 2023-10-14 23:11:19 +02:00
.sops.yaml Add Maven Central publishing API support 2026-05-03 19:12:03 +02:00
asm.package-list Huge Docs update 2024-07-03 13:37:50 +02:00
build.gradle.kts Bump version 2026-05-05 00:50:20 +02:00
gradle.properties Add Maven Central publishing API support 2026-05-03 19:12:03 +02:00
gradlew Add AccessWideners, more flexible tiny mappings API, update versions 2024-07-02 22:49:49 +02:00
gradlew.bat Add AccessWideners, more flexible tiny mappings API, update versions 2024-07-02 22:49:49 +02:00
LICENSE.md Vastly improve JarRemapper utility 2026-05-05 00:49:45 +02:00
maven-central-password Add Maven Central publishing API support 2026-05-03 19:12:03 +02:00
maven-central-token Add Maven Central publishing API support 2026-05-03 19:12:03 +02:00
maven-central-username Add Maven Central publishing API support 2026-05-03 19:12:03 +02:00
README.md Move docs to Forgejo 2026-06-05 21:39:10 +02:00
settings.gradle.kts Improve accuracy of remapper, introduce mappings converter, seal MappingsFormat 2026-05-03 22:15:43 +02:00

mappings-util

A small JVM mappings library designed to load, modify, and use mappings, for runtime and pre-runtime remapping. Several mappings formats are supported, namely:

  • Tiny (v1 and v2),
  • SRG and XSRG,
  • CSRG,
  • TSRG (v1 and v2),
  • Proguard,
  • Recaf,
  • Enigma,
  • and a custom "compacted" binary format

Important: this is a Kotlin-first library. This means that this library was written in Kotlin and with Kotlin in mind. You can use this library in Java as well, albeit probably with a slightly worse experience (extension functions do not exist in Java, for example). Using Kotlin is highly recommended.

Important: this library introduced binary incompatibility in version 0.2

Usage

mappings-util is on Maven Central, and can be linked in your project depending on the build system.

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
}

dependencies {
    implementation("nl.koenoostveen:mappings-util:0.2")
}

Maven

<dependencies>
    <dependency>
        <groupId>nl.koenoostveen</groupId>
        <artifactId>mappings-util</artifactId>
        <version>0.2</version>
    </dependency>
</dependencies>

Docs

Available on Forgejo Pages.

Examples

  • Some basic examples on how to transform and handle mappings can be found here
  • Parsing mappings from disk can be done in two ways:
    • Fully buffered:
    MappingsLoader.loadMappings(File("/path/to/some/mappings/file").readLines())
    
    • Partially buffered:
    File("/path/to/some/mappings/file").inputStream().use { inp -> MappingsLoader.loadMappings(inp) }
    
    The latter is slightly faster and more memory efficient.
  • Mappings may be used for remapping through:
val remapper = MappingsRemapper(
    mappings,
    from = "fromNamespace",
    to = "toNamespace",
    loader = ClasspathLoaders.fromSystemLoader()
)

val reader = ClassReader(bytes)
val writer = ClassWriter(null)
reader.accept(LambdaAwareRemapper(writer, remapper), 0)

// Or remapping a ClassNode
val node = ClassNode()
reader.accept(node)
node.remap(remapper)

// Or for remapping a full jar
remapJar(mappings, inputFile, outputFile, "fromNamespace", "toNamespace")

// Or with the experimental DSL
performRemap {
    copyResources = true
    mappings = File("/path/to/some/mappings/file").inputStream().use { inp ->
        MappingsLoader.loadMappings(inp)
    }
    
    loader = ClasspathLoaders.fromJars(listOf(
        "classpath-a.jar",
        "classpath-b.jar"
    ))

    task(
        input = Path("input.jar"),
        output = Path("output.jar"),
        fromNamespace = "fromNamespace",
        toNamespace = "toNamespace",
    )
}
  • Writing mappings to disk is easy:
File("/path/to/some/mappings/file").bufferedWriter().use { mappings.writeLazy().writeTo(it) }

Tools

Remapper

remapper can take JAR files and a mappings file, and produce a remapped JAR file. Example:

remapper --force -- client.jar client-mapped.jar client.txt official named

takes Proguard mappings from client.txt, and turns client.jar into client-mapped.jar, taking names in "official" to "named".

Converter

Converts mappings files between formats. Usage:

converter <mappings> <format> [output]
where <format> is one of:
  - "tinyv1"
  - "tiny"
  - "srg"
  - "xsrg"
  - "proguard"
  - "tsrg"
  - "tsrg2"
  - "csrg"
  - "enigma"
  - "recaf"

If [output] is missing or -, defaults to stdout

License

Use of this source code is governed by the MIT license, a copy of which can be found here.

Contributing

PRs are welcome!