Repeatedly Changing Systems
This page is the guard rail for the direct port.
When the same subsystem changed in multiple intermediate versions, do not treat the earliest migration note as final. Use the latest applicable version as the source of truth, but still apply the older chapter first so the intermediate API transitions make sense.
Rendering and graphics
Relevant sections:
- Gui Render Types (1.21.2)
- Shader Rewrites (1.21.2)
- Entity Render States (1.21.2)
- Render Pipeline Rework (1.21.5)
- Model Rework (1.21.5)
- GUI Changes (1.21.6)
- Blaze3d Changes (1.21.6)
- Minor Migrations (1.21.7)
- Feature Submissions: The Movie (1.21.9)
- The Font Glyph Pipeline (1.21.9)
- Oh Hey, Another Rendering Rewrite (1.21.11)
- Even More Rendering Changes (26.1)
How to read them:
1.21.2/3changes GUI blits, shader JSON structure, and render-state assumptions.1.21.5is the first large rendering infrastructure rewrite aroundRenderPipeline,GpuTexture, and render passes.1.21.6changes GUI rendering flow again through prepare/render state separation.1.21.9changes how features are submitted for rendering.1.21.11changes samplers, render types, terrain split, and atlases.26.1is the final authority for block/item rendering, materials, tint sources, fluid models, particle layers, and backend-facing rendering APIs.
Practical rule:
- Treat
26.1as the final rendering target. - Keep
1.21.4client items and1.21.6GUI flow as still-active requirements, not obsolete history.
Item models and item metadata
Relevant sections:
- Client Items (1.21.4)
- Mob Replacing Current Items (1.21.4)
- Particles, rendered through Render Types (1.21.4)
- Weapons, Tools, and Armor: Removing the Redundancies (1.21.5)
- Data Component Getters (1.21.5)
- Feature Submissions: The Movie (1.21.9)
- Oh Hey, Another Rendering Rewrite (1.21.11)
- New Data Components (1.21.11)
- Data Component Initializers (26.1)
- Item Instances and Stack Templates (26.1)
- Dye Component (26.1)
- Even More Rendering Changes (26.1)
What sticks:
1.21.4client items are the baseline for item rendering data.1.21.5removes more hardcoded item-class assumptions in favor of components and equipment data.1.21.9,1.21.11, and26.1further change how items participate in rendering and metadata pipelines.
Practical rule:
- First convert item assets to client items.
- Then port behavior and metadata around components.
- Finally validate them against the
26.1rendering and item-instance model.
Tags, registries, codecs, and validation
Relevant sections:
- The Holder Set Transition (1.21.2)
- Registry Objcet Id, in the Properties? (1.21.2)
- Recipes, now in Registry format (1.21.2)
- Tags and Parsing (1.21.5)
- Tag Providers: Appender Rewrite (1.21.6)
- Generic Encoding and Decoding: Replacing Direct NBT Access (1.21.6)
- The Rename Shuffle (1.21.11)
- Loot Type Unrolling (26.1)
- Validation Overhaul (26.1)
- Serializer Records and Recipe Info (26.1)
What sticks:
1.21.2/3is whereHolderandHolderSetstart affecting large parts of the codebase.1.21.5changes tag access, parser behavior, codec-based reads and writes, and saved-data construction.1.21.6changes tag provider building and nudges more code toward generic encoding and decoding.1.21.11contributes rename churn that affects registry and identifier-facing code.26.1finalizes more codec-driven infrastructure with loot type unrolling and validation overhaul.
Practical rule:
- The earlier chapters tell you how to get onto holder- and codec-based APIs.
26.1is the final target for validation and loot registration shape.
Data components
Relevant sections:
- Consumables (1.21.2)
- Equipments and Items, Models and All (1.21.2)
- The Ingredient Shift (1.21.2)
- Recipes, now in Registry format (1.21.2)
- Weapons, Tools, and Armor: Removing the Redundancies (1.21.5)
- Data Component Getters (1.21.5)
- New Data Components (1.21.11)
- Data Component Initializers (26.1)
- Dye Component (26.1)
What sticks:
1.21.2/3introduces important component-facing migrations such as consumables and recipe-related data moves.1.21.5expands component-centered behavior for tools, armor, weapons, and general data access.1.21.11adds more component types.26.1continues with initializers, dye components, and more component additions.
Practical rule:
- Expect items and recipes to get less class-driven and more component-driven as you move forward.
Saved data and world state
Relevant sections:
- Saved Data, now with Types (1.21.5)
- Splitting the Primary Level Data into Saved Data (26.1)
- World Clocks and Time Markers (26.1)
What sticks:
1.21.5moves saved data toSavedDataType.26.1splits primary level data further into dedicated saved-data objects.
Practical rule:
- Do the
1.21.5migration first, then revisit every level/world persistence assumption again in26.1.
Developer tooling, tests, debugging, and permissions
Relevant sections:
- The Game Test Overhaul (1.21.5)
- The Debugging Overhaul (1.21.9)
- Debug Screens (1.21.9)
- The JSON-RPC Management Servers (1.21.9)
- Permission Overhaul (1.21.11)
- Gizmos (1.21.11)
- Java 25 and Deobfuscation (26.1)
What sticks:
1.21.5overhauls game tests.1.21.9overhauls debugging and management-server shape.1.21.11adds a permission overhaul and gizmo-focused visualization work.26.1adds Java 25 and more minor tooling-facing changes.
Practical rule:
- Port gameplay code first.
- Then re-enable your debug, test, and operator-only tooling against the later chapters.