mirror of
https://github.com/VolmitSoftware/Iris.git
synced 2026-08-27 04:37:47 +00:00
Brian Neumann-Fopiano
169 lines
10 KiB
Markdown
169 lines
10 KiB
Markdown
# Minecraft Version Bump Checklist
|
|
|
|
`gradle.properties` `minecraftVersion` is the single source of truth for the target Minecraft
|
|
version. Most build outputs derive from it. This document lists every edit required to move Iris
|
|
to a new Minecraft version, in order.
|
|
|
|
## Source of truth
|
|
|
|
`gradle.properties`:
|
|
|
|
- `minecraftVersion` — target MC version (e.g. `26.2`). Drives the Bukkit plugin `api-version`,
|
|
`BuildConstants.MINECRAFT_VERSION`, the `com.mojang:minecraft` coordinate, all mod-metadata
|
|
minecraft ranges, and every dist/jar artifact name.
|
|
- `fabricLoaderVersion` — Fabric Loader version.
|
|
- `forgeVersion` — Forge version (`<mc>-<forge>`).
|
|
- `neoForgeVersion` — NeoForge version.
|
|
- `irisVersion` — bump the trailing `-<mc>` suffix to match (e.g. `4.0.0-26.2` -> `4.0.0-27.0`).
|
|
|
|
## Ordered steps
|
|
|
|
1. Edit `gradle.properties`: update `minecraftVersion`, `fabricLoaderVersion`, `forgeVersion`,
|
|
`neoForgeVersion`, and the `irisVersion` suffix.
|
|
|
|
2. Edit `gradle/libs.versions.toml`:
|
|
- `spigot` — the Spigot/Paper API pin used to compile against (`<mc>-R0.1-SNAPSHOT`).
|
|
- `fabricApi-*` — the ten Fabric API module versions, if the new MC requires different
|
|
Fabric API builds. Each module is versioned independently (`<version>+<build-hash>`).
|
|
The ten are `base`, `registrySync`, `resourceLoader`, `lifecycleEvents`, `commandApi`,
|
|
`eventsInteraction`, `networking`, `rendering`, `keyMapping`, `permission`. Every one of them
|
|
is bundled jar-in-jar and must be declared in `fabric.mod.json` `jars` — see step 7.
|
|
|
|
3. Edit `core/src/main/java/art/arcane/iris/core/nms/datapack/DataVersion.java` (manual, structural):
|
|
- Append a new enum constant `V<major>_<minor>("<mc>", <packFormat>, <DataFixer>::new)`.
|
|
- `packFormat` comes from https://minecraft.wiki/w/Pack_format.
|
|
- `getLatest()` returns the last enum constant, so append; do not reorder.
|
|
- Add a matching `IDataFixer` implementation under `core/src/main/java/art/arcane/iris/core/nms/datapack/`
|
|
if the datapack format changed.
|
|
|
|
4. Register the new Bukkit NMS binding module:
|
|
- `settings.gradle` — add `include(':adapters:bukkit:nms:v<major>_<minor>_R<rev>')`.
|
|
- `build.gradle` — add the binding to the `nmsBindings` map:
|
|
`v<major>_<minor>_R<rev>: '<spigot-nms-build-version>'` (e.g. `'26.2.build.25-alpha'`).
|
|
- Create the binding sources under `adapters/bukkit/nms/v<major>_<minor>_R<rev>/`.
|
|
|
|
5. Update loader version-range metadata (manual floors/ranges only; the `minecraft` ranges are
|
|
templated from `minecraftVersion` and need no edit):
|
|
- `adapters/fabric/src/main/resources/fabric.mod.json` — `minecraft` is `~${minecraftVersion}`
|
|
(auto). Update the `fabricloader` floor (currently `>=0.19.3`) if the loader minimum changes,
|
|
and the `jars` list if the bundled Fabric API modules change.
|
|
- `adapters/forge/src/main/resources/META-INF/mods.toml` — `minecraft` versionRange is
|
|
`[${minecraftVersion}]` (auto). Update `loaderVersion` (currently `[65,)`) and the `forge`
|
|
dependency versionRange (also `[65,)`) for the new Forge line. Both are hand-maintained.
|
|
- `adapters/neoforge/src/main/resources/META-INF/neoforge.mods.toml` — `minecraft` versionRange
|
|
is `[${minecraftVersion}]` (auto). `loaderVersion` (currently `[3,)`) is the javafml
|
|
specification version, not the NeoForge version, and rarely moves. The `neoforge` dependency
|
|
`versionRange` is **hardcoded** (currently `[26.2,)`) and is *not* templated from
|
|
`minecraftVersion` — hand-edit it on every bump or the mod will load on the wrong NeoForge
|
|
line.
|
|
|
|
6. Re-verify the mapping-coupled files. Six files name Mojang-mapped classes, fields, and method
|
|
descriptors directly. Nothing templates them, nothing fails fast at build time if a name moved,
|
|
and a stale entry surfaces as a silent no-op or a load-time crash. Check every one against the
|
|
new MC jar.
|
|
|
|
Access widener (Fabric) — `accessWidener v2 official`, so the names are Mojang-mapped:
|
|
|
|
- `adapters/fabric/src/main/resources/irisworldgen.accesswidener`
|
|
- `MinecraftServer.levels` `Ljava/util/Map;`
|
|
- `MinecraftServer.executor` `Ljava/util/concurrent/Executor;`
|
|
- `MinecraftServer.storageSource` `Lnet/minecraft/world/level/storage/LevelStorageSource$LevelStorageAccess;`
|
|
- `PackRepository.sources` `Ljava/util/Set;` (accessible **and** mutable)
|
|
|
|
Verify: each field still exists with that exact descriptor. Loom fails the build on an
|
|
unresolvable AW entry, so a rename shows up as an AW error — read it, do not delete the line.
|
|
|
|
Access transformers (Forge and NeoForge) — must stay in sync with each other and with the AW:
|
|
|
|
- `adapters/forge/src/main/resources/META-INF/accesstransformer.cfg`
|
|
- `adapters/neoforge/src/main/resources/META-INF/accesstransformer.cfg`
|
|
- both: `public net.minecraft.server.MinecraftServer levels` / `executor` / `storageSource`
|
|
|
|
Verify: the three ATs match the first three AW entries. Note the ATs have no `PackRepository`
|
|
entry — Forge/NeoForge reach the pack sources through their own hooks, so do not add one
|
|
without a reason. Wired via `minecraft { accessTransformer.from(...) }` (Forge) and
|
|
`neoForge { accessTransformers.from(...) }` (NeoForge).
|
|
|
|
Mixin configs — three JSONs, eight mixin classes, all targeting Mojang-mapped members:
|
|
|
|
- `adapters/fabric/src/main/resources/irisworldgen.mixins.json`
|
|
(package `art.arcane.iris.fabric.mixin`, `compatibilityLevel` `JAVA_25`, Fabric only)
|
|
- `BlockItemMixin` -> `BlockItem.placeBlock`, `@At("RETURN")`
|
|
- `BlockMixin` -> `Block.getDrops(...)` with a **full descriptor**
|
|
(`BlockState, ServerLevel, BlockPos, BlockEntity, Entity, ItemInstance`) — the highest-churn
|
|
entry in the repo; the parameter list changes across MC versions
|
|
- `PackRepositoryMixin` -> `PackRepository.<init>`, `@At("RETURN")`
|
|
- `adapters/modded-common/src/main/resources/irisworldgen.entity.mixins.json`
|
|
(package `art.arcane.iris.modded.mixin`, `compatibilityLevel` `JAVA_21`, all three loaders)
|
|
- `EntityPersistenceMixin` -> `Entity.shouldBeSaved`
|
|
- `LivingEntityLootMixin` -> `LivingEntity.dropFromLootTable(ServerLevel, DamageSource, boolean)`
|
|
— full descriptor
|
|
- `MobAwarenessMixin` -> `Mob.serverAiStep`, injecting at a **field target**
|
|
(`Lnet/minecraft/world/entity/Mob;noActionTime:I`) — verify the field, not just the method
|
|
- `adapters/modded-common/src/main/resources/irisworldgen.client.mixins.json`
|
|
(package `art.arcane.iris.client.mixin`, client-only)
|
|
- `IrisWorldOpenFlowsMixin` -> `WorldOpenFlows.confirmWorldCreation` and
|
|
`WorldOpenFlows.openWorldCheckWorldStemCompatibility`
|
|
- `IrisWorldTypeEntryMixin` -> `WorldCreationUiState.WorldTypeEntry.describePreset`, plus a
|
|
`@Shadow` member — shadows break silently if the field is renamed
|
|
|
|
The client mixin *config* lives in `modded-common/src/main/resources` but the classes live in
|
|
`adapters/client-common/src/main/java/art/arcane/iris/client/mixin/`; the modded mixin classes
|
|
live in `adapters/modded-common/src/main/java/art/arcane/iris/modded/mixin/`. All three
|
|
adapters add both shared source dirs, so one edit hits every loader.
|
|
|
|
Registration differs per loader and each place must list the same configs:
|
|
- Fabric — `fabric.mod.json` `mixins` (all three; the client one gated on
|
|
`"environment": "client"`).
|
|
- NeoForge — `[[mixins]]` blocks in `neoforge.mods.toml` (entity + client).
|
|
- Forge — no toml entry. The jar manifest attribute `MixinConfigs` in
|
|
`adapters/forge/build.gradle` plus `--mixin.config` args on the `runClient`/`runServer`
|
|
configurations (entity + client). Adding a mixin config on Forge means editing the manifest
|
|
attribute *and* the run args.
|
|
|
|
`injectors.defaultRequire` is `1` in all three configs, so a mixin that no longer applies
|
|
fails the run instead of degrading quietly. Treat any "mixin apply failed" line as a bump
|
|
blocker, and run both `runClient` and `runServer` per loader — client-only mixins are not
|
|
exercised by a server run.
|
|
|
|
7. Reconcile the Fabric jar-in-jar list. `adapters/fabric/build.gradle` adds every Fabric API
|
|
module to the `jij` configuration, which the `shadowJar` copies into `META-INF/jars` with the
|
|
version stripped from the filename. The `jij` configuration is `transitive = false`, so the
|
|
bundled set is exactly the declared set, and `fabric.mod.json` `jars` must list exactly those
|
|
filenames. After changing the module list, confirm the jar agrees:
|
|
|
|
```
|
|
unzip -l "dist/Iris v<version> [Fabric] <mc>+<loader>.jar" | grep META-INF/jars
|
|
```
|
|
|
|
An entry in `jars` with no matching nested jar makes the loader refuse the mod; a nested jar
|
|
missing from `jars` is dead weight the loader never mounts.
|
|
|
|
8. Build and verify:
|
|
- `./gradlew :core:check`
|
|
- `./gradlew buildBukkit`
|
|
- `./gradlew buildFabric`
|
|
- `./gradlew buildForge`
|
|
- `./gradlew buildNeoforge`
|
|
|
|
## Derived automatically (do not hand-edit on a version bump)
|
|
|
|
- Bukkit plugin `api-version` — `adapters/bukkit/plugin/build.gradle` reads `minecraftVersion`.
|
|
- `BuildConstants.MINECRAFT_VERSION` — stamped by the `generateTemplates` task in
|
|
`core/build.gradle` from `minecraftVersion`; consumed by `Tasks.supportedVersions`.
|
|
- Mod-metadata `minecraft` version ranges — templated from `minecraftVersion` at `processResources`.
|
|
- Dist/jar artifact names and the `com.mojang:minecraft` coordinate — composed from
|
|
`minecraftVersion` in the build scripts.
|
|
|
|
## Notes
|
|
|
|
- `build.gradle`, the adapter `build.gradle` files, and `settings.gradle` carry `.getOrElse('26.2')`
|
|
defensive defaults for the version properties. `gradle.properties` always overrides them, so a
|
|
bump does not require touching those fallbacks; refresh them only if the checked-in default should
|
|
track the current release.
|
|
- The Java literal `"26.2"` intentionally remains in `DataVersion.java` (structural enum constant),
|
|
`core/src/test/java/art/arcane/iris/core/nms/MinecraftVersionTest.java`, and
|
|
`core/src/test/java/art/arcane/iris/core/lifecycle/PaperLibBootstrapTest.java`. The test files use
|
|
MC version strings as parser fixtures, not as a version source; update them only when the version
|
|
string formats they exercise change.
|