Updating Instructions

June 19, 2026 · View on GitHub

These are the usual steps for updating ViaFabricPlus to a new Minecraft version. If you're unsure about anything, feel free to ask in the ViaVersion Discord.

1. Update Dependencies

Update all upstream versions in gradle.properties. The main ones are:

  • minecraft_version
  • fabric_loader_version
  • fabric_api_version
  • supported_minecraft_versions (if needed)

Also update versions in the dependencies block of build.gradle.kts.

2. Update Core References

  • Update the NATIVE_VERSION field in ProtocolTranslator
  • Update protocol constants in ViaFabricPlusProtocol

3. Port the Code

  1. Decompile the Minecraft source with your preferred tool.
  2. Try to compile the mod and port the code until all fixes work again.

4. Update Data Diffs

Set updating_minecraft = true.

Run gradle test to automatically update various data JSONs in the assets.

Manually check the following files:

  • entity-dimensions.json

Set updating_minecraft = false.

5. Validate Mixins

Check if all mixins in the injection package still apply correctly. Critical ones include:

  • MixinClientLevel#tickEntity
  • MixinClientLevel#tickPassenger
  • MixinPlayer#changeSpeedCalculation

6. Diff Game Code

Diff the new Minecraft source against the previous version (e.g. using git). Implement all relevant changes for ViaFabricPlus. These usually include:

  • Logic changes (e.g. if (a && b) → if (b || a))
  • Movement changes (e.g. player.yaw → player.headYaw)
  • Networking changes (e.g. new packet or changed structure)
  • Visual changes (e.g. animations)

Note: ViaVersion already covers most server-side gameplay changes. ViaFabricPlus usually handles client-side and deeper integration fixes.

See Contributing Guidelines for details on which fixes matter.

7. Focus Areas in Game Code

Usually important (mojang mappings):

  • net.minecraft
  • net.minecraft.client
    • gui
    • multiplayer
    • player
  • net.minecraft.util
  • net.minecraft.world
    • entity
    • inventory
    • item
    • level (including block)

Usually safe to skip:

  • com.mojang
  • net.minecraft.advancements
  • net.minecraft.commands
  • net.minecraft.data
  • net.minecraft.gametest
  • net.minecraft.realms
  • net.minecraft.recipebook
  • net.minecraft.references
  • net.minecraft.resources
  • net.minecraft.server
  • net.minecraft.sounds
  • net.minecraft.stats
  • net.minecraft.tags

8. Verify Upstream

Check the ViaVersion/upstream protocol implementation.

  • Report upstream issues when needed
  • If an issue can't be fixed upstream without excessive work, add a client-side workaround in ViaFabricPlus

9. Final Steps

  1. Run the game and verify all GUIs and visuals.

  2. Clean up your code and ensure it's readable.

    • Client-side fixes are sorted by protocol version, newest at the top.

  3. Open a pull request and wait for review.

Project Structure

  • Every change to the game is called a feature.
  • Features live under both features/ and injection/mixin/features/.
  • Loading is handled by static blocks and a dummy init function in FeaturesLoading.

Build Files

  • Common build logic comes from the BaseProject Gradle convention plugin.
  • The root project includes all submodules (including optional ones like viafabricplus-visuals).
  • Be careful not to introduce unintended dependencies on optional submodules.

Release Process

  1. Set project_version in gradle.properties to the new release version.

  2. Pin version IDs of configureVVDependencies in build.gradle.kts.

  3. Commit with the message:

    ViaFabricPlus <version>

Versioning Scheme

  • Major → Breaking or fundamental refactors (e.g. new mappings, full rewrite)
  • Minor → Port to a new game version or major feature addition
  • Patch → Bug fixes or small features

After releasing:

  • Switch back to -SNAPSHOT version
  • Unpin configureVVDependencies

Make a version bump commit:

Start <release version> cycle

Git Branches

  • ver/<version> → all new changes are merged into the branch of the currently active Minecraft version
  • Keep one branch per Minecraft version (e.g. ver/1.21.5)

See ViaFabricPlus-archive for older branches.