This is an old revision of the document!


NeoForge Migration

Since an Architectury Loom 1.4 update, NeoForge 1.20.2 support has been introduced into Architectury. This page serves as a tutorial on how to migrate to NeoForge, depending on your current project, and your goals. The tutorials can be applied in reverse if needed.

We assume the migration is not easy, please feel free to step by the Discord server for assistance.

About MinecraftForge

To read more about our support on MinecraftForge and NeoForge, you may read more on the migration page for 1.20.2. To summerize, we will continue to provide support for MinecraftForge and NeoForge's toolchain for the forseeable future. For Architectury API, we will prioritize compatibility for NeoForge over MinecraftForge in situations where it is impossible to maintain compatibility for both.

About Yarn

Architectury Loom had always supported Yarn as a mappings option for Forge, and will continue to do so for NeoForge. NeoForge has removed srg mappings as intermediary, such that both the development environment and production environment both use the same mappings.

Architectury Loom 1.4 adds “hopes” and “prayers” to NeoForge in order to support Yarn. Remapping may not be done perfectly, so here's a few things to take note.

  1. Write ATs in Mojang Mappings
  2. Don't use JS coremods
  3. Don't use reflection to access Minecraft internals (while we have a solution to remap reflection, it is not yet in Architectury Loom because we really really don't want to use it)
  4. MixinExtras may not function properly if you use Yarn (We have ditched refmaps for mixins, and our remapper is currently not capable of remapping MixinExtras)

Migrate your Forge-only project to NeoForge

1. Update to latest Gradle & Architectury Loom 1.4

On the top of build.gradle, replace the loom version with 1.4-SNAPSHOT.

2. Modify gradle.properties

loom.platform = neoforge

3. Add the NeoForge maven

Add maven { url “https://maven.neoforged.net/releases/” } to your build.gradle.

4. Remove the loom.forge {} block

The mixins declared should go directly to META-INF/mods.toml (see https://github.com/neoforged/FancyModLoader/pull/31)). Converted ATs can be added directly to remapJar.

Custom AT paths can be modified in the loom.neoForge {} block.

5. Replace the Forge dependency

neoForge "net.neoforged:neoforge:VERSION"

6. Make sure your project's JavaCompile version is 17.

You should have something similar to this, change the version to 17.

tasks.withType(JavaCompile) {
  // ensure that the encoding is set to UTF-8, no matter what the system default is
  // this fixes some edge cases with special characters not displaying correctly // see [http://yodaconditions.net/blog/fix-for-java-file-encoding-problems-with-gradle.html](http://yodaconditions.net/blog/fix-for-java-file-encoding-problems-with-gradle.html)
  // If Javadoc is generated, this must be specified in that task too.
  options.encoding = "UTF-8"
  options.release = 17
}

7. Refresh Gradle & Run Configs, Fix Errors & META-INF/mods.toml & Profit??

Migrate your Architectury project to NeoForge

NeoForge can be added as an additional subproject for any Architectury Projects.

While Forge-like setups are possible (where Forge and NeoForge projects share common code), it is not recommended since you will need to do manual remapping configuration, which is not trivial and is prone to crashes.

The following section is split between three variants:

  1. Migrate your Forge subproject to NeoForge
  2. Add a NeoForge subproject independent of the Forge subproject
  3. Add a Forge-like subproject, and a NeoForge subproject

Migrate your Forge subproject to NeoForge

1. Update to latest Gradle & Architectury Loom 1.4

On the top of build.gradle, replace the loom version with 1.4-SNAPSHOT.

2. Modify forge/gradle.properties

loom.platform = neoforge

3. Add the NeoForge maven

Add maven { url “https://maven.neoforged.net/releases/” } to your forge/build.gradle or build.gradle's subprojects block.

4. Remove the loom.forge {} block in forge/build.gradle

The mixins declared should go directly to META-INF/mods.toml (see https://github.com/neoforged/FancyModLoader/pull/31)). Converted ATs can be added directly to remapJar.

Custom AT paths can be modified in the loom.neoForge {} block.

5. Replace the Forge dependency in forge/build.gradle

neoForge "net.neoforged:neoforge:VERSION"

If you are using Architectury API, make sure to change architectury-forge to architectury-neoforge.

6. Make sure your project's JavaCompile version is 17.

You should have something similar to this, change the version to 17.

tasks.withType(JavaCompile) {
  // ensure that the encoding is set to UTF-8, no matter what the system default is
  // this fixes some edge cases with special characters not displaying correctly // see [http://yodaconditions.net/blog/fix-for-java-file-encoding-problems-with-gradle.html](http://yodaconditions.net/blog/fix-for-java-file-encoding-problems-with-gradle.html)
  // If Javadoc is generated, this must be specified in that task too.
  options.encoding = "UTF-8"
  options.release = 17
}

7. Add NeoForge as a compile target in common/build.gradle

architectury {
  common("fabric", "neoforge")
}

8. Modify forge/build.gradle

First, change forge() to neoForge() in the architectury block.

architectury {
  platformSetupLoomIde()
  neoForge()
}

Optional: If you want to keep forge as the package extension for @ExpectPlatform annotations, set platformPackage in the neoForge block and common:

// In common/build.gradle
architectury {
  common("fabric", "neoforge") {
    // This means map neoforge to forge
    it.platformPackage "neoforge", "forge"
  }
}
 
// In forge/build.gradle
architectury {
  platformSetupLoomIde()
  neoForge {
    platformPackage = "forge"
  }
}

Then, modify your configurations, change developmentForge to developmentNeoForge:

configurations {
  common
  shadowCommon // Don't use shadow from the shadow plugin because we don't want IDEA to index this.
  compileClasspath.extendsFrom common
  runtimeClasspath.extendsFrom common
  developmentNeoForge.extendsFrom common
}

Now, in your dependencies block, change transformProductionForge to transformProductionNeoForge.

dependencies {
  // ...
  shadowCommon(project(path: ":common", configuration: "transformProductionNeoForge")) { transitive false }
}

9. Check usages of ArchitecturyTarget.getCurrentTarget()

ArchitecturyTarget.getCurrentTarget() will return “neoforge” on NeoForge, check if you are expecting that.

10. Refresh Gradle & Run Configs, Fix Errors & forge/META-INF/mods.toml & Profit??

Add a NeoForge subproject independent of the Forge subproject

1. Initial Setup

Create a neoforge folder, copy your forge folder's build.gradle and gradle.properties.

Then in settings.gradle, add include “neoforge” under the forge line.

2. Setup NeoForge

Follow the steps above in “Migrate your Forge subproject to NeoForge”, but make sure you are applying to the neoforge project instead of the forge project.

Add a Forge-like subproject, and a NeoForge subproject

WIP