Welcome to the Essential Mod Partner Program documentation. If you would like to learn more or join this program, click here.
This repository contains the documentation and examples for the Partner Mod Integration. The source code of the integration can be found here.
Latest Partner Integration Mod Version:
Refer to the changelog for changes.
There are certain Minecraft versions where the changes do not affect the Partner Mod, so for these versions you are required to bundle the Partner Mod for a different Minecraft versions. These version mismatches are bolded in the fourth column of this table.
| Minecraft Version | Fabric | Forge | NeoForge | Partner Mod Minecraft Version |
|---|---|---|---|---|
| 1.8.9 | ❌ | ✅ | ❌ | 1.8.9 |
| 1.12.2 | ❌ | ✅ | ❌ | 1.12.2 |
| 1.16.5 | ✅ | ✅ | ❌ | 1.16.5 |
| 1.17.1 | ✅ | ✅ | ❌ | 1.17.1 |
| 1.18 | ✅ | ❌ | ❌ | 1.18.1 |
| 1.18.1 | ✅ | ❌ | ❌ | 1.18.1 |
| 1.18.2 | ✅ | ✅ | ❌ | 1.18.2 |
| 1.19 | ✅ | ❌ | ❌ | 1.19 |
| 1.19.1 | ✅ | ❌ | ❌ | 1.19.2 |
| 1.19.2 | ✅ | ✅ | ❌ | 1.19.2 |
| 1.19.3 | ✅ | ✅ | ❌ | 1.19.3 |
| 1.19.4 | ✅ | ✅ | ❌ | 1.19.4 |
| 1.20 | ✅ | ❌ | ❌ | 1.20 |
| 1.20.1 | ✅ | ✅ | ❌ | 1.20.1 |
| 1.20.2 | ✅ | ✅ | ❌ | 1.20.2 |
| 1.20.4 | ✅ | ✅ | ✅ | 1.20.4 |
| 1.20.6 | ✅ | ✅ | ✅ | 1.20.6 |
| 1.21 | ✅ | ❌ | ❌ | 1.21.1 |
| 1.21.1 | ✅ | ✅ | ✅ | 1.21.1 |
| 1.21.2 | ✅ | ❌ | ❌ | 1.21.3 |
| 1.21.3 | ✅ | ✅ | ✅ | 1.21.3 |
| 1.21.4 | ✅ | ✅ | ✅ | 1.21.4 |
| 1.21.5 | ✅ | ✅ | ✅ | 1.21.5 |
| 1.21.6 | ✅ | ❌ | ❌ | 1.21.6 |
Bundling the Partner Mod is different on Fabric and Forge/NeoForge. See the sections below for the details of how to bundle the Partner Mod on each modloader.
Examples are provided in the examples directory. There is also a "multiversion" example in examples/multiversion that supports all of the above versions (using the Essential Gradle Toolkit/ReplayMod preprocessor multiversion approach).
On Fabric, the Partner Mod is bundled using Fabric's jar-in-jar mechanism. Fabric Loader will automatically select the latest version available out of all the versions bundled by mods. This can be done as follows.
repositories {
// If you use a groovy buildscript instead of a Kotlin one, use {} instead of ().
// If you use the defaults plugin from Essential Gradle Toolkit, the repository is likely already added.
maven(url = "https://repo.essential.gg/public")
}
dependencies {
// Replace ${mcVersion} with the Minecraft version
// Replace ${partnerModVersion} with the Partner Mod version
// Refer to the Supported Versions table for both of these
include("gg.essential:partner-mod-integration-${mcVersion}-fabric:${partnerModVersion}")
}See examples/1.21.1-fabric for a full example.
On Forge and NeoForge, you must include a relocated version of the Partner Mod within your mod. At startup, these relocated versions will negotiate to ensure only the latest version of the Partner Mod is used.
This process is slightly different for legacy forge (1.8.9 & 1.12.2) and modern forge (1.16+).
1.8.9 and 1.12.2 Forge
An example using the Kotlin buildscript can be found in examples/1.12.2-forge and an example using the Groovy buildscript can be found in examples/1.8.9-forge.
The following highlights the important sections (using the Kotlin buildscript, if using the Groovy buildscript refer to the respective example).
plugins {
// Load the shadow plugin.
// We don't need to apply it since we don't want the default shadowJar task.
id("com.gradleup.shadow") version "8.3.5" apply false
}
repositories {
// If you use a groovy buildscript instead of a Kotlin one, use {} instead of ().
// If you use the defaults plugin from Essential Gradle Toolkit, the repository is likely already added.
maven(url = "https://repo.essential.gg/public")
}
// Replace this with a package within your mod package
val essentialPartnerModPackage = "com.example.mod.essentialpartnermod"
tasks.jar {
manifest.attributes(
// The main entry point of the Essential Partner mod is its core mod:
"FMLCorePlugin" to "$essentialPartnerModPackage.asm.EssentialPartnerCoreMod",
// If your mod already has its own core mod, you can have the Essential Partner core mod chain-load it:
"EssentialPartnerCoreModDelegate" to "com.example.mod.asm.ExampleModCoreMod",
// In any case, you'll likely also want to instruct Forge to load your regular mod, otherwise it'll only
// load the core mod:
"FMLCorePluginContainsFMLMod" to "Yes",
)
}
// Replace ${mcVersion} with the Minecraft version
// Replace ${partnerModVersion} with the Partner Mod version
// Refer to the Supported Versions table for both of these
val essentialPartnerModDep = "gg.essential:partner-mod-integration-${mvVersion}-forge:${partnerModVersion}"
// Relocate Essential Ad into your mod's package
val relocatedEssentialPartnerModJar by tasks.registering(com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar::class) {
destinationDirectory.set(layout.buildDirectory.dir("devlibs"))
archiveFileName.set("essentialpartner.jar")
inputs.property("essentialPartnerModPackage", essentialPartnerModPackage)
val configuration = project.configurations.detachedConfiguration(project.dependencies.create(essentialPartnerModDep))
dependsOn(configuration)
from({ configuration.map { zipTree(it) } })
exclude("mcmod.info", "META-INF/mods.toml", "META-INF/neoforge.mods.toml", "pack.mcmeta", "gg/essential/partnermod/EssentialPartnerMod.class")
relocate("gg.essential.partnermod", essentialPartnerModPackage)
filesMatching("gg/essential/partnermod/mixins.json") {
filter { it.replace("gg.essential.partnermod", essentialPartnerModPackage) }
}
}
// Include the relocated classes into your jar
tasks.jar {
from(relocatedEssentialPartnerModJar.map { it.archiveFile }.map { zipTree(it) })
}1.16.5+ Forge and NeoForge
An example using the Kotlin buildscript can be found in examples/1.20.4-forge and an example using the Groovy buildscript can be found in examples/1.16.5-forge.
The following highlights the important sections (using the Kotlin buildscript, if using the Groovy buildscript refer to the respective example).
// Apply the shadow plugin
plugins {
// Load the shadow plugin.
// We don't need to apply it since we don't want the default shadowJar task.
id("com.gradleup.shadow") version "8.3.5" apply false
}
repositories {
// If you use a groovy buildscript instead of a Kotlin one, use {} instead of ().
// If you use the defaults plugin from Essential Gradle Toolkit, the repository is likely already added.
maven(url = "https://repo.essential.gg/public")
}
// Replace this with a package within your mod package
val essentialPartnerModPackage = "com.example.mod.essentialpartnermod"
tasks.jar {
manifest.attributes(
// The main entry point of the Essential Partner mod are its mixins.
// Note that you may have to re-declare your own mixin configs here too depending on your build system.
"MixinConfigs" to "${essentialPartnerModPackage.replace(".", "/")}/mixins.json,mixins.examplemod.json",
)
}
// Replace ${mcVersion} with the Minecraft version
// Replace ${partnerModVersion} with the Partner Mod version
// Replace ${platform} with "forge" for Forge and "neoforge" for NeoForge
// Refer to the Supported Versions table for both of these
val essentialPartnerModDep = "gg.essential:partner-mod-integration-${mcVersion}-${platform}:${partnerModVersion}"
// Relocate Essential Ad into your mod's package
val relocatedEssentialPartnerModJar by tasks.registering(com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar::class) {
destinationDirectory.set(layout.buildDirectory.dir("devlibs"))
archiveFileName.set("essentialpartner.jar")
inputs.property("essentialPartnerModPackage", essentialPartnerModPackage)
val configuration = project.configurations.detachedConfiguration(project.dependencies.create(essentialPartnerModDep))
dependsOn(configuration)
from({ configuration.map { zipTree(it) } })
exclude("mcmod.info", "META-INF/mods.toml", "META-INF/neoforge.mods.toml", "pack.mcmeta", "gg/essential/partnermod/EssentialPartnerMod.class")
relocate("gg.essential.partnermod", essentialPartnerModPackage)
filesMatching("gg/essential/partnermod/mixins.json") {
filter { it.replace("gg.essential.partnermod", essentialPartnerModPackage) }
}
}
// Include the relocated classes into your jar
tasks.jar {
from(relocatedEssentialPartnerModJar.map { it.archiveFile }.map { zipTree(it) })
}- Added support for Fabric on Minecraft 1.21.6
- Added support for Forge on Minecraft 1.20.6, 1.21, 1.21.3, 1.21.4, and 1.21.5
- Added support for NeoForge on Minecraft 1.20.4, 1.20.6, 1.21, 1.21.3, 1.21.4, and 1.21.5
- Replaced Fabric 1.21 with Fabric 1.21.1 (these two versions are compatible, however 1.21.1 is the version that we support for Forge and NeoForge)
- Initial Release