fix PlayerChangedMainHandEvent javadoc (PaperMC#12020)

* fix PlayerChangedMainHandEvent javadoc * Obsolete --------- Co-authored-by: Bjarne Koll <[email protected]>
Doc94 · Jan 26, 2025 · 7e21cb8 · 7e21cb8
1 parent 3af5e77
commit 7e21cb8
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 5 deletions.
diff --git a/paper-api/src/main/java/org/bukkit/event/player/PlayerChangedMainHandEvent.java b/paper-api/src/main/java/org/bukkit/event/player/PlayerChangedMainHandEvent.java
@@ -1,33 +1,51 @@
 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;
     }
 
     /**
      * Gets the new main hand of the player. The old hand is still momentarily
      * 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

diff --git a/paper-server/patches/sources/net/minecraft/server/level/ServerPlayer.java.patch b/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);
 +        }