NeoForge 26.1 porting notes

Checked against NeoForge for Minecraft 26.1 (NeoForge blog, 24 March 2026) and NeoForge’s 1.21.11 → 26.1 primer on 2 November 2026.

Coming from 1.21.1?

NeoForge’s post says to read the release notes of the versions in between first: 21.2, 21.4, 21.5, 21.6, 21.9 and 21.11.

Version numbers

NeoForge versions now have four parts. In 26.1.0.10-beta, 26.1.0 is Minecraft 26.1 (hotfix 0), 10 is the NeoForge release, and -beta means breaking changes are still allowed. The -beta goes away once the version is stable. Linen’s NeoForge templates use 26.1.2.114 for 26.1.2, 26.2.0.88 for 26.2 and 26.3.0.23-beta for 26.3.

Build changes

In this order, from NeoForge’s post:

Update the Gradle plugin. When the post was written the newest were ModDevGradle 2.0.141 and NeoGradle 7.1.21. Linen’s NeoForge 26.x templates, taken from NeoForge’s official MDKs, use ModDevGradle 2.0.148 (2.0.147 for 26.3):
```
plugins {
    id 'net.neoforged.moddev' version '2.0.148'
}
```
Update Gradle to 9.1.0 or newer. Change the version in distributionUrl in gradle/wrapper/gradle-wrapper.properties. The MDKs in Linen’s templates use Gradle 9.2.1:
```
distributionUrl=https\://services.gradle.org/distributions/gradle-9.2.1-bin.zip
```

Set Java to 25:

java.toolchain.languageVersion = JavaLanguageVersion.of(25)

Change the NeoForge version. In NeoForge’s MDK it is neo_version in gradle.properties:
```
minecraft_version=26.1.2
minecraft_version_range=[26.1.2]
neo_version=26.1.2.114
```
Remove Parchment, or keep it. Mojang’s parameter names now come with the game, so Parchment is optional. NeoForge says you can keep it for its extra javadocs. In an MDK project, removing it means deleting the parchment { ... } block inside neoForge { ... } in build.gradle and the parchment_minecraft_version and parchment_mappings_version lines in gradle.properties. That is the difference between Linen’s 1.21.11 and 26.1.2 NeoForge templates. If you set Parchment with neoForge.parchment.* lines in gradle.properties, delete those instead.

Code changes NeoForge highlights

The post picks out a few. The primer covers far more of the game’s changes (loot types, villager trades, rendering, saved data and others).

Item stacks need registries. A new ItemStack can only be made once the registries are loaded. Recipes and other data use ItemStackTemplate instead: the item, the count and the component changes. A template is never empty; use null where you need “no item”.

To do this	Use
Template to stack	`template.create()`
Non-empty stack to template	`ItemStackTemplate.fromNonEmptyStack(stack)`

Fluids got the same change: FluidStack and FluidResource need the registries, and FluidStackTemplate is new.

GuiGraphics is now GuiGraphicsExtractor. Many screen methods were renamed with it:

1.21.11	26.1
`Screen#render`	`Screen#extractRenderState`
`Screen#renderBackground`	`Screen#extractBackground`
`AbstractContainerScreen#renderBg`	`Screen#extractBackground`
`AbstractContainerScreen#renderLabels`	`AbstractContainerScreen#extractLabels`

ChunkPos construction:

1.21.11	26.1
`new ChunkPos(blockPos)`	`ChunkPos.containing(blockPos)`
`ChunkPos.asLong(blockPos)`	`ChunkPos.pack(blockPos)`
`new ChunkPos(packedLong)`	`ChunkPos.unpack(packedLong)`

MutableQuad is a new NeoForge helper for building and changing baked quads.

NeoForge’s way to find what changed

The post suggests keeping a working 1.21.11 (or 1.21.1) project open next to the 26.1 one:

Find a call that no longer compiles in 26.1.
Find the same call in the old project, where it still compiles.
Go to a place where vanilla uses that method.
Open the same vanilla code in 26.1 and see how Mojang changed it. Often you can make the same change.

In Linen

Linen has no porting assistant yet. What it does today:

New mod makes a clean NeoForge project for 26.1 or newer, so you can compare build files. Linen opens a folder with one version per subfolder, so the old and new projects can sit side by side, as NeoForge suggests.
Linen installs Java 25 for a 26.x project.
Find usages and Minecraft’s code browse the decompiled game for each project’s own version, on your machine. That covers steps 3 and 4 above.
Linen Check reads registrations, models, loot tables, names, mixins and the build, and names the file and the fix.
Claude Code, Anthropic’s extension, on your own Claude plan, gets Linen’s tools (lookup_symbol, search_source, vanilla_examples, linen_decompile, gradle and others) and Linen Check after every edit. Ask it to port one class at a time with you.