Initial mdBook porting primers site

.github/workflows/deploy-pages.yml

@@ -0,0 +1,50 @@
+name: Deploy Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: latest
+
+      - name: Build book
+        run: mdbook build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./book
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,2 @@
+book/
+

README.md

@@ -0,0 +1,11 @@
+# Porting Primers
+
+This repository publishes an `mdBook` site for NeoForge porting primers covering the path from `1.21.1` to `26.1`.
+
+The content includes:
+
+- a topic-indexed landing page for jumping to the relevant primer sections
+- the split upstream primer pages
+- a compiled direct-port overview
+
+The site is deployed automatically to GitHub Pages from the `main` branch through the workflow in `.github/workflows/deploy-pages.yml`.

book.toml

@@ -0,0 +1,18 @@
+[book]
+authors = ["Leclowndu93150", "OpenAI Codex"]
+language = "en"
+src = "src"
+title = "1.21.1 to 26.1 Porting Primers"
+description = "A topic-indexed NeoForge porting guide and upstream primer archive for migrating from 1.21.1 to 26.1."
+
+[output.html]
+default-theme = "navy"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/Leclowndu93150/Porting-Primers"
+site-url = "/Porting-Primers/"
+edit-url-template = "https://github.com/Leclowndu93150/Porting-Primers/edit/main/{path}"
+no-section-label = true
+additional-css = []
+
+[output.html.search]
+enable = false

src/README.md

@@ -0,0 +1,285 @@
+# 1.21.1 to 26.1 NeoForge Porting GitBook
+
+This GitBook is organized around two goals:
+
+1. Keep every upstream primer page available on its own.
+2. Make the main page a topic map so you can jump straight to the primers that matter for a subsystem, workflow, or type of breakage.
+
+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 is the upstream `1.21.1 -> 1.21.2/3` step and is treated that way here.
+
+## How to use this GitBook
+
+If you already know the kind of change you are looking for, use the topic map below.
+
+If you want a short compiled overview first, use:
+
+- [Compiled Direct Port Guide](direct-port-guide.md)
+
+If you want the raw primers as separate pages, use:
+
+- [Detailed Primers](detailed-primers/README.md)
+
+If you want a quick view of which subsystems changed repeatedly across multiple versions, use:
+
+- [Repeatedly Changing Systems](repeatedly-changing-systems.md)
+
+## Topic Map
+
+### Build, mappings, names, imports, and package moves
+
+For Java version bumps, deobfuscation, `ResourceLocation` to `Identifier`, utility-package moves, `critereon` to `criterion`, and large import/package shuffles, go to:
+
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Rename Shuffle`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Java 25 and Deobfuscation`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Minor Migrations`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Minor Migrations`
+
+### Datagen, packs, registries, tags, codecs, loot, validation, and recipe serialization
+
+For holder sets, ingredients, recipe registry changes, datapack-facing systems, tag/provider rewrites, generic encoding, loot codec registration, validation, and serializer structure changes, go to:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Pack Changes`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `The Holder Set Transition`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Instruments, the Datapack Edition`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Trial Spawner Configurations, now in Datapack Form`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Recipe Providers, the 'not actually' of Data Providers`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `The Ingredient Shift`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Recipes, now in Registry format`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Tags and Parsing`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Model Rework`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Tag Providers: Appender Rewrite`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Generic Encoding and Decoding: Replacing Direct NBT Access`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Rename Shuffle`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Loot Type Unrolling`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Validation Overhaul`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Datapack Villager Trades`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Serializer Records and Recipe Info`
+
+### Items, components, equipment, armor, tools, combat, dyes, and consumables
+
+For modern item setup, item/equipment data, armor/equippable changes, consumables, cooldowns, data components, dye behavior, and stack-template changes, go to:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Equipments and Items, Models and All`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Armor Materials, Equipment, and Model (Textures)`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Interaction Results`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `BlockEntityTypes Privatized!`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Consumables`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Registry Objcet Id, in the Properties?`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Properties Changes`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Mob Replacing Current Items`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Weapons, Tools, and Armor: Removing the Redundancies`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Data Component Getters`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `New Data Components`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Data Component Initializers`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Item Instances and Stack Templates`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Dye Component`
+
+### Rendering, models, shaders, particles, block models, item models, materials, atlases, and visual pipelines
+
+For shaders, render types, render states, client items, particles, model baking, render pipeline rewrites, block/item model systems, atlas/material changes, GUI rendering internals, and the large `26.1` rendering pass, go to:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Gui Render Types`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Shader Rewrites`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Entity Render States`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Equipments and Items, Models and All`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Armor Materials, Equipment, and Model (Textures)`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Client Items`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Particles, rendered through Render Types`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Render Pipeline Rework`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Model Rework`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `GUI Changes`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Blaze3d Changes`
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md): `Minor Migrations`
+- [1.21.7 -> 1.21.8](detailed-primers/1.21.8-from-1.21.7.md): `Minor Migrations`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Feature Submissions: The Movie`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `The Font Glyph Pipeline`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Oh Hey, Another Rendering Rewrite`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Gizmos`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Even More Rendering Changes`
+
+### GUI, input, keybinds, debug screens, debug tooling, RPC tooling, and test infrastructure
+
+For GUI framework changes, input events, key categories, debug renderers, debug screens, tooling servers, and game tests, go to:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Gui Render Types`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `The Game Test Overhaul`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `GUI Changes`
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md): `Minor Migrations`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `The Debugging Overhaul`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Debug Screens`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `The JSON-RPC Management Servers`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Input Handling Consolidation`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Gizmos`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Permission Overhaul`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Java 25 and Deobfuscation`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Minor Migrations`
+
+### World state, saved data, game rules, timelines, clocks, players, permissions, waypoints, and other server-side systems
+
+For block removal flow, voxel shapes, weighted lists, tickets, saved data, server player changes, waypoints, permissions, game rules, timelines, clocks, and level/server data ownership, go to:
+
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Handling the Removal of Block Entities Properly`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Voxel Shape Helpers`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Weighted List Rework`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Tickets`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Saved Data, now with Types`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Waypoints`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Server Player Changes`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): ``Level#isClientSide` now private`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Permission Overhaul`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Timeline of Environment Attributes`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Game Rule Shuffle`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): ``Level#random` field now protected`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `World Clocks and Time Markers`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Splitting the Primary Level Data into Saved Data`
+
+### Short releases and catch-all API churn
+
+If the thing you are chasing is not obviously a major subsystem rewrite, check these first:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Minor Migrations`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Minor Migrations`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Minor Migrations`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Minor Migrations`
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md): `Minor Migrations`
+- [1.21.7 -> 1.21.8](detailed-primers/1.21.8-from-1.21.7.md): `Minor Migrations`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Minor Migrations`
+- [1.21.9 -> 1.21.10](detailed-primers/1.21.10-from-1.21.9.md): `Minor Migrations`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Minor Migrations`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Minor Migrations`
+
+The smallest releases in this chain are still indexed here and should not be skipped:
+
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md)
+- [1.21.7 -> 1.21.8](detailed-primers/1.21.8-from-1.21.7.md)
+- [1.21.9 -> 1.21.10](detailed-primers/1.21.10-from-1.21.9.md)
+
+## Complete Section Inventory By Version
+
+This inventory exists so the main page indexes every upstream `##` section used in this GitBook.
+
+### 1.21.1 -> 1.21.2/3
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Pack Changes`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `The Holder Set Transition`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Gui Render Types`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Shader Rewrites`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Entity Render States`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Equipments and Items, Models and All`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Armor Materials, Equipment, and Model (Textures)`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Interaction Results`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Instruments, the Datapack Edition`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Trial Spawner Configurations, now in Datapack Form`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Recipe Providers, the 'not actually' of Data Providers`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `The Ingredient Shift`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `BlockEntityTypes Privatized!`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Consumables`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Registry Objcet Id, in the Properties?`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Properties Changes`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Recipes, now in Registry format`
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md): `Minor Migrations`
+
+### 1.21.2/3 -> 1.21.4
+
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Pack Changes`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Client Items`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Mob Replacing Current Items`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Particles, rendered through Render Types`
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md): `Minor Migrations`
+
+### 1.21.4 -> 1.21.5
+
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Pack Changes`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Handling the Removal of Block Entities Properly`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Voxel Shape Helpers`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Weapons, Tools, and Armor: Removing the Redundancies`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Weighted List Rework`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Tickets`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `The Game Test Overhaul`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Data Component Getters`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Tags and Parsing`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Saved Data, now with Types`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Render Pipeline Rework`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Model Rework`
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md): `Minor Migrations`
+
+### 1.21.5 -> 1.21.6
+
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Pack Changes`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `GUI Changes`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Waypoints`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Blaze3d Changes`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Tag Providers: Appender Rewrite`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Generic Encoding and Decoding: Replacing Direct NBT Access`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Server Player Changes`
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md): `Minor Migrations`
+
+### 1.21.6 -> 1.21.7
+
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md): `Pack Changes`
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md): `Minor Migrations`
+
+### 1.21.7 -> 1.21.8
+
+- [1.21.7 -> 1.21.8](detailed-primers/1.21.8-from-1.21.7.md): `Pack Changes`
+- [1.21.7 -> 1.21.8](detailed-primers/1.21.8-from-1.21.7.md): `Minor Migrations`
+
+### 1.21.8 -> 1.21.9
+
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Pack Changes`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `The Debugging Overhaul`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Debug Screens`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Feature Submissions: The Movie`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `The Font Glyph Pipeline`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `The JSON-RPC Management Servers`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Input Handling Consolidation`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): ``Level#isClientSide` now private`
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md): `Minor Migrations`
+
+### 1.21.9 -> 1.21.10
+
+- [1.21.9 -> 1.21.10](detailed-primers/1.21.10-from-1.21.9.md): `Pack Changes`
+- [1.21.9 -> 1.21.10](detailed-primers/1.21.10-from-1.21.9.md): `Minor Migrations`
+
+### 1.21.10 -> 1.21.11
+
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Pack Changes`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Rename Shuffle`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Oh Hey, Another Rendering Rewrite`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Gizmos`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Permission Overhaul`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `New Data Components`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Timeline of Environment Attributes`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `The Game Rule Shuffle`
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md): `Minor Migrations`
+
+### 1.21.11 -> 26.1
+
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Pack Changes`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Java 25 and Deobfuscation`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Loot Type Unrolling`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Validation Overhaul`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Datapack Villager Trades`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): ``Level#random` field now protected`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Data Component Initializers`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Item Instances and Stack Templates`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Serializer Records and Recipe Info`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Dye Component`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `World Clocks and Time Markers`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Splitting the Primary Level Data into Saved Data`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Even More Rendering Changes`
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md): `Minor Migrations`
+
+## Source and attribution
+
+The split primer pages in this GitBook are copied from the upstream primers in:
+
+- `ChampionAsh5357/neoforged-github`, branch `update/26.1`
+
+For attribution and license notes, see:
+
+- [Source And Attribution](source-and-attribution.md)

src/SUMMARY.md

@@ -0,0 +1,17 @@
+# Summary
+
+- [1.21.1 to 26.1 NeoForge Porting Guide](README.md)
+- [Direct Port Guide](direct-port-guide.md)
+- [Repeatedly Changing Systems](repeatedly-changing-systems.md)
+- [Source And Attribution](source-and-attribution.md)
+- [Detailed Primers](detailed-primers/README.md)
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md)
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md)
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md)
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md)
+- [1.21.7 -> 1.21.8](detailed-primers/1.21.8-from-1.21.7.md)
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md)
+- [1.21.9 -> 1.21.10](detailed-primers/1.21.10-from-1.21.9.md)
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)

src/detailed-primers/1.21.10-from-1.21.9.md

@@ -0,0 +1,27 @@
+# Minecraft 1.21.9 -> 1.21.10 Mod Migration Primer
+
+This is a high level, non-exhaustive overview on how to migrate your mod from 1.21.9 to 1.21.10. This does not look at any specific mod loader, just the changes to the vanilla classes. All provided names use the official mojang mappings.
+
+This primer is licensed under the [Creative Commons Attribution 4.0 International](http://creativecommons.org/licenses/by/4.0/), so feel free to use it as a reference and leave a link so that other readers can consume the primer.
+
+If there's any incorrect or missing information, please file an issue on this repository or ping @ChampionAsh5357 in the Neoforged Discord server.
+
+Thank you to:
+
+- @melanx for a typo
+
+## Pack Changes
+
+There are a number of user-facing changes that are part of vanilla which are not discussed below that may be relevant to modders. You can find a list of them on [Misode's version changelog](https://misode.github.io/versions/?id=1.21.10&tab=changelog).
+
+## Minor Migrations
+
+The following is a list of useful or interesting additions, changes, and removals that do not deserve their own section in the primer.
+
+### List of Additions
+
+- `net.minecraft.world.entity.decoration.HangingEntity#getPopBox` - Returns the bounding box indicating where the entity will pop off if colliding.
+
+### List of Changes
+
+`net.minecraft.world.level.block.state.BlockBehaviour#entityInside` now takes in a `boolean` indicating whether the entity is intersecting or inside the block

src/detailed-primers/1.21.7-from-1.21.6.md

@@ -0,0 +1,38 @@
+# Minecraft 1.21.6 -> 1.21.7 Mod Migration Primer
+
+This is a high level, non-exhaustive overview on how to migrate your mod from 1.21.6 to 1.21.7. This does not look at any specific mod loader, just the changes to the vanilla classes. All provided names use the official mojang mappings.
+
+This primer is licensed under the [Creative Commons Attribution 4.0 International](http://creativecommons.org/licenses/by/4.0/), so feel free to use it as a reference and leave a link so that other readers can consume the primer.
+
+If there's any incorrect or missing information, please file an issue on this repository or ping @ChampionAsh5357 in the Neoforged Discord server.
+
+## Pack Changes
+
+There are a number of user-facing changes that are part of vanilla which are not discussed below that may be relevant to modders. You can find a list of them on [Misode's version changelog](https://misode.github.io/versions/?id=1.21.7&tab=changelog).
+
+## Minor Migrations
+
+The following is a list of useful or interesting additions, changes, and removals that do not deserve their own section in the primer.
+
+### List of Additions
+
+- `com.mojang.blaze3d.opengl.DirectStateAccess#copyBufferSubData` - Copies all or part of one buffer object's data store to the data store of another buffer object.
+- `com.mojang.blaze3d.pipeline.BlendFunction#INVERT` - Inverts the blend factors of the RGB source and destination. Alpha uses the default one from source and zero from destination.
+- `com.mojang.blaze3d.systems.CommandEncoder#copyToBuffer` - Copies the data store of one buffer slice to another buffer slice.
+- `net.minecraft.Util#isAarch64` - Returns whether the OS architecture uses aarch64.
+- `net.minecraft.client.gui.GuiGraphics#textHighlight` - Adds a highlighted box around the provided bounds.
+- `net.minecraft.client.renderer.RenderPipelines#GUI_INVERT` - A render pipeline for drawing a gui element with inverted colors.
+- `net.minecraft.client.renderer.item.TrackingItemRenderState` - A render state that tracks the model sources being used to render the item stack.
+
+### List of Changes
+
+- `com.mojang.blaze3d.pipeline.RenderPipeline$Builder#withColorLogic` is now deprecated
+- `net.minecraft.client.gui.renderer.GuiRenderer#MIN_GUI_Z` is now private
+- `net.minecraft.client.gui.render.state.GuiItemRenderState` now takes in a `TrackingItemRenderState` instead of a `ItemStackRenderState`
+    - `itemStackRenderState` now returns a `TrackingItemRenderState`
+- `net.minecraft.client.renderer.RenderPipelines#GUI_TEXT_HIGHLIGHT` now uses the `ADDITIVE` blend function instead of the `OR_REVERSE` color logic
+- `net.minecraft.client.renderer.item.ItemStackRenderState#getModelIdentity` -> `TrackingItemRenderState#getModelIdentity`
+
+### List of Removals
+
+- `net.minecraft.client.renderer.item.ItemStackRenderState#clearModelIdentity`

src/detailed-primers/1.21.8-from-1.21.7.md

@@ -0,0 +1,19 @@
+# Minecraft 1.21.7 -> 1.21.8 Mod Migration Primer
+
+This is a high level, non-exhaustive overview on how to migrate your mod from 1.21.7 to 1.21.8. This does not look at any specific mod loader, just the changes to the vanilla classes. All provided names use the official mojang mappings.
+
+This primer is licensed under the [Creative Commons Attribution 4.0 International](http://creativecommons.org/licenses/by/4.0/), so feel free to use it as a reference and leave a link so that other readers can consume the primer.
+
+If there's any incorrect or missing information, please file an issue on this repository or ping @ChampionAsh5357 in the Neoforged Discord server.
+
+## Pack Changes
+
+There are a number of user-facing changes that are part of vanilla which are not discussed below that may be relevant to modders. You can find a list of them on [Misode's version changelog](https://misode.github.io/versions/?id=1.21.8&tab=changelog).
+
+## Minor Migrations
+
+The following is a list of useful or interesting additions, changes, and removals that do not deserve their own section in the primer.
+
+### List of Additions
+
+- `com.mojang.blaze3d.GraphicsWorkarounds` - A helper for working around issues with specific graphics hardware.

src/detailed-primers/README.md

@@ -0,0 +1,16 @@
+# Detailed Primers
+
+These chapters preserve the upstream primer content step by step so the direct guide does not lose version-specific detail.
+
+Read them in order:
+
+- [1.21.1 -> 1.21.2/3](1.21.2-from-1.21.1.md)
+- [1.21.2/3 -> 1.21.4](1.21.4-from-1.21.2-3.md)
+- [1.21.4 -> 1.21.5](1.21.5-from-1.21.4.md)
+- [1.21.5 -> 1.21.6](1.21.6-from-1.21.5.md)
+- [1.21.6 -> 1.21.7](1.21.7-from-1.21.6.md)
+- [1.21.7 -> 1.21.8](1.21.8-from-1.21.7.md)
+- [1.21.8 -> 1.21.9](1.21.9-from-1.21.8.md)
+- [1.21.9 -> 1.21.10](1.21.10-from-1.21.9.md)
+- [1.21.10 -> 1.21.11](1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](26.1-from-1.21.11.md)

src/repeatedly-changing-systems.md

@@ -0,0 +1,133 @@
+# 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 chapters:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md)
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md)
+- [1.21.6 -> 1.21.7](detailed-primers/1.21.7-from-1.21.6.md)
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md)
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)
+
+How to read them:
+
+- `1.21.2/3` changes GUI blits, shader JSON structure, and render-state assumptions.
+- `1.21.5` is the first large rendering infrastructure rewrite around `RenderPipeline`, `GpuTexture`, and render passes.
+- `1.21.6` changes GUI rendering flow again through prepare/render state separation.
+- `1.21.9` changes how features are submitted for rendering.
+- `1.21.11` changes samplers, render types, terrain split, and atlases.
+- `26.1` is the final authority for block/item rendering, materials, tint sources, fluid models, particle layers, and backend-facing rendering APIs.
+
+Practical rule:
+
+- Treat `26.1` as the final rendering target.
+- Keep `1.21.4` client items and `1.21.6` GUI flow as still-active requirements, not obsolete history.
+
+## Item models and item metadata
+
+Relevant chapters:
+
+- [1.21.2/3 -> 1.21.4](detailed-primers/1.21.4-from-1.21.2-3.md)
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md)
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)
+
+What sticks:
+
+- `1.21.4` client items are the baseline for item rendering data.
+- `1.21.5` removes more hardcoded item-class assumptions in favor of components and equipment data.
+- `1.21.9`, `1.21.11`, and `26.1` further 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.1` rendering and item-instance model.
+
+## Tags, registries, codecs, and validation
+
+Relevant chapters:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md)
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.5 -> 1.21.6](detailed-primers/1.21.6-from-1.21.5.md)
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)
+
+What sticks:
+
+- `1.21.2/3` is where `Holder` and `HolderSet` start affecting large parts of the codebase.
+- `1.21.5` changes tag access, parser behavior, codec-based reads and writes, and saved-data construction.
+- `1.21.6` changes tag provider building and nudges more code toward generic encoding and decoding.
+- `1.21.11` contributes rename churn that affects registry and identifier-facing code.
+- `26.1` finalizes 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.1` is the final target for validation and loot registration shape.
+
+## Data components
+
+Relevant chapters:
+
+- [1.21.1 -> 1.21.2/3](detailed-primers/1.21.2-from-1.21.1.md)
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)
+
+What sticks:
+
+- `1.21.2/3` introduces important component-facing migrations such as consumables and recipe-related data moves.
+- `1.21.5` expands component-centered behavior for tools, armor, weapons, and general data access.
+- `1.21.11` adds more component types.
+- `26.1` continues 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 chapters:
+
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)
+
+What sticks:
+
+- `1.21.5` moves saved data to `SavedDataType`.
+- `26.1` splits primary level data further into dedicated saved-data objects.
+
+Practical rule:
+
+- Do the `1.21.5` migration first, then revisit every level/world persistence assumption again in `26.1`.
+
+## Developer tooling, tests, debugging, and permissions
+
+Relevant chapters:
+
+- [1.21.4 -> 1.21.5](detailed-primers/1.21.5-from-1.21.4.md)
+- [1.21.8 -> 1.21.9](detailed-primers/1.21.9-from-1.21.8.md)
+- [1.21.10 -> 1.21.11](detailed-primers/1.21.11-from-1.21.10.md)
+- [1.21.11 -> 26.1](detailed-primers/26.1-from-1.21.11.md)
+
+What sticks:
+
+- `1.21.5` overhauls game tests.
+- `1.21.9` overhauls debugging and management-server shape.
+- `1.21.11` adds a permission overhaul and gizmo-focused visualization work.
+- `26.1` adds 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.

src/source-and-attribution.md

@@ -0,0 +1,41 @@
+# Source And Attribution
+
+This docs tree was assembled from the upstream primers in:
+
+- Repository: `https://github.com/ChampionAsh5357/neoforged-github`
+- Branch: `update/26.1`
+- Primer root: `primers/`
+
+## Coverage used for this compilation
+
+The compiled direct-port guide includes these upstream primer steps:
+
+- `1.21.1 -> 1.21.2/3`
+- `1.21.2/3 -> 1.21.4`
+- `1.21.4 -> 1.21.5`
+- `1.21.5 -> 1.21.6`
+- `1.21.6 -> 1.21.7`
+- `1.21.7 -> 1.21.8`
+- `1.21.8 -> 1.21.9`
+- `1.21.9 -> 1.21.10`
+- `1.21.10 -> 1.21.11`
+- `1.21.11 -> 26.1`
+
+## Attribution
+
+Per the upstream `primers/README.md`:
+
+- Primers for versions `1.12 - 1.15` were written by `@williewillus`.
+- Primers for versions `1.16 - 1.17` were written by `@50ap5ud5`.
+- All newer primers, including the ones used here, were written by `@ChampionAsh5357`.
+
+## Licensing note
+
+The detailed primers copied into this docs tree remain under their upstream licenses and attribution requirements.
+
+For the exact license text and upstream breakdown, refer to:
+
+- `repo/primers/README.md`
+- `repo/primers/LICENSE-CHAMPIONASH5357`
+- `repo/primers/LICENSE-50AP5UD5`
+- `repo/primers/LICENSE-WILLIEWILLUS`