fix PlayerChangedMainHandEvent javadoc (#12020)

* fix PlayerChangedMainHandEvent javadoc

* Obsolete

---------

Co-authored-by: Bjarne Koll <lynxplay101@gmail.com>

paper-api/src/main/java/org/bukkit/event/player/PlayerChangedMainHandEvent.java

@@ -1,22 +1,26 @@
 package org.bukkit.event.player;
 
+import com.destroystokyo.paper.event.player.PlayerClientOptionsChangeEvent;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
 import org.bukkit.inventory.MainHand;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * Called when a player changes their main hand in the client settings.
+ * @apiNote Obsolete and replaced by {@link PlayerClientOptionsChangeEvent}.
  */
+@ApiStatus.Obsolete
 public class PlayerChangedMainHandEvent extends PlayerEvent {
 
     private static final HandlerList handlers = new HandlerList();
     //
-    private final MainHand mainHand;
+    private final MainHand newMainHand;
 
-    public PlayerChangedMainHandEvent(@NotNull Player who, @NotNull MainHand mainHand) {
+    public PlayerChangedMainHandEvent(@NotNull Player who, @NotNull MainHand newMainHand) {
         super(who);
-        this.mainHand = mainHand;
+        this.newMainHand = newMainHand;
     }
 
     /**
@@ -24,10 +28,24 @@ public class PlayerChangedMainHandEvent extends PlayerEvent {
      * available via {@link Player#getMainHand()}.
      *
      * @return the new {@link MainHand} of the player
+     * @deprecated has never been functional since its implementation and simply returns the old main hand.
+     * The method is left in this broken state to not break compatibility with plugins that relied on this fact.
+     * Use {@link #getNewMainHand()} instead or migrate to {@link PlayerClientOptionsChangeEvent#getMainHand()}.
      */
     @NotNull
+    @Deprecated(since = "1.21.4", forRemoval = true)
     public MainHand getMainHand() {
-        return mainHand;
+        return newMainHand == MainHand.LEFT ? MainHand.RIGHT : MainHand.LEFT;
+    }
+
+    /**
+     * Gets the new main hand of the player.
+     *
+     * @return the new {@link MainHand} of the player
+     */
+    @NotNull
+    public MainHand getNewMainHand() {
+        return newMainHand;
     }
 
     @NotNull

paper-server/patches/sources/net/minecraft/server/level/ServerPlayer.java.patch

@@ -1213,7 +1213,7 @@
 +        if (this.getMainArm() != clientInformation.mainHand()) {
 +            org.bukkit.event.player.PlayerChangedMainHandEvent event = new org.bukkit.event.player.PlayerChangedMainHandEvent(
 +                this.getBukkitEntity(),
-+                this.getMainArm() == HumanoidArm.LEFT ? org.bukkit.inventory.MainHand.LEFT : org.bukkit.inventory.MainHand.RIGHT
++                clientInformation.mainHand() == HumanoidArm.LEFT ? org.bukkit.inventory.MainHand.LEFT : org.bukkit.inventory.MainHand.RIGHT
 +            );
 +            this.server.server.getPluginManager().callEvent(event);
 +        }