Kotlin for Forge Mod Wiki

Kotlin for Forge (KFF) serves as a bridge between the Kotlin programming language and the Minecraft Forge modding platform. While standard Forge is built for Java, KFF allows developers to leverage Kotlin's modern features—such as concise syntax, null safety, coroutines, and serialization—without requiring end-users to manually install separate language libraries.

As a library mod, Kotlin for Forge does not add gameplay elements like mobs, blocks, or biomes. Instead, it provides the underlying infrastructure and technical utilities necessary for other mods written in Kotlin to function correctly within the game.

KFF bundles and shades several core Kotlin libraries to ensure compatibility across different mods and to prevent version conflicts. The following libraries are provided out-of-the-box:

Kotlin for Forge introduces several specialized components that modify how Forge interacts with mod code.

KotlinLanguageProvider

In standard Java modding, Forge looks for a class to instantiate. The KotlinLanguageProvider allows Forge to recognize and load Kotlin object declarations as the primary @Mod entry point. This enables the use of singletons, which are more idiomatic in Kotlin.

AutoKotlinEventBusSubscriber

Standard Forge uses @Mod.EventBusSubscriber to register static event handlers. KFF provides AutoKotlinEventBusSubscriber, which specifically targets Kotlin object declarations. This ensures that events are correctly routed to the singleton instance of the object rather than attempting to find static methods in a class.

Specialized Event Bus

KFF includes its own implementation of the Forge IEventBus. This implementation is enhanced to support:

• KCallables: Direct support for Kotlin function references.
• Reified Type Parameters: Allows for cleaner event listening syntax using Kotlin's reified keyword to avoid manual class passing.

When developing with Kotlin for Forge, the standard initialization flow is slightly altered to accommodate Kotlin's structure.

MOD_CONTEXT

Developers must use thedarkcolour.kotlinforforge.forge.MOD_CONTEXT instead of the standard net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext. This context provides the necessary hooks to the Mod Event Bus and the Forge Event Bus.

Example Usage:

val modBus = MOD_CONTEXT.getKEventBus
modBus.addListener(::onCommonSetup)

Property Delegates

KFF provides several utility property delegates to simplify modding tasks:

• Sided Property Delegates: Allows for values that differ between the Client and Server sides.
• Object Holder Delegates: Simplifies the injection of registered objects (like Items or Blocks) into variables using Kotlin's by syntax.

To use Kotlin for Forge in a development environment, specific configurations are required in the project's build files.

Gradle Configuration

The following plugins and repositories must be added to the build.gradle file to enable Kotlin support and fetch the KFF dependencies:

plugins {
 id 'org.jetbrains.kotlin.jvm' version '1.8.21'
 id 'org.jetbrains.kotlin.plugin.serialization' version '1.8.21' // Optional
}

repositories {
 maven {
 name = 'Kotlin for Forge'
 url = 'https://thedarkcolour.github.io/KotlinForForge/'
 }
}

dependencies {
 implementation 'thedarkcolour:kotlinforforge:3.12.0'
}

mods.toml Configuration

To instruct Forge to use the Kotlin loader, the mods.toml file must be updated to specify kotlinforforge as the mod loader:

modLoader="kotlinforforge"
loaderVersion="[3,)"

KFF includes a variety of extension functions designed to make the Forge API feel more native to Kotlin. These include:

• Registry Extensions: Simplified methods for registering blocks, items, and entities using reified types.
• Event Extensions: Inline functions that allow for cleaner event registration without the boilerplate of anonymous classes.
• Configuration Wrappers: Helpers for interacting with Forge's configuration system using Kotlin's delegated properties.