kff-1.20.5-migration-guide.md

Hey all. I finally got Kotlin for Forge working on NeoForge 1.20.5!
There were a lot of breaking changes in NeoForge that inevitably affected the way developers use Kotlin for Forge, so I wanted to write a quick guide listing some of the common problems you'll run into when you update.

Some Good News

Thanks to a change in NeoForge's FancyModLoader, it is now possible to JarJar Kotlin libraries without them crashing with Kotlin for Forge! Hopefully Forge will do the same...

Note for IntelliJ users

As Minecraft has updated to Java 21, you will now need to use a Java 21 JDK in your project.

If you are using JBR or DCEVM, keep reading! If not, you should TRY IT, because it allows hotswapping your code even with added/removed methods during a Debug session, avoiding that nasty Hot Swap failed: Schema change not implemented error.
You might be disappointed that IntelliJ does not offer a JBR that supports Java 21. Fret not, you can download one from the official JetBrains Runtime GitHub repository!

If you don't know which one to download, pick JBR (vanilla). You don't want fastdebug or JBRSDK.

Changes to your buildscript

Before you update your buildscript, make sure you are using at least Gradle 8.6. If you are on an older version, update by changing the Gradle distribution URL in ./gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

You'll want to ensure you are targeting Java 21 when compiling your Kotlin code. If you are unable to call any functions from KFF, this snippet should fix it:

// For Groovy buildscript
compileKotlin {
    kotlinOptions.jvmTarget = "21"
}

// For Kotlin buildscript
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    kotlinOptions.jvmTarget = "21"
}

Make sure your Gradle is using the Java 21 toolchain. This goes for all projects, not just those written in Kotlin, so make sure you set the correct version in your buildscript:

// For Groovy buildscript
java.toolchain.languageVersion = JavaLanguageVersion.of(21)

// For Kotlin buildscript
java.toolchain.languageVersion.set(JavaLanguageVersion.of(21))

Changes to your Mod's structure

In the transition to 1.20.5, NeoForge has changed a few things related to mod initialization. Firstly, mods.toml has been renmaed to neoforge.mods.toml. If you are using Gradle's processResources task to fill in the fields, make sure that you update its reference in your buildscript:

// For Groovy buildscript
tasks.withType(ProcessResources).configureEach {
    var replaceProperties = ...
    inputs.properties replaceProperties

    // Make sure you have the correct "neoforge.mods.toml" listed here!
    filesMatching(['META-INF/neoforge.mods.toml', 'pack.mcmeta']) {
        expand replaceProperties + [project: project]
    }
}

// For Kotlin buildscript
val replacements: MutableMap<String, Any> = ...
// Make sure you have the correct "neoforge.mods.toml" listed in here!
val targets = mutableListOf("META-INF/mods.toml", "META-INF/neoforge.mods.toml")
tasks.withType<ProcessResources> {
    inputs.properties(replacements)
    filesMatching(targets) {
        expand(replacements)
    }
}

Secondly, Mod.EventBusSubscriber and its inner classes are now just EventBusSubscriber.