Migrating Ornithe mod development environments from Gen1 to Gen2.

migrating-ornithe-gen1-mods-to-gen2.md

Now that Gen2 is stable, I'm sure you're all itching to migrate your Gen1 mods to Gen2. Luckily we thought ahead a little bit and there's a relatively straightforward path for migrating Loom projects. However, for projects targeting Minecraft versions below 1.3 with both a client and server component, there is extra work needed.

The migration itself comes down to updating the build script and dependencies. If your project uses Feather mappings, they will have to be updated, which will likely be the most tedious part of the process. The first guide below will walk you through how this is done. If your project uses MCP mappings, follow the second guide below, which will skip over some unnecessary steps.

Migration for projects using Feather mappings

The basic premise is as follows: migrate your Gen1 project to the latest Feather gen1 builds, then update the build script for Gen2, et voila! your Gen1 project is now a Gen2 project.

1. Update the Gradle version of your project to 9.2+ (recommended 9.2.1 at the time of writing). Run the following command in terminal: > ./gradlew wrapper --gradle-version 9.2.1. If you updated from an old version, you may have to fix up your build script.
   • archivesBaseName was removed in favor of base.archivesName.
   • sourceCompatibility and targetCompatibility must be set in the java { } block.
2. Update your project to use Loom/Ploceus 1.15. If you updated from an old version, you may have to fix up your build script.
   • ploceus.addCommonLibraries() was removed, and library upgrades are applied by default. They can be disabled with ploceus.disableLibraryUpgrades(), but this is not recommended, as the library upgrades are applied in production environments.
   • ploceus.nestedMappings() was removed. Use ploceus.featherMappings(...) to create a Feather mappings dependency with inner class patches applied, or ploceus.mappings(...) to create a custom mappings dependency with inner class patches applied.
   • ploceus.nests(...), ploceus.raven(..), ploceus.sparrow(...) were added for creating dependencies for Nests, Raven, and Sparrow respectively.
3. Check https://ornithemc.net/develop/ for the latest Feather gen1 build for the Minecraft version of your project. For example, for Minecraft 1.7.2 the latest gen1 Feather gen1 build is 31.
4. Migrate your project to the latest Feather gen1 build using Loom's migration feature. For example, if your project targets Minecraft 1.7.2, migrate to Feather version 1.7.2+build.31. Run the following command in terminal: > ./gradlew migrateMappings --mappings "net.ornithemc:feather:1.7.2+build.31". The migrated source will be in the ./remappedSrc directory of your project. Back up your old source and implement the migrated source.
5. Update your project setup for Gen2. This comes down to the following changes in build.gradle:
   • add setIntermediaryGeneration(2) to the ploceus { } block.
   • If your project targets Minecraft versions between Beta 1.0 and release 1.3, and depends on Nests, Raven, and/or Sparrow, you will have to change how you declare those dependencies. For client-side projects, you must add these dependencies to the clientNests, clientExceptions, clientSignatures configurations respectively, and for server-side projects to the serverNests, serverExceptions, serverSignatures configurations.
6. Check https://ornithemc.net/develop/ again and update your dependencies' versions in gradle.properties. Remember to select Gen2!
7. Rebuild the project and fix any errors introduced by the migration process.

Migration for projects using MCP mappings

1. Update the Gradle version of your project to 9.2+ (recommended 9.2.1 at the time of writing). Run the following command in terminal: > ./gradlew wrapper --gradle-version 9.2.1. If you updated from an old version, you may have to fix up your build script.
   • archivesBaseName was removed in favor of base.archivesName.
   • sourceCompatibility and targetCompatibility must be set in the java { } block.
2. Update your project to use Loom/Ploceus 1.15. If you updated from an old version, you may have to fix up your build script.
   • ploceus.addCommonLibraries() was removed, and library upgrades are applied by default. They can be disabled with ploceus.disableLibraryUpgrades(), but this is not recommended, as the library upgrades are applied in production environments.
   • ploceus.nestedMappings() was removed. Use ploceus.featherMappings(...) to create a Feather mappings dependency with inner class patches applied, or ploceus.mappings(...) to create a custom mappings dependency with inner class patches applied.
   • ploceus.nests(...), ploceus.raven(..), ploceus.sparrow(...) were added for creating dependencies for Nests, Raven, and Sparrow respectively.
3. Update your project setup for Gen2. This comes down to the following changes in build.gradle:
   • add setIntermediaryGeneration(2) to the ploceus { } block.
   • If your project targets Minecraft versions between Beta 1.0 and release 1.3, and depends on Nests, Raven, and/or Sparrow, you will have to change how you declare those dependencies. For client-side projects, you must add these dependencies to the clientNests, clientExceptions, clientSignatures configurations respectively, and for server-side projects to the serverNests, serverExceptions, serverSignatures configurations.
4. Rebuild the project and fix any errors introduced by the migration process.

Migration for projects targeting Minecraft Beta 1.0 - release 1.3

If your project targets Minecraft versions between Beta 1.0 and release 1.3, and has both a client and server component, there are a few extra steps to the migration process. Gen2 makes it possible to combine the client and server components into one project, similar to how you are used to developing mods for 1.3 and above.

This process is a bit more involved, and if you are unsure how to go about it, it is recommended you start with a fresh copy of the mod template, and copy the migrated client and server projects into it.

1. Start by cloning a fresh copy of the mod template.
   • Switch to the gen2/fabric branch of the template, or select the gen2/fabric branch when generating a repository from the template.
2. Configure the project like normal, and add any dependencies your migrated projects required.
3. Update the mod.json, again referencing your migrated projects.
4. Copy the source from your migrated projects over into the new project. Depending on how you structured your code, you may have similar or identical classes in both the client and server components. You'll want to either combine them or rename them so they don't conflict.
5. You can even re-design elements of the mod to better take advantage of the merged development environment, but that is beyond the scope of this guide.

After this, you should have a working Gen2 port of your Gen1 mod!