Skip to content

Latest commit

 

History

History
88 lines (63 loc) · 4.4 KB

developer-usage.md

File metadata and controls

88 lines (63 loc) · 4.4 KB
Raw

Developer usage

An example mod showcasing the mod's various features is available in the example-* branches of the repo:

Below are instructions for migrating build scripts to use UniMixins.

RetroFuturaGradle

The easiest way to use UniMixins is to use GTNH's ExampleMod, which has UniMixins integration built-in.

ForgeGradle

Refer to the example mod's build script (Gradle 4 | Gradle 6).

You can also depend on modules individually:

dependencies {
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-mixin-1.7.10:$unimixinsVersion")
    
    // You don't need all the modules, only the ones your mod requires.
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-compat-1.7.10:$unimixinsVersion:dev")
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-spongemixins-1.7.10:$unimixinsVersion:dev")
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-mixinbooterlegacy-1.7.10:$unimixinsVersion:dev")
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-gasstation-1.7.10:$unimixinsVersion:dev")
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-mixinextras-1.7.10:$unimixinsVersion:dev")
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-gtnhmixins-1.7.10:$unimixinsVersion:dev")
    implementation("com.github.LegacyModdingMC.UniMixins:unimixins-mixingasm-1.7.10:$unimixinsVersion:dev")
}
Testing info

If you want to depend on a local build, you need to use io.github.legacymoddingmc.unimixins instead of com.github.LegacyModdingMC.UniMixins.

And here's how you depend on the Very Optional modules (not published on Jitpack).

    //implementation("io.github.legacymoddingmc.unimixins:unimixins-mixin-1.7.10-spongepowered:$unimixinsVersion")
    //implementation("io.github.legacymoddingmc.unimixins:unimixins-mixin-1.7.10-fabric:$unimixinsVersion")
    //implementation("io.github.legacymoddingmc.unimixins:unimixins-mixin-1.7.10-gasmix:$unimixinsVersion")
    //implementation("io.github.legacymoddingmc.unimixins:unimixins-mixin-1.7.10-gtnh:$unimixinsVersion")

Note: If you are not using UniMix or GTNH's Mixin fork, you will need to add the compat module and set the -Dunimixins.compat.hackClasspathModDiscovery=true JVM flag, or Forge may fail to discover your mod or its dependencies.

Tricks

Hot swapping

Mixin hot swapping can be enabled in a similar way to how it works on Fabric. You just have to add the UniMixins jar (or the matching UniMix jar) as a java agent.

Here's a buildscript snippet that will set it up for you (tested with the GTNH ExampleMod):

afterEvaluate {
    File uni = configurations.compileClasspath.findAll { it.name.contains("unimixins-all-") || it.name.contains("unimixins-mixin-") || it.name.contains("unimixins-0.") }.first()
    runClient {
        extraJvmArgs.add(
                '-javaagent:' + uni.getPath()
        )
    }
}

Pitfalls

Shaded ASM package name

Mods which depend on MixinBooterLegacy or GTNHMixins use the MixinBooterLegacy-style shaded ASM package name (org.spongepowered.libraries.org.objectweb.asm), whereas UniMix uses the legacy name (org.spongepowered.asm.lib). You will have to switch to the latter to make your mod compile.

-import org.spongepowered.libraries.org.objectweb.asm.tree.ClassNode;
+import org.spongepowered.asm.lib.tree.ClassNode;

--mods hack

Some build scripts use the --mods program argument to add a duplicate of the mod in order to work around Mixin preventing mixin mods on the class path from getting loaded as Forge mods. In UniMix and GTNH's Mixin fork, this issue was fixed, so this workaround should be removed since it only causes problems.

-       arguments += [
-               "--mods=../build/libs/$archivesBaseName-${version}.jar"
-       ]