NeoForge for Minecraft 26.1

This blog post covers a selection of the most important changes for modders updating to Minecraft 26.1! As of writing, the latest NeoForge version is 26.1.0.1-beta.

There are strong indications that 26.1 will be the next stable modding version, replacing 1.21.1, so I encourage all modders to port their mods to 26.1. If you are porting from 1.21.1, I would recommend reading:

• The 21.2 release notes
• The 21.4 release notes
• The 21.5 release notes
• The 21.6 release notes
• The 21.9 release notes
• The 21.11 release notes

This is a personal educated guess, not an official statement from the NeoForge team as a whole.

NeoForge versions now have four components to match the new versioning system of Minecraft! The first three components identify the Minecraft version, the last the NeoForge release. For example in 26.1.0.10-beta we have 26.1.0 (26.1 hotfix 0) for Minecraft, 10 for the NeoForge release, and the -beta suffix indicating that breaking changes are still allowed. As usual the -beta suffix will be dropped to stabilize the release after some time.

Mojang has removed obfuscation in 26.1. For modders, this means that the official parameter names used by the developers of Minecraft are now available!

Us NeoForge maintainers have taken this chance to simplify the toolchain surrounding NeoForm (our project derived from MCP that sets recompilable Minecraft sources): the repository and build system have been cleaned up and streamlined. Note that this comes with a versioning change for NeoForm: NeoForm versions are now of the form <mc version>-<neoform build>. For example, 26.1-1 for the first NeoForm build for Minecraft 26.1.

Make sure to update your Gradle plugin. Currently, the latest version of ModDevGradle (MDG) is 2.0.141 and the latest version of NeoGradle (NG) is 7.1.21.

Minecraft is now using Java 25, so once you have updated MDG or NG, make sure to update your Gradle version as well. Gradle 9.1.0 or newer is required. The easiest way to update Gradle is to change the version in the distributionUrl property of the gradle/wrapper/gradle-wrapper.properties file.

Additionally, make sure to update the language version in your Gradle build:

  java {
      toolchain {
-         languageVersion = JavaLanguageVersion.of(21)
+         languageVersion = JavaLanguageVersion.of(25)
      }
  }

Then, you can update the NeoForge version as usual. For example, if you set the version in gradle.properties:

- neoforge_version=21.1.113
+ neoforge_version=26.1.0.1-beta

Finally, Parchment can be removed since Mojang’s parameter names are now available thanks to the removal of obfuscation. For example, if you were setting Parchment via gradle.properties, you can delete the corresponding lines:

- neoForge.parchment.minecraftVersion=1.21
- neoForge.parchment.mappingsVersion=2024.07.28

You can also keep it to benefit from additional javadocs.

Due to changes in how data components work, instantiating new ItemStacks now require the registries to be loaded. To represent stacks before that, for example in recipes and other data files, there is now ItemStackTemplate.

An ItemStackTemplate is a record of the item holder, the count, and the data component patch. Note that ItemStackTemplates cannot be empty; if an empty template is needed, null is used. @Nullable ItemStackTemplate can thus be understood as an immutable version of a potentially empty ItemStack. To convert a template to a stack, use template.create(). To convert a non-empty stack to a template, use ItemStackTemplate.fromNonEmptyStack(stack).

Similarly to item stacks, ItemResources also require the registries to be loaded, meaning that only ItemStackTemplates should be used in data files. Note that added a few extra helper methods to ItemStack and ItemResource such as matches.isSameItemSameComponents(stack, template) and resource.matches(template).

We have mirrored these changes to fluids: FluidStack and FluidResource now require the registries to be loaded, and we have introduced FluidStackTemplate. Note that fluids can have default data components as well now.

As in the last few releases, rendering continues to be refactored at a fast pace. GuiGraphics was renamed to GuiGraphicsExtractor, and many GUI-related methods were renamed in a similar fashion. For example:

A new helper class was added to NeoForge: MutableQuad. It acts as a mutable representation of a BakedQuad, allowing for easy construction and modification of quads. It also provides more advanced utility methods such as:

• setCubeFaceFromSpriteCoords to generate the positions of a face by using a 2D coordinate system as if you were looking at the sprite textured on that face;
• setCubeFace to generate the positions of a 3D cube face by giving the cube’s extent;
• bakeUvsFromPosition to generate the texture coordinates of the quad similar to how Vanilla block models do, with optional transformations;
• recalculateWinding to reorder the vertices of the quad to match the vertex order expected by Vanilla ambient occlusion for axis-aligned quads;
• setSpriteAndMoveUv to change the sprite used by a quad while remapping the atlas uv automatically.

We hope that you will find it useful.

A few changes to ChunkPos construction and conversion to/from long:

// BlockPos -> ChunkPos
- new ChunkPos(blockPos)
+ ChunkPos.containing(blockPos)
// ChunkPos or x,z -> long
- ChunkPos.asLong(blockPos)
+ ChunkPos.pack(blockPos)
// long -> ChunkPos
- new ChunkPos(packedLong)
+ ChunkPos.unpack(packedLong)

A good strategy to migrate your mod is to have a working Minecraft 1.21.11 (or 1.21.1) workspace alongside your in-progress Minecraft 26.1 workspace. This allows you to quickly find out how to update specific pieces of code. The workflow is as follows:

1. Find a function call that doesn’t compile anymore in 26.1.
2. Find the same function call in the 1.21.11 workspace that still compiles.
3. Right click the function call, and go to a vanilla usage of the method. Note: In IntelliJ, this requires the Minecraft sources to be attached, and the scope for the search needs to be set to All Places!
4. Go to the same vanilla usage in 26.1, and compare to see how vanilla updated their code.
5. In many cases it is enough to make the same change to your code.

This can also be applied on a larger scale than a function call, for example to learn how recipe output datagen changed between 1.21.11 and 26.1.

I also encourage you to look through the Minecraft changes section of Fabric’s blog post for a different set of highlights.

Additionally, a porting primer covering a lot more of Minecraft’s changes is available here (courtesy of @ChampionAsh5357).

With the increase Minecraft update frequency, it seems that we the NeoForge maintainers are more short-staffed than ever. Anyone reading this, if you feel motivated to help, please don’t hesitate to look through the issue tracker and see if you might be able to help!

Additionally, I want to acknowledge the substantial amount of work that @ApexModder, @shartte, @XFactHD put into keeping NeoForge up-to-date on the various 26.1 snapshots. Thank you!

That’s all for this blog post, happy porting!