5.4.2 Release

Fixes #4596

.github/FUNDING.yml

@@ -1,2 +1,3 @@
 github: kennytv
 patreon: kennytv
+custom: ['https://florianmichael.de/donate']

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -21,10 +21,11 @@ body:
 
   - type: textarea
     attributes:
-      label: Console Error
+      label: Server/Client Error
       description: |
         If you encounter warnings/errors in your console, **paste them with https://mclo.gs/ and put the paste link here**.
         If the error is small/less than 10 lines, you may put it directly into this field.
+        **Important**: If you are kicked for `Network Protocol Error` or an encoder/decoder exception, please click the `Open Report Directory` button on your client and paste the newest disconnect file contents.
       value: |
         ```
         Put the mclo.gs link or text here.
@@ -40,7 +41,7 @@ body:
         Describe the unexpected behavior.
         If you want to attach screenshots, use the comment field at the bottom of the page.
       placeholder: |
-        Example: "Placing signs on 1.13.2 causes text to disappear."
+        Example: "Placing signs on 1.21.3 causes text to disappear."
     validations:
       required: true
 
@@ -51,7 +52,7 @@ body:
         List the steps on how we can reproduce the issue. Make sure we can easily understand what you mean with each step.
       placeholder: |
         Example:
-        1. Login with a 1.13.2 client
+        1. Login with a 1.21.3 client
         2. Place a sign
         3. The sign text is displayed wrong
     validations:

.github/workflows/build.yml

@@ -1,6 +1,6 @@
 name: Java CI with Gradle
 
-on: [push, pull_request]
+on: [push, pull_request, workflow_dispatch]
 
 jobs:
   build:
@@ -12,8 +12,10 @@ jobs:
     steps:
     - name: Checkout Repository
       uses: actions/checkout@v4
-    - name: Validate Gradle Wrapper
-      uses: gradle/actions/wrapper-validation@v4
+      with:
+        persist-credentials: false
+    - name: Set up Gradle
+      uses: gradle/actions/setup-gradle@v4
     - name: Set up JDK 17
       uses: actions/setup-java@v4
       with:
@@ -22,3 +24,10 @@ jobs:
         check-latest: true
     - name: Build with Gradle
       run: ./gradlew build
+    - name: Upload Artifacts to GitHub
+      # Only upload on the preview repository as there is no CI job for it.
+      if: ${{ github.repository == 'ViaVersion/ViaVersionDev' && github.ref_name == 'preview' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: Artifacts
+        path: build/libs/

.github/workflows/publish.yml

@@ -4,6 +4,7 @@ on:
     branches:
       - master
       - dev
+  workflow_dispatch:
 
 jobs:
   publish:
@@ -12,16 +13,25 @@ jobs:
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v4
-      - name: Validate Gradle Wrapper
-        uses: gradle/actions/wrapper-validation@v4
+        with:
+          persist-credentials: false
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
       - name: Set up JDK 17
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: 17
           check-latest: true
-      - name: Publish
+      - name: Build
+        run: ./gradlew build
+      - name: Publish to Hangar
         env:
           HANGAR_TOKEN: ${{ secrets.HANGAR_TOKEN }}
+        run: ./gradlew publishAllPublicationsToHangar --stacktrace
+        continue-on-error: true
+      - name: Publish to Modrinth
+        env:
           MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}
-        run: ./gradlew build modrinth publishAllPublicationsToHangar --stacktrace
+        run: ./gradlew modrinth --stacktrace
+        continue-on-error: true

.github/workflows/update-gradle-wrapper.yml

@@ -10,5 +10,7 @@ jobs:
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       - name: Update Gradle Wrapper
         uses: gradle-update/update-gradle-wrapper-action@v2

README.md

@@ -18,7 +18,14 @@ Supported Versions:
 
 ![Table (https://i.imgur.com/zrQTcf0.png)](https://i.imgur.com/zrQTcf0.png)
 
-**User Docs:** https://docs.viaversion.com/display/VIAVERSION/
+**User Docs:** https://docs.viaversion.com
+
+Snapshot support
+--------
+**ViaVersion will only be released a few days *after* a Minecraft update** unless the protocol changes of the update were trivial. If you want early-access, usually days or even weeks before the final release, you can subscribe to either:
+- [GitHub Sponsors](https://github.com/sponsors/kennytv/sponsorships?sponsor=kennytv&tier_id=385613&preview=false) (preferred option. Use the `/verify` command on this Discord after), or alternatively
+- [Patreon](https://www.patreon.com/kennytv/membership) (see the highest tier and make sure to link Patreon to your Discord account under Settings->Connections)
+  This also includes access to a private repository with the code, which will be pushed to the public repository after the given delay on a Minecraft update.
 
 Releases/Dev Builds
 --------
@@ -91,8 +98,7 @@ Resources
 
 - **[Via Mappings Generator](https://github.com/ViaVersion/Mappings)**
 - **[Mojang mappings](https://minecraft.wiki/w/Obfuscation_map)** (Thank you, Mojang, very cool)
-- **[wiki.vg](https://wiki.vg)** (Used for historic information regarding packet structure, we also contribute back)
-- **[Burger](https://github.com/Pokechu22/Burger)** (See [PAaaS](https://github.com/Matsv/Paaas))
+- Previously: **[Burger](https://github.com/Pokechu22/Burger)** (see [PAaaS](https://github.com/Matsv/Paaas)) and **wiki.vg**
 
 License
 --------

SECURITY.md

@@ -0,0 +1,10 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a **security vulnerability**, please **do not** open a public issue. Instead, use one of the following **confidential contact methods**:
+
+* **Email:** [security@viaversion.com](mailto:security@viaversion.com)
+* **Discord:** Join our [Discord server](https://discord.gg/viaversion) and visit the [#exploit-report](https://discord.com/channels/316206679014244363/1388847764137316485) channel for further instructions.
+
+If your issue is **not security-related** (e.g., bug reports, feature requests, or usage questions), please use the [GitHub Issues page](https://github.com/ViaVersion/ViaVersion/issues) or contact us via the [Discord server](https://discord.gg/viaversion).

api/build.gradle.kts

@@ -29,7 +29,11 @@ dependencies {
     api(libs.snakeYaml)
 
     compileOnlyApi(libs.netty)
-    compileOnlyApi(libs.guava)
+    compileOnlyApi(libs.guava) {
+        exclude("com.google.errorprone", "error_prone_annotations")
+        exclude("org.jspecify", "jspecify")
+        exclude("com.google.j2objc", "j2objc-annotations")
+    }
     compileOnlyApi(libs.checkerQual)
 }
 

api/src/main/java-templates/com/viaversion/viaversion/util/VersionInfo.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/Via.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/ViaAPI.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -114,7 +114,8 @@ public interface ViaAPI<T> {
     ProtocolVersion getPlayerProtocolVersion(UUID uuid);
 
     /**
-     * Returns whether Via injected into this player connection.
+     * Returns whether Via injected into this player connection. Note that this method may not work on
+     * clientside implementations and is generally not recommended to be used. Use {@link ConnectionManager} instead.
      *
      * @param uuid uuid of the player
      * @return whether Via has a cached a UserConnection for this player
@@ -122,7 +123,8 @@ public interface ViaAPI<T> {
     boolean isInjected(UUID uuid);
 
     /**
-     * Returns the Via injected UserConnection if present.
+     * Returns whether Via injected into this player connection. Note that this method may not work on
+     * clientside implementations and is generally not recommended to be used. Use {@link ConnectionManager} instead.
      *
      * @param uuid uuid of the player
      * @return user connection if present

api/src/main/java/com/viaversion/viaversion/api/ViaManager.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/command/ViaCommandSender.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/command/ViaSubCommand.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -66,7 +66,7 @@ public interface ViaSubCommand {
      *
      * @param sender Command sender
      * @param args   Arguments
-     * @return commands executed succesfully if false, show usage
+     * @return commands executed successfully if false, show usage
      */
     boolean execute(ViaCommandSender sender, String[] args);
 

api/src/main/java/com/viaversion/viaversion/api/command/ViaVersionCommand.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -30,7 +30,7 @@ public interface ViaVersionCommand {
      * Register your own subcommand inside ViaVersion
      *
      * @param command Your own SubCommand instance to handle it.
-     * @throws IllegalArgumentException throws an exception when the subcommand already exists or if it's not valid, example: spacee
+     * @throws IllegalArgumentException throws an exception when the subcommand already exists or if it's not valid, example: space
      */
     void registerSubCommand(ViaSubCommand command);
 

api/src/main/java/com/viaversion/viaversion/api/configuration/Config.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/configuration/ConfigurationProvider.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/configuration/ViaVersionConfig.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -233,13 +233,6 @@ public interface ViaVersionConfig extends Config {
      */
     boolean isChunkBorderFix();
 
-    /**
-     * Should we fix nbt array's in json chat messages for 1.12 clients
-     *
-     * @return true if enabled
-     */
-    boolean is1_12NBTArrayFix();
-
     /**
      * Should we make team colours based on the last colour in team prefix
      *
@@ -285,6 +278,13 @@ public interface ViaVersionConfig extends Config {
      */
     boolean isSuppressConversionWarnings();
 
+    /**
+     * Should we hide errors that occur when trying to convert text components?
+     *
+     * @return true if enabled
+     */
+    boolean isSuppressTextComponentConversionWarnings();
+
     /**
      * Should we disable the 1.13 auto-complete feature to stop spam kicks? (for any server lower than 1.13)
      *
@@ -478,4 +478,12 @@ public interface ViaVersionConfig extends Config {
      * @return true if enabled
      */
     boolean fix1_21PlacementRotation();
+
+    /**
+     * If enabled, cancel swing packets sent while having an inventory opened on 1.15.2 and below servers.
+     * This can cause false positives with anti-cheat plugins.
+     *
+     * @return true if enabled
+     */
+    boolean cancelSwingInInventory();
 }

api/src/main/java/com/viaversion/viaversion/api/connection/ConnectionManager.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -28,51 +28,81 @@ import java.util.UUID;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
- * Handles injected UserConnections
+ * Handles injected UserConnections.
+ * Check {@link UserConnection#isServerSide()} and {@link UserConnection#isClientSide()} to determine the connection type.
  */
 public interface ConnectionManager {
 
     /**
-     * Returns if Via injected into this player connection.
+     * Returns if Via has injected. See above for the connection types.
      *
-     * @param playerId player uuid
+     * @param uuid player uuid
      * @return true if the player is handled by Via
      */
-    boolean isClientConnected(UUID playerId);
+    boolean hasServerConnection(UUID uuid);
 
-    /**
-     * Frontend connections will have the UUID stored. Override this if your platform isn't always frontend.
-     * UUIDs can't be duplicate between frontend connections.
-     *
-     * @return true if the user is a frontend connection
-     */
-    default boolean isFrontEnd(UserConnection connection) {
-        return !connection.isClientSide();
+    @Deprecated
+    default boolean isClientConnected(UUID uuid) {
+        return hasServerConnection(uuid);
     }
 
     /**
-     * Returns the frontend UserConnection from the player connected to this proxy server
-     * Returns null when there isn't a server or connection was not found
-     * When ViaVersion is reloaded, this method may not return some players.
-     * <p>
-     * Note that connections are removed as soon as their channel is closed,
-     * so avoid using this method during player quits for example.
+     * Returns if Via has injected. See above for the connection types.
      *
-     * @return frontend UserConnection of the player connected to this proxy server
+     * @param uuid player uuid
+     * @return true if the player is handled by Via
      */
-    @Nullable UserConnection getConnectedClient(UUID clientIdentifier);
+    boolean hasClientConnection(UUID uuid);
 
     /**
-     * Returns the UUID from the frontend connection to this proxy server
-     * Returns null when there isn't a server or this connection isn't frontend, or it doesn't have an id
+     * Returns the server UserConnection. See above for the connection types.
      * When ViaVersion is reloaded, this method may not return some players.
      * <p>
      * Note that connections are removed as soon as their channel is closed,
      * so avoid using this method during player quits for example.
      *
-     * @return UUID of the frontend connection to this proxy server
+     * @return server UserConnection of the player or null
      */
-    @Nullable UUID getConnectedClientId(UserConnection connection);
+    @Nullable
+    UserConnection getServerConnection(UUID uuid);
+
+    @Deprecated
+    @Nullable default UserConnection getConnectedClient(UUID uuid) {
+        return getServerConnection(uuid);
+    }
+
+    /**
+     * Returns the client UserConnection. See above for the connection types.
+     * When ViaVersion is reloaded, this method may not return some players.
+     * <p>
+     * Note that connections are removed as soon as their channel is closed,
+     * so avoid using this method during player quits for example.
+     *
+     * @return client UserConnection of the player or null
+     */
+    @Nullable
+    UserConnection getClientConnection(UUID uuid);
+
+    /**
+     * Returns a map containing the UUIDs and server UserConnections
+     * When ViaVersion is reloaded, this method may not return some players.
+     *
+     * @return map containing the UUIDs and frontend UserConnections
+     */
+    Map<UUID, UserConnection> getServerConnections();
+
+    @Deprecated
+    default Map<UUID, UserConnection> getConnectedClients() {
+        return getServerConnections();
+    }
+
+    /**
+     * Returns a map containing the UUIDs and client UserConnections
+     * When ViaVersion is reloaded, this method may not return some players.
+     *
+     * @return map containing the UUIDs and client UserConnections
+     */
+    Map<UUID, UserConnection> getClientConnections();
 
     /**
      * Returns all UserConnections which are registered
@@ -84,15 +114,6 @@ public interface ConnectionManager {
      */
     Set<UserConnection> getConnections();
 
-    /**
-     * Returns a map containing the UUIDs and frontend UserConnections from players connected to this proxy server
-     * Returns empty list when there isn't a server
-     * When ViaVersion is reloaded, this method may not return some players.
-     *
-     * @return map containing the UUIDs and frontend UserConnections from players connected to this proxy server
-     */
-    Map<UUID, UserConnection> getConnectedClients();
-
     void onLoginSuccess(UserConnection connection);
 
     void onDisconnect(UserConnection connection);

api/src/main/java/com/viaversion/viaversion/api/connection/ProtocolInfo.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -142,4 +142,4 @@ public interface ProtocolInfo {
     ProtocolPipeline getPipeline();
 
     void setPipeline(ProtocolPipeline pipeline);
-}
+}

api/src/main/java/com/viaversion/viaversion/api/connection/StorableObject.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -30,15 +30,6 @@ package com.viaversion.viaversion.api.connection;
  */
 public interface StorableObject {
 
-    /**
-     * Returns whether the object should be uncached on a server switch.
-     *
-     * @return whether the object should be uncached on a server switch
-     */
-    default boolean clearOnServerSwitch() {
-        return true;
-    }
-
     default void onRemove() {
     }
 }

api/src/main/java/com/viaversion/viaversion/api/connection/StoredObject.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/connection/UserConnection.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -24,6 +24,7 @@ package com.viaversion.viaversion.api.connection;
 
 import com.viaversion.viaversion.api.configuration.ViaVersionConfig;
 import com.viaversion.viaversion.api.data.entity.EntityTracker;
+import com.viaversion.viaversion.api.data.item.ItemHasher;
 import com.viaversion.viaversion.api.minecraft.ClientWorld;
 import com.viaversion.viaversion.api.protocol.Protocol;
 import com.viaversion.viaversion.api.protocol.packet.PacketTracker;
@@ -99,6 +100,23 @@ public interface UserConnection {
      */
     void addEntityTracker(Class<? extends Protocol> protocolClass, EntityTracker tracker);
 
+    /**
+     * Adds an item hasher to the user connection.
+     *
+     * @param protocolClass protocol class
+     * @param itemHasher   item hasher
+     */
+    void addItemHasher(Class<? extends Protocol> protocolClass, ItemHasher itemHasher);
+
+    /**
+     * Returns the item hasher by the given protocol class if present.
+     *
+     * @param protocolClass protocol class
+     * @param <T>           item hasher type
+     * @return item hasher if present
+     */
+    @Nullable <T extends ItemHasher> T getItemHasher(Class<? extends Protocol> protocolClass);
+
     /**
      * Returns the client world by the given protocol class if present.
      *
@@ -121,17 +139,7 @@ public interface UserConnection {
     /**
      * Clear stored objects, entity trackers and client worlds.
      */
-    default void clearStoredObjects() {
-        clearStoredObjects(false);
-    }
-
-    /**
-     * Clear stored objects, entity trackers and client worlds.
-     * If cleared for a proxy server switch, some stored objects and tracker data will be retained.
-     *
-     * @param isServerSwitch whether the clear is due to a server switch
-     */
-    void clearStoredObjects(boolean isServerSwitch);
+    void clearStoredObjects();
 
     /**
      * Sends a raw packet to the connection on the current thread.
@@ -319,23 +327,35 @@ public interface UserConnection {
     void setPendingDisconnect(boolean pendingDisconnect);
 
     /**
-     * Returns whether this is a client-side connection.
-     * This is a mod integrated into the client itself, or for example a backend Velocity connection.
+     * Returns whether this is a backend connection.
+     * This is a mod integrated into the client, or for example a backend Velocity connection.
      *
-     * @return whether this is a client-side connection
+     * @return whether this is a backend connection
      */
     boolean isClientSide();
 
+    /**
+     * Returns whether this is a frontend connection.
+     * This is a plugin integrated into the server, or for example a frontend Velocity connection.
+     *
+     * @return whether this is a frontend connection
+     */
+    default boolean isServerSide() {
+        return !isClientSide();
+    }
+
     /**
      * Returns whether {@link ViaVersionConfig#blockedProtocolVersions()} should be checked for this connection.
      *
      * @return whether blocked protocols should be applied
      */
-    boolean shouldApplyBlockProtocol();
+    default boolean shouldApplyBlockProtocol() {
+        return isServerSide();
+    }
 
     /**
      * Returns a newly generated uuid that will let a packet be passed through without
-     * transformig its contents if used together with {@link PacketWrapper#PASSTHROUGH_ID}.
+     * transforming its contents if used together with {@link PacketWrapper#PASSTHROUGH_ID}.
      *
      * @return generated passthrough token
      */

api/src/main/java/com/viaversion/viaversion/api/data/BiMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/BiMappingsBase.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/FullMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/FullMappingsBase.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -95,7 +95,7 @@ public class FullMappingsBase implements FullMappings {
     }
 
     @Override
-    public String mappedIdentifier(final int mappedId) {
+    public @Nullable String mappedIdentifier(final int mappedId) {
         if (mappedId < 0 || mappedId >= mappedIdToString.length) {
             return null;
         }

api/src/main/java/com/viaversion/viaversion/api/data/IdentityMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/Int2IntMapBiMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/Int2IntMapMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/IntArrayMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/MappingData.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/MappingDataBase.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -208,8 +208,8 @@ public class MappingDataBase implements MappingData {
     }
 
     @Override
-    public int getOldSoundId(final int i) {
-        return soundMappings.getNewIdOrDefault(i, 0);
+    public int getOldSoundId(final int id) {
+        return soundMappings.inverse().getNewIdOrDefault(id, 0);
     }
 
     @Override

api/src/main/java/com/viaversion/viaversion/api/data/MappingDataLoader.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/Mappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/ParticleMappings.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/entity/ClientEntityIdChangeListener.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/entity/DimensionData.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/data/entity/EntityTracker.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -123,6 +123,20 @@ public interface EntityTracker {
      */
     void setClientEntityId(int clientEntityId);
 
+    /**
+     * Returns whether the client player has the "insta build" ability, usually from creative mode.
+     *
+     * @return whether the client player can insta build
+     */
+    boolean canInstaBuild();
+
+    /**
+     * Sets whether the client player has the "insta build" ability, usually from creative mode.
+     *
+     * @param instaBuild whether the client player can insta build
+     */
+    void setInstaBuild(boolean instaBuild);
+
     /**
      * Returns the current world section height (block height / 16).
      * This is always 16 for sub 1.17 worlds.

api/src/main/java/com/viaversion/viaversion/api/data/entity/StoredEntityData.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -66,4 +66,4 @@ public interface StoredEntityData {
      * @param object object to store
      */
     void put(Object object);
-}
+}

api/src/main/java/com/viaversion/viaversion/api/data/entity/TrackedEntity.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -55,4 +55,4 @@ public interface TrackedEntity {
     boolean hasSentEntityData();
 
     void sentEntityData(boolean sentEntityData);
-}
+}

api/src/main/java/com/viaversion/viaversion/api/data/item/ItemHasher.java

@@ -0,0 +1,51 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.data.item;
+
+import java.util.List;
+
+/**
+ * Used for converting items to hashed items and caching them for later use during serverbound packets.
+ * <p>
+ * Most of this stays in the internal module given non-permanent, imperfect caching as well as missing converters.
+ */
+public interface ItemHasher {
+
+    /**
+     * Returns whether this connection is currently processing a clientbound player inventory packet.
+     * <p>
+     * Used for checking when it is necessary to track/process item data hashes.
+     *
+     * @return true if processing a clientbound inventory packet, false otherwise
+     */
+    boolean isProcessingClientboundInventoryPacket();
+
+    void setProcessingClientboundInventoryPacket(boolean processingClientboundInventoryPacket);
+
+    /**
+     * Sets the enchantment registry for this connection.
+     *
+     * @param enchantments list of enchantment identifiers
+     */
+    void setEnchantments(List<String> enchantments);
+}

api/src/main/java/com/viaversion/viaversion/api/debug/DebugHandler.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,7 +22,6 @@
  */
 package com.viaversion.viaversion.api.debug;
 
-import com.google.common.annotations.Beta;
 import com.viaversion.viaversion.api.Via;
 import com.viaversion.viaversion.api.protocol.packet.Direction;
 import com.viaversion.viaversion.api.protocol.packet.PacketType;
@@ -50,7 +49,6 @@ public interface DebugHandler {
      *
      * @param packetTypeName packet type name
      */
-    @Beta
     void addPacketTypeNameToLog(String packetTypeName);
 
     /**
@@ -59,7 +57,6 @@ public interface DebugHandler {
      *
      * @param packetType packet type
      */
-    @Beta
     void addPacketTypeToLog(PacketType packetType);
 
     /**
@@ -67,22 +64,44 @@ public interface DebugHandler {
      *
      * @param packetTypeName packet type name
      */
-    @Beta
     boolean removePacketTypeNameToLog(String packetTypeName);
 
     /**
      * Resets packet type filters.
      */
-    @Beta
     void clearPacketTypesToLog();
 
+    /**
+     * Sets whether packets should be logged before and after being transformed.
+     *
+     * @param logPacketTransform whether packets should be logged
+     */
+    default void setLogPacketTransform(boolean logPacketTransform) {
+        setLogPrePacketTransform(logPacketTransform);
+        setLogPostPacketTransform(logPacketTransform);
+    }
+
+    /**
+     * Returns whether packets should be logged before being transformed.
+     * Set to true by default.
+     *
+     * @return whether packets should be logged before being transformed
+     */
+    boolean logPrePacketTransform();
+
+    /**
+     * Sets whether packets should be logged before being transformed.
+     *
+     * @param logPrePacketTransform whether packets should be logged before being transformed
+     */
+    void setLogPrePacketTransform(boolean logPrePacketTransform);
+
     /**
      * Returns whether packets should be logged after being transformed.
      * Set to false by default.
      *
      * @return whether packets should be logged after being transformed
      */
-    @Beta
     boolean logPostPacketTransform();
 
     /**
@@ -90,7 +109,6 @@ public interface DebugHandler {
      *
      * @param logPostPacketTransform whether packets should be logged after being transformed
      */
-    @Beta
     void setLogPostPacketTransform(boolean logPostPacketTransform);
 
     /**
@@ -103,7 +121,6 @@ public interface DebugHandler {
      */
     boolean shouldLog(PacketWrapper wrapper, Direction direction);
 
-    @Beta
     default void enableAndLogIds(final PacketType... packetTypes) {
         setEnabled(true);
         for (final PacketType packetType : packetTypes) {

api/src/main/java/com/viaversion/viaversion/api/legacy/LegacyViaAPI.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/legacy/bossbar/BossBar.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/legacy/bossbar/BossColor.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/legacy/bossbar/BossFlag.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/legacy/bossbar/BossStyle.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/AnimalVariant.java

@@ -0,0 +1,55 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft;
+
+import com.viaversion.viaversion.api.type.Types;
+import com.viaversion.viaversion.api.type.types.misc.HolderType;
+import io.netty.buffer.ByteBuf;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * Represents an animal variant (e.g. for cows, pigs, chickens).
+ *
+ * @param modelType model type id
+ * @param texture texture path
+ * @param biomes biomes this variant can spawn in, if limited to specific biomes
+ */
+public record AnimalVariant(int modelType, String texture, @Nullable HolderSet biomes) {
+
+    public static HolderType<AnimalVariant> TYPE = new HolderType<>() {
+        @Override
+        public AnimalVariant readDirect(final ByteBuf buffer) {
+            final int modelType = Types.VAR_INT.readPrimitive(buffer);
+            final String texture = Types.STRING.read(buffer);
+            final HolderSet biomes = Types.OPTIONAL_HOLDER_SET.read(buffer);
+            return new AnimalVariant(modelType, texture, biomes);
+        }
+
+        @Override
+        public void writeDirect(final ByteBuf buffer, final AnimalVariant variant) {
+            Types.VAR_INT.writePrimitive(buffer, variant.modelType());
+            Types.STRING.write(buffer, variant.texture());
+            Types.OPTIONAL_HOLDER_SET.write(buffer, variant.biomes());
+        }
+    };
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/BlockChangeRecord.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -65,4 +65,4 @@ public interface BlockChangeRecord {
     int getBlockId();
 
     void setBlockId(int blockId);
-}
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/BlockChangeRecord1_16_2.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -58,7 +58,7 @@ public class BlockChangeRecord1_16_2 implements BlockChangeRecord {
 
     @Override
     public short getY(int chunkSectionY) {
-        Preconditions.checkArgument(chunkSectionY >= 0, "Invalid chunkSectionY: " + chunkSectionY);
+        Preconditions.checkArgument(chunkSectionY >= 0, "Invalid chunkSectionY: %s", chunkSectionY);
         return (short) ((chunkSectionY << 4) + sectionY);
     }
 

api/src/main/java/com/viaversion/viaversion/api/minecraft/BlockChangeRecord1_8.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/BlockFace.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -33,7 +33,6 @@ public enum BlockFace {
     TOP((byte) 0, (byte) 1, (byte) 0, EnumAxis.Y),
     BOTTOM((byte) 0, (byte) -1, (byte) 0, EnumAxis.Y);
 
-    public static final BlockFace[] HORIZONTAL = {NORTH, SOUTH, EAST, WEST};
     private static final Map<BlockFace, BlockFace> opposites = new EnumMap<>(BlockFace.class);
 
     static {

api/src/main/java/com/viaversion/viaversion/api/minecraft/BlockPosition.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -37,6 +37,13 @@ public class BlockPosition {
         return new BlockPosition(x + face.modX(), y + face.modY(), z + face.modZ());
     }
 
+    public double distanceFromCenterSquared(final double x, final double y, final double z) {
+        final double dx = this.x + 0.5 - x;
+        final double dy = this.y + 0.5 - y;
+        final double dz = this.z + 0.5 - z;
+        return dx * dx + dy * dy + dz * dz;
+    }
+
     public int x() {
         return x;
     }

api/src/main/java/com/viaversion/viaversion/api/minecraft/ChunkPosition.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -66,6 +66,17 @@ public final class ChunkPosition {
         return (long) chunkX & 0xffffffffL | ((long) chunkZ & 0xffffffffL) << 32;
     }
 
+    /**
+     * Returns a long key for the given block coordinates.
+     *
+     * @param x the block X coordinate
+     * @param z the block Z coordinate
+     * @return the chunk key
+     */
+    public static long chunkKeyForBlock(final int x, final int z) {
+        return chunkKey(x >> 4, z >> 4);
+    }
+
     @Override
     public boolean equals(final Object o) {
         if (this == o) return true;

api/src/main/java/com/viaversion/viaversion/api/minecraft/ClientWorld.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/EitherHolder.java

@@ -0,0 +1,82 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft;
+
+public interface EitherHolder<T> {
+
+    /**
+     * Returns a direct or indirect value holder.
+     *
+     * @param value the value
+     * @param <T>   the type of the value
+     * @return a new direct holder
+     */
+    static <T> EitherHolder<T> of(final Holder<T> value) {
+        return new EitherHolderImpl<>(value, null);
+    }
+
+    /**
+     * Returns an indirect holder via the resource key.
+     *
+     * @param key  the resource key
+     * @param <T> the type of the value
+     * @return a new holder with the given resource key
+     */
+    static <T> EitherHolder<T> of(final String key) {
+        return new EitherHolderImpl<>(null, key);
+    }
+
+    /**
+     * Returns true if this holder is backed by a direct value.
+     *
+     * @return true if the holder is direct
+     * @see #hasKey()
+     */
+    boolean hasHolder();
+
+    /**
+     * Returns true if this holder has a resource key.
+     *
+     * @return true if this holder has a resource key
+     * @see #hasHolder()
+     */
+    boolean hasKey();
+
+    /**
+     * Returns the value of this holder.
+     *
+     * @return the value of this holder
+     * @throws IllegalArgumentException if this contains a resource key instead of a holder
+     * @see #hasHolder()
+     */
+    Holder<T> holder();
+
+    /**
+     * Returns the resource key.
+     *
+     * @return the resource key
+     * @throws IllegalArgumentException if this contains a holder instead of a resource key
+     * @see #hasKey()
+     */
+    String key();
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/EitherHolderImpl.java

@@ -0,0 +1,55 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft;
+
+import com.google.common.base.Preconditions;
+import com.viaversion.viaversion.util.EitherImpl;
+
+final class EitherHolderImpl<T> extends EitherImpl<Holder<T>, String> implements EitherHolder<T> {
+
+    EitherHolderImpl(final Holder<T> left, final String value) {
+        super(left, value);
+    }
+
+    @Override
+    public boolean hasHolder() {
+        return isLeft();
+    }
+
+    @Override
+    public boolean hasKey() {
+        return isRight();
+    }
+
+    @Override
+    public Holder<T> holder() {
+        Preconditions.checkArgument(hasHolder(), "Either does not have a holder");
+        return left();
+    }
+
+    @Override
+    public String key() {
+        Preconditions.checkArgument(hasKey(), "Either does not have a key");
+        return right();
+    }
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/Environment.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/EulerAngle.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/GameMode.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -24,22 +24,28 @@ package com.viaversion.viaversion.api.minecraft;
 
 public enum GameMode {
 
-    NOT_SET(""),
-    SURVIVAL("Survival Mode"),
-    CREATIVE("Creative Mode"),
-    ADVENTURE("Adventure Mode"),
-    SPECTATOR("Spectator Mode");
+    NOT_SET("", -1),
+    SURVIVAL("Survival Mode", 0),
+    CREATIVE("Creative Mode", 1),
+    ADVENTURE("Adventure Mode", 2),
+    SPECTATOR("Spectator Mode", 3);
 
     private final String text;
+    private final int id;
 
-    GameMode(String text) {
+    GameMode(String text, final int id) {
         this.text = text;
+        this.id = id;
     }
 
     public String text() {
         return text;
     }
 
+    public int id() {
+        return id;
+    }
+
     public static GameMode getById(int id) {
         return switch (id) {
             case -1 -> NOT_SET;

api/src/main/java/com/viaversion/viaversion/api/minecraft/GameProfile.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,11 +22,31 @@
  */
 package com.viaversion.viaversion.api.minecraft;
 
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 import java.util.UUID;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 public record GameProfile(@Nullable String name, @Nullable UUID id, Property[] properties) {
 
+    public GameProfile(@Nullable final String name, @Nullable final UUID id) {
+        this(name, id, new Property[0]);
+    }
+
+    public Map<String, List<Property>> propertiesMap() {
+        final Map<String, List<Property>> map = new HashMap<>();
+        for (Property property : properties) {
+            map.computeIfAbsent(property.name(), k -> new ArrayList<>()).add(property);
+        }
+        return map;
+    }
+
     public record Property(String name, String value, @Nullable String signature) {
+
+        public Property(final String name, final String value) {
+            this(name, value, null);
+        }
     }
 }

api/src/main/java/com/viaversion/viaversion/api/minecraft/GlobalBlockPosition.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/Holder.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -23,6 +23,8 @@
 package com.viaversion.viaversion.api.minecraft;
 
 import it.unimi.dsi.fastutil.ints.Int2IntFunction;
+import java.util.function.Function;
+import java.util.function.Supplier;
 
 public interface Holder<T> {
 
@@ -88,5 +90,24 @@ public interface Holder<T> {
      * @param rewriteFunction the function to rewrite the id
      * @return a new holder with the id rewritten, or self
      */
-    Holder<T> updateId(final Int2IntFunction rewriteFunction);
+    default Holder<T> updateId(final Int2IntFunction rewriteFunction) {
+        return this.updateId(rewriteFunction, null);
+    }
+
+    /**
+     * Returns a new holder with the id rewritten using the given function, or self if this is a direct holder or the id did not change.
+     *
+     * @param rewriteFunction the function to rewrite the id
+     * @param ifMissing       a supplier that provides a new holder if the id is missing (i.e. -1)
+     * @return a new holder with the id rewritten, or self
+     */
+    Holder<T> updateId(Int2IntFunction rewriteFunction, Supplier<Holder<T>> ifMissing);
+
+    /**
+     * Returns a new holder with the value rewritten using the given function, or self if this is an id holder or the value did not change.
+     *
+     * @param rewriteFunction the function to rewrite the value
+     * @return a new holder with the value rewritten, or self
+     */
+    Holder<T> updateValue(final Function<T, T> rewriteFunction);
 }

api/src/main/java/com/viaversion/viaversion/api/minecraft/HolderSet.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/HolderSetImpl.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -67,11 +67,17 @@ final class HolderSetImpl {
 
         @Override
         public HolderSet rewrite(final Int2IntFunction idRewriter) {
+            // Filter out negative ids as they would come from missing VB mapping data. This happens especially
+            // with block ids which are not mapped and thus written as -1 so VV rewriters can cancel them nicely.
             final int[] mappedIds = new int[ids.length];
-            for (int i = 0; i < mappedIds.length; i++) {
-                mappedIds[i] = idRewriter.applyAsInt(ids[i]);
+            int validCount = 0;
+            for (final int id : ids) {
+                final int mappedId = idRewriter.applyAsInt(id);
+                if (mappedId != -1) {
+                    mappedIds[validCount++] = mappedId;
+                }
             }
-            return new Ids(mappedIds);
+            return new Ids(validCount == ids.length ? mappedIds : Arrays.copyOf(mappedIds, validCount));
         }
 
         @Override

api/src/main/java/com/viaversion/viaversion/api/minecraft/IdHolder.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -24,6 +24,8 @@ package com.viaversion.viaversion.api.minecraft;
 
 import com.google.common.base.Preconditions;
 import it.unimi.dsi.fastutil.ints.Int2IntFunction;
+import java.util.function.Function;
+import java.util.function.Supplier;
 
 record IdHolder<T>(int id) implements Holder<T> {
 
@@ -47,14 +49,22 @@ record IdHolder<T>(int id) implements Holder<T> {
     }
 
     @Override
-    public Holder<T> updateId(final Int2IntFunction rewriteFunction) {
+    public Holder<T> updateId(final Int2IntFunction rewriteFunction, final Supplier<Holder<T>> ifMissing) {
         final int rewrittenId = rewriteFunction.applyAsInt(id);
         if (rewrittenId == id) {
             return this;
         }
         if (rewrittenId == -1) {
+            if (ifMissing != null) {
+                return ifMissing.get();
+            }
             throw new IllegalArgumentException("Received invalid id in updateId");
         }
         return Holder.of(rewrittenId);
     }
+
+    @Override
+    public Holder<T> updateValue(final Function<T, T> rewriteFunction) {
+        return this;
+    }
 }

api/src/main/java/com/viaversion/viaversion/api/minecraft/PaintingVariant.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/Particle.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,15 +22,15 @@
  */
 package com.viaversion.viaversion.api.minecraft;
 
-import com.viaversion.viaversion.api.minecraft.item.Item;
 import com.viaversion.viaversion.api.protocol.packet.PacketWrapper;
 import com.viaversion.viaversion.api.type.Type;
+import com.viaversion.viaversion.util.Copyable;
 import com.viaversion.viaversion.util.IdHolder;
 import io.netty.buffer.ByteBuf;
 import java.util.ArrayList;
 import java.util.List;
 
-public final class Particle implements IdHolder {
+public final class Particle implements IdHolder, Copyable {
     private final List<ParticleData<?>> arguments = new ArrayList<>(4);
     private int id;
 
@@ -73,6 +73,7 @@ public final class Particle implements IdHolder {
         arguments.set(index, new ParticleData<>(type, value));
     }
 
+    @Override
     public Particle copy() {
         final Particle particle = new Particle(id);
         for (ParticleData<?> argument : arguments) {
@@ -89,7 +90,7 @@ public final class Particle implements IdHolder {
             '}';
     }
 
-    public static final class ParticleData<T> {
+    public static final class ParticleData<T> implements Copyable {
         private final Type<T> type;
         private T value;
 
@@ -118,12 +119,9 @@ public final class Particle implements IdHolder {
             wrapper.write(type, value);
         }
 
+        @Override
         public ParticleData<T> copy() {
-            if (value instanceof Item item) {
-                return new ParticleData<>(type, (T) item.copy());
-            } else {
-                return new ParticleData<>(type, value);
-            }
+            return new ParticleData<>(type, Copyable.copy(value));
         }
 
         @Override

api/src/main/java/com/viaversion/viaversion/api/minecraft/PlayerMessageSignature.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/ProfileKey.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/Quaternion.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/RegistryEntry.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -23,6 +23,7 @@
 package com.viaversion.viaversion.api.minecraft;
 
 import com.viaversion.nbt.tag.Tag;
+import com.viaversion.viaversion.util.Copyable;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 /**
@@ -31,12 +32,13 @@ import org.checkerframework.checker.nullness.qual.Nullable;
  * @param key key of the registry entry
  * @param tag data of the registry entry, or null if the client should use its default
  */
-public record RegistryEntry(String key, @Nullable Tag tag) {
+public record RegistryEntry(String key, @Nullable Tag tag) implements Copyable {
 
     public RegistryEntry withKey(final String key) {
         return new RegistryEntry(key, tag != null ? tag.copy() : null);
     }
 
+    @Override
     public RegistryEntry copy() {
         return new RegistryEntry(key, tag != null ? tag.copy() : null);
     }

api/src/main/java/com/viaversion/viaversion/api/minecraft/RegistryType.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/SoundEvent.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,11 +22,21 @@
  */
 package com.viaversion.viaversion.api.minecraft;
 
+import it.unimi.dsi.fastutil.ints.Int2IntFunction;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 public record SoundEvent(String identifier, @Nullable Float fixedRange) {
 
+    private static final Holder<SoundEvent> UNKNOWN = Holder.of(new SoundEvent("viaversion:unknown", 0F));
+
     public SoundEvent withIdentifier(final String identifier) {
         return new SoundEvent(identifier, this.fixedRange);
     }
+
+    public static @Nullable Holder<SoundEvent> rewriteHolder(@Nullable final Holder<SoundEvent> holder, final Int2IntFunction soundRewriteFunction) {
+        if (holder == null) {
+            return null;
+        }
+        return holder.updateId(soundRewriteFunction, () -> UNKNOWN);
+    }
 }

api/src/main/java/com/viaversion/viaversion/api/minecraft/TagData.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/ValueHolder.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -23,6 +23,8 @@
 package com.viaversion.viaversion.api.minecraft;
 
 import it.unimi.dsi.fastutil.ints.Int2IntFunction;
+import java.util.function.Function;
+import java.util.function.Supplier;
 
 record ValueHolder<T>(T value) implements Holder<T> {
 
@@ -42,7 +44,13 @@ record ValueHolder<T>(T value) implements Holder<T> {
     }
 
     @Override
-    public Holder<T> updateId(final Int2IntFunction rewriteFunction) {
+    public Holder<T> updateId(final Int2IntFunction rewriteFunction, final Supplier<Holder<T>> ifMissing) {
         return this;
     }
+
+    @Override
+    public Holder<T> updateValue(final Function<T, T> rewriteFunction) {
+        final T rewrittenValue = rewriteFunction.apply(value);
+        return rewrittenValue != value ? Holder.of(rewrittenValue) : this;
+    }
 }

api/src/main/java/com/viaversion/viaversion/api/minecraft/Vector.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/Vector3f.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/VillagerData.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/WolfVariant.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/WorldIdentifiers.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/blockentity/BlockEntity.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/blockentity/BlockEntityImpl.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/BaseChunk.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -143,6 +143,16 @@ public class BaseChunk implements Chunk {
         this.heightMap = heightMap;
     }
 
+    @Override
+    public Heightmap[] heightmaps() {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public void setHeightmaps(final Heightmap[] heightmaps) {
+        throw new UnsupportedOperationException();
+    }
+
     @Override
     public List<CompoundTag> getBlockEntities() {
         return blockEntities;

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/Chunk.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -79,7 +79,8 @@ public interface Chunk {
      * @return chunk section bit mask, only non-null for 1.17+ chunks
      * @see #getBitmask()
      */
-    @Nullable BitSet getChunkMask();
+    @Nullable
+    BitSet getChunkMask();
 
     void setChunkMask(BitSet chunkSectionMask);
 
@@ -88,7 +89,8 @@ public interface Chunk {
      *
      * @return array of nullable chunk sections
      */
-    @Nullable ChunkSection[] getSections();
+    @Nullable
+    ChunkSection[] getSections();
 
     void setSections(ChunkSection[] sections);
 
@@ -106,10 +108,15 @@ public interface Chunk {
      *
      * @return compoundtag containing heightmaps if present
      */
-    @Nullable CompoundTag getHeightMap();
+    @Nullable
+    CompoundTag getHeightMap();
 
     void setHeightMap(@Nullable CompoundTag heightMap);
 
+    Heightmap[] heightmaps();
+
+    void setHeightmaps(Heightmap[] heightmaps);
+
     /**
      * Returns a list of block entities.
      *

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/Chunk1_18.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -123,6 +123,16 @@ public class Chunk1_18 implements Chunk {
         this.heightMap = heightMap;
     }
 
+    @Override
+    public Heightmap[] heightmaps() {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public void setHeightmaps(final Heightmap[] heightmaps) {
+        throw new UnsupportedOperationException();
+    }
+
     @Override
     public List<CompoundTag> getBlockEntities() {
         throw new UnsupportedOperationException();

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/Chunk1_21_5.java

@@ -0,0 +1,145 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft.chunks;
+
+import com.viaversion.nbt.tag.CompoundTag;
+import com.viaversion.viaversion.api.minecraft.blockentity.BlockEntity;
+import java.util.BitSet;
+import java.util.List;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+public class Chunk1_21_5 implements Chunk {
+    protected final int x;
+    protected final int z;
+    protected ChunkSection[] sections;
+    protected Heightmap[] heightmaps;
+    protected final List<BlockEntity> blockEntities;
+
+    public Chunk1_21_5(int x, int z, ChunkSection[] sections, Heightmap[] heightmaps, List<BlockEntity> blockEntities) {
+        this.x = x;
+        this.z = z;
+        this.sections = sections;
+        this.heightmaps = heightmaps;
+        this.blockEntities = blockEntities;
+    }
+
+    @Override
+    public boolean isBiomeData() {
+        return false;
+    }
+
+    @Override
+    public int getX() {
+        return x;
+    }
+
+    @Override
+    public int getZ() {
+        return z;
+    }
+
+    @Override
+    public boolean isFullChunk() {
+        return true;
+    }
+
+    @Override
+    public boolean isIgnoreOldLightData() {
+        return false;
+    }
+
+    @Override
+    public void setIgnoreOldLightData(boolean ignoreOldLightData) {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public int getBitmask() {
+        return -1;
+    }
+
+    @Override
+    public void setBitmask(int bitmask) {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public @Nullable BitSet getChunkMask() {
+        return null;
+    }
+
+    @Override
+    public void setChunkMask(BitSet chunkSectionMask) {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public ChunkSection[] getSections() {
+        return sections;
+    }
+
+    @Override
+    public void setSections(ChunkSection[] sections) {
+        this.sections = sections;
+    }
+
+    @Override
+    public int @Nullable [] getBiomeData() {
+        return null;
+    }
+
+    @Override
+    public void setBiomeData(int @Nullable [] biomeData) {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public @Nullable CompoundTag getHeightMap() {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public void setHeightMap(final CompoundTag heightMap) {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public Heightmap[] heightmaps() {
+        return heightmaps;
+    }
+
+    @Override
+    public void setHeightmaps(final Heightmap[] heightmaps) {
+        this.heightmaps = heightmaps;
+    }
+
+    @Override
+    public List<CompoundTag> getBlockEntities() {
+        throw new UnsupportedOperationException();
+    }
+
+    @Override
+    public List<BlockEntity> blockEntities() {
+        return blockEntities;
+    }
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/ChunkSection.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/ChunkSectionImpl.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/ChunkSectionLight.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/ChunkSectionLightImpl.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/DataPalette.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/DataPaletteImpl.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/Heightmap.java

@@ -0,0 +1,26 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft.chunks;
+
+public record Heightmap(int type, long[] data) {
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/NibbleArray.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal

api/src/main/java/com/viaversion/viaversion/api/minecraft/chunks/PaletteType.java

@@ -1,6 +1,6 @@
 /*
  * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
- * Copyright (C) 2016-2024 ViaVersion and contributors
+ * Copyright (C) 2016-2025 ViaVersion and contributors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -41,4 +41,4 @@ public enum PaletteType {
     public int highestBitsPerValue() {
         return highestBitsPerValue;
     }
-}
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/codec/CodecContext.java

@@ -0,0 +1,54 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft.codec;
+
+import com.viaversion.viaversion.api.data.MappingData;
+import com.viaversion.viaversion.api.minecraft.data.StructuredDataKey;
+import com.viaversion.viaversion.util.Key;
+import java.util.List;
+
+public interface CodecContext {
+
+    RegistryAccess registryAccess();
+
+    boolean mapped();
+
+    boolean isSupported(StructuredDataKey<?> key);
+
+    interface RegistryAccess {
+
+        Key item(int id);
+
+        Key enchantment(int id);
+
+        Key attributeModifier(int id);
+
+        Key dataComponentType(int id);
+
+        static RegistryAccess of(final List<String> enchantments, final MappingData mappingData) {
+            return new RegistryAccessImpl(enchantments, mappingData);
+        }
+
+        RegistryAccess withMapped(boolean mapped);
+    }
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/codec/DelegatingOps.java

@@ -0,0 +1,110 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft.codec;
+
+import com.viaversion.viaversion.api.type.Type;
+import java.util.function.Consumer;
+
+public class DelegatingOps implements Ops {
+
+    private final Ops delegate;
+
+    public DelegatingOps(final Ops delegate) {
+        this.delegate = delegate;
+    }
+
+    @Override
+    public CodecContext context() {
+        return delegate.context();
+    }
+
+    @Override
+    public void writeByte(final byte b) {
+        delegate.writeByte(b);
+    }
+
+    @Override
+    public void writeBytes(final byte[] array) {
+        delegate.writeBytes(array);
+    }
+
+    @Override
+    public void writeBoolean(final boolean b) {
+        delegate.writeBoolean(b);
+    }
+
+    @Override
+    public void writeShort(final short s) {
+        delegate.writeShort(s);
+    }
+
+    @Override
+    public void writeString(final CharSequence sequence) {
+        delegate.writeString(sequence);
+    }
+
+    @Override
+    public void writeInt(final int i) {
+        delegate.writeInt(i);
+    }
+
+    @Override
+    public void writeLong(final long l) {
+        delegate.writeLong(l);
+    }
+
+    @Override
+    public void writeFloat(final float f) {
+        delegate.writeFloat(f);
+    }
+
+    @Override
+    public void writeDouble(final double d) {
+        delegate.writeDouble(d);
+    }
+
+    @Override
+    public void writeInts(final int[] array) {
+        delegate.writeInts(array);
+    }
+
+    @Override
+    public void writeLongs(final long[] array) {
+        delegate.writeLongs(array);
+    }
+
+    @Override
+    public void writeList(final Consumer<ListSerializer> consumer) {
+        delegate.writeList(consumer);
+    }
+
+    @Override
+    public void writeMap(final Consumer<MapSerializer> consumer) {
+        delegate.writeMap(consumer);
+    }
+
+    @Override
+    public <V> void write(final Type<V> type, final V value) {
+        delegate.write(type, value);
+    }
+}

api/src/main/java/com/viaversion/viaversion/api/minecraft/codec/Ops.java

@@ -0,0 +1,135 @@
+/*
+ * This file is part of ViaVersion - https://github.com/ViaVersion/ViaVersion
+ * Copyright (C) 2016-2025 ViaVersion and contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package com.viaversion.viaversion.api.minecraft.codec;
+
+import com.viaversion.viaversion.api.type.Type;
+import com.viaversion.viaversion.api.type.Types;
+import java.util.Objects;
+import java.util.function.Consumer;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+public interface Ops {
+
+    CodecContext context();
+
+    void writeByte(byte b);
+
+    void writeBytes(byte[] array);
+
+    void writeBoolean(boolean b);
+
+    void writeShort(short s);
+
+    void writeString(CharSequence sequence);
+
+    void writeInt(int i);
+
+    void writeLong(long l);
+
+    void writeFloat(float f);
+
+    void writeDouble(double d);
+
+    void writeInts(int[] array);
+
+    void writeLongs(long[] array);
+
+    void writeList(Consumer<ListSerializer> consumer);
+
+    void writeMap(Consumer<MapSerializer> consumer);
+
+    <V> void write(final Type<V> type, final V value);
+
+    interface ListSerializer {
+
+        <V> ListSerializer write(Type<V> valueType, V value);
+
+        ListSerializer writeList(Consumer<ListSerializer> consumer);
+
+        ListSerializer writeMap(Consumer<MapSerializer> consumer);
+    }
+
+    interface MapSerializer {
+
+        <K, V> MapSerializer write(Type<K> keyType, K key, Type<V> valueType, V value);
+
+        default <V> MapSerializer write(final String key, final Type<V> type, final V value) {
+            write(Types.STRING, key, type, value);
+            return this;
+        }
+
+        /**
+         * Writes the given value or default value if the value is null.
+         *
+         * @param key map key
+         * @param type type of the value
+         * @param value the value to write, or null
+         * @param def default value to write if the value is null
+         * @return self
+         * @param <V> value type
+         */
+        default <V> MapSerializer write(final String key, final Type<V> type, @Nullable final V value, final V def) {
+            write(Types.STRING, key, type, value != null ? value : def);
+            return this;
+        }
+
+        /**
+         * Writes the given value if it is not null.
+         *
+         * @param key map key
+         * @param type type of the value
+         * @param value the value to write, or null
+         * @return self
+         * @param <V> value type
+         */
+        default <V> MapSerializer writeOptional(final String key, final Type<V> type, @Nullable final V value) {
+            if (value != null) {
+                write(Types.STRING, key, type, value);
+            }
+            return this;
+        }
+
+        /**
+         * Writes the given value if it is not null and not equal to the default value.
+         *
+         * @param key map key
+         * @param type type of the value
+         * @param value the value to write, or null
+         * @param def default value to compare against
+         * @return self
+         * @param <V> value type
+         */
+        default <V> MapSerializer writeOptional(final String key, final Type<V> type, @Nullable final V value, final V def) {
+            if (value != null && !Objects.deepEquals(value, def)) {
+                write(Types.STRING, key, type, value);
+            }
+            return this;
+        }
+
+        MapSerializer writeList(String key, Consumer<ListSerializer> consumer);
+
+        MapSerializer writeMap(String key, Consumer<MapSerializer> consumer);
+
+        <T> MapSerializer writeInlinedMap(Type<T> valueType, T value);
+    }
+}