1.21.1 to 26.1 NeoForge Porting Guide

This site indexes the upstream NeoForge porting primers so you can jump straight to the section that matters.

The upstream chain covered here is:

1.21.1 -> 1.21.2/3 -> 1.21.4 -> 1.21.5 -> 1.21.6 -> 1.21.7 -> 1.21.8 -> 1.21.9 -> 1.21.10 -> 1.21.11 -> 26.1

There is no separate 1.21.3 primer upstream. The 1.21.2 primer covers the 1.21.1 -> 1.21.2/3 step.

How to use this site

If you know what subsystem changed, use the Topic Map below. Every link goes directly to the relevant section.

If the same subsystem changed across multiple versions, see Repeatedly Changing Systems for the reading order.

If you want the raw primers, see Detailed Primers for a full table of contents with anchor links to every section.

If you have a compile error, use the Class and Method Index to find where it changed.

Topic Map

Build, mappings, names, imports, and package moves

• The Rename Shuffle (1.21.11)
• ResourceLocation to Identifier (1.21.11)
• The util Package (1.21.11)
• critereon to criterion (1.21.11)
• Entity and Object Subpackages (1.21.11)
• Java 25 and Deobfuscation (26.1)
• JSpecify Annotations (1.21.11)
• Usage Annotations (1.21.11)

Datagen, packs, registries, tags, codecs, loot, validation, and recipe serialization

• The Holder Set Transition (1.21.2)
• The Ingredient Shift (1.21.2)
• Recipes, now in Registry format (1.21.2)
• Recipe Providers, the ‘not actually’ of Data Providers (1.21.2)
• Instruments, the Datapack Edition (1.21.2)
• Trial Spawner Configurations, now in Datapack Form (1.21.2)
• Critereons, Supplied with HolderGetters (1.21.2 minor)
• Codecable Json Reload Listener (1.21.2 minor)
• Context Keys (1.21.2 minor)
• SimpleJsonResourceReloadListener (1.21.4 minor)
• MetadataSectionSerializer, replaced by Codecs (1.21.4 minor)
• Tags and Parsing (1.21.5)
• Model Rework (1.21.5)
• Registry Context Swapper (1.21.5 minor)
• Timer Callbacks, joining the codec club! (1.21.5 minor)
• Tag Providers: Appender Rewrite (1.21.6)
• Generic Encoding and Decoding: Replacing Direct NBT Access (1.21.6)
• Loot Type Unrolling (26.1)
• Validation Overhaul (26.1)
• Datapack Villager Trades (26.1)
• Serializer Records and Recipe Info (26.1)
• New Tag Providers (26.1 minor)
• Plantable Tags (26.1 minor)

Items, components, equipment, armor, tools, combat, dyes, and consumables

• Equipments and Items, Models and All (1.21.2)
• Armor Materials, Equipment, and Model (Textures) (1.21.2)
• Consumables (1.21.2)
• Interaction Results (1.21.2)
• BlockEntityTypes Privatized! (1.21.2)
• Registry Objcet Id, in the Properties? (1.21.2)
• Properties Changes (1.21.2)
• Fuel Values (1.21.2 minor)
• Mob Replacing Current Items (1.21.4)
• Weapons, Tools, and Armor: Removing the Redundancies (1.21.5)
• Data Component Getters (1.21.5)
• Component Interaction Events (1.21.5 minor)
• Item Owner (1.21.9 minor)
• Container User (1.21.9 minor)
• Slot Sources (1.21.11 minor)
• New Data Components (1.21.11)
• Data Component Initializers (26.1)
• Item Instances and Stack Templates (26.1)
• Dye Component (26.1)
• Data Component Additions (26.1 minor)

Rendering, models, shaders, particles, block models, item models, materials, atlases, and visual pipelines

• Gui Render Types (1.21.2)
• Shader Rewrites (1.21.2)
• Entity Render States (1.21.2)
• Fog Parameters (1.21.2 minor)
• Light Emissions (1.21.2 minor)
• Map Textures (1.21.2 minor)
• Client Items (1.21.4)
• Particles, rendered through Render Types (1.21.4)
• Render Pipeline Rework (1.21.5)
• Model Rework (1.21.5)
• Texture Atlas Reworks (1.21.5 minor)
• GUI Changes (1.21.6)
• Blaze3d Changes (1.21.6)
• Removal of Mob Effects Atlas (1.21.6 minor)
• Animation Baking (1.21.6 minor)
• ChunkSectionLayers (1.21.6 minor)
• Minor Migrations (1.21.7 – GUI render follow-ups)
• Minor Migrations (1.21.8 – GraphicsWorkarounds)
• Feature Submissions: The Movie (1.21.9)
• The Font Glyph Pipeline (1.21.9)
• Client Asset Split (1.21.9 minor)
• Oh Hey, Another Rendering Rewrite (1.21.11)
• Gizmos (1.21.11)
• Even More Rendering Changes (26.1)
• Entity Textures and Adult/Baby Models (26.1 minor)
• Audio Changes (26.1 minor)

Entities, mobs, mob AI, conversions, spawning, and entity data

• Interaction Results (1.21.2)
• EXPLOOOOSSSION! (1.21.2 minor – Explosion is now an interface)
• Mob Conversions (1.21.2 minor – Mob#convertTo changed)
• Minecart Behavior (1.21.2 minor)
• Ender Pearl Chunk Loading (1.21.2 minor)
• Entity References (1.21.5 minor – UUID replaced by EntityReference)
• Leashes (1.21.6 minor)
• Typed Entity Data (1.21.9 minor)
• Name And Id (1.21.9 minor)
• The Removal of interactAt (26.1 minor – Entity#interactAt removed)
• Activities and Brains (26.1 minor – AI brain system changes)
• More Entity Sound Variant Registries (26.1 minor)
• Zombie Nautilus Variant (1.21.11 minor)

GUI, input, keybinds, debug screens, debug tooling, RPC tooling, and test infrastructure

• Gui Render Types (1.21.2)
• The Game Test Overhaul (1.21.5)
• GUI Changes (1.21.6)
• Minor Migrations (1.21.7)
• The Debugging Overhaul (1.21.9)
• Debug Screens (1.21.9)
• The JSON-RPC Management Servers (1.21.9)
• Input Handling Consolidation (1.21.9)
• Cursor Types (1.21.9 minor)
• Gizmos (1.21.11)
• Text Collectors (1.21.11 minor)
• OptionEnum Removal (1.21.11 minor)
• Container Screen Changes (26.1 minor)
• Input Message Editor Support (26.1 minor)
• Test Environment State Tracking (26.1 minor)

World state, saved data, game rules, timelines, clocks, players, permissions, waypoints, and other server-side systems

• Handling the Removal of Block Entities Properly (1.21.5)
• Voxel Shape Helpers (1.21.5)
• Weighted List Rework (1.21.5)
• Tickets (1.21.5)
• Saved Data, now with Types (1.21.5)
• Block Effect Appliers (1.21.5 minor)
• Waypoints (1.21.6)
• Server Player Changes (1.21.6)
• Permission Sources (1.21.6 minor)
• Level#isClientSide now private (1.21.9)
• Ticket Flags (1.21.9 minor)
• Respawn Data (1.21.9 minor)
• Permission Overhaul (1.21.11)
• The Timeline of Environment Attributes (1.21.11)
• The Game Rule Shuffle (1.21.11)
• Level#random field now protected (26.1)
• World Clocks and Time Markers (26.1)
• Splitting the Primary Level Data into Saved Data (26.1)
• Chat Permissions (26.1 minor)
• ChunkPos, now a record (26.1 minor)
• Cauldron Interaction Dispatchers (26.1 minor)
• Fluid Logic Reorganization (26.1 minor)
• Removal of Random Patch Feature (26.1 minor)
• Rule-Based Block State Providers (26.1 minor)
• File Fixer Upper (26.1 minor)

Remaining minor migrations

• Language File Removals and Renames (1.21.2)
• MacosUtil#IS_MACOS (1.21.2)
• Smarter Framerate Limiting (1.21.2)
• Orientations (1.21.2)
• The Removal of the Carving Generation Step (1.21.2)
• Consecutive Executors (1.21.2)
• Profilers and the Tracy Client (1.21.2)
• Tick Throttler (1.21.2)
• Music, now with Volume Controls (1.21.4)
• Descoping Player Arguments (1.21.5)
• Reload Instance Creation (1.21.5)
• The JOML Backing Interfaces (1.21.5)
• Mob Effects Field Renames (1.21.5)
• Reload Listener Shared State (1.21.9)
• The ‘On Shelf’ Transform (1.21.9)
• Shared Text Areas Debugger (1.21.11)
• Specific Logic Changes (1.21.11)
• Typed Instance (26.1)
• No More Tripwire Pipelines (26.1)
• Environment Attribute Additions (26.1)
• Specific Logic Changes (26.1)

Every primer also contains New Tags, Tag Changes, List of Additions, List of Changes, and List of Removals subsections within their Minor Migrations. For those, go to the full primer pages in Detailed Primers.

Class and Method Index

If you have a compile error or need to find where a specific class/method changed, search this table.

Source and attribution

The split primer pages are copied from ChampionAsh5357/neoforged-github, branch update/26.1. See Source And Attribution.