Added player in inventory events + comments

src/main/java/net/minestom/server/data/Data.java

@@ -8,7 +8,8 @@ public class Data {
 
     public static final Data EMPTY = new Data() {
         @Override
-        public <T> void set(String key, T value, Class<T> type) {}
+        public <T> void set(String key, T value, Class<T> type) {
+        }
 
         @Override
         public <T> T get(String key) {
@@ -41,6 +42,8 @@ public class Data {
     }
 
     /**
+     * Get if the data has a key
+     *
      * @param key
      * @return true if the data contains the key, false otherwise
      */
@@ -49,6 +52,8 @@ public class Data {
     }
 
     /**
+     * Get the list of data keys
+     *
      * @return an unmodifiable set containing all keys
      */
     public Set<String> getKeys() {
@@ -56,12 +61,19 @@ public class Data {
     }
 
     /**
+     * Get if the data is empty or not
+     *
      * @return true if the data does not contain anything, false otherwise
      */
     public boolean isEmpty() {
         return data.isEmpty();
     }
 
+    /**
+     * Clone this data
+     *
+     * @return a cloned data object
+     */
     public Data clone() {
         Data data = new Data();
         data.data = new ConcurrentHashMap<>(this.data);

src/main/java/net/minestom/server/event/inventory/InventoryClickEvent.java

@@ -1,5 +1,6 @@
 package net.minestom.server.event.inventory;
 
+import net.minestom.server.entity.Player;
 import net.minestom.server.event.Event;
 import net.minestom.server.inventory.Inventory;
 import net.minestom.server.inventory.click.ClickType;
@@ -7,13 +8,14 @@ import net.minestom.server.item.ItemStack;
 
 public class InventoryClickEvent extends Event {
 
+    private Player player;
     private Inventory inventory;
     private int slot;
     private ClickType clickType;
     private ItemStack clickedItem;
     private ItemStack cursorItem;
 
-    public InventoryClickEvent(Inventory inventory, int slot, ClickType clickType, ItemStack clicked, ItemStack cursor) {
+    public InventoryClickEvent(Player player, Inventory inventory, int slot, ClickType clickType, ItemStack clicked, ItemStack cursor) {
         this.inventory = inventory;
         this.slot = slot;
         this.clickType = clickType;
@@ -21,6 +23,15 @@ public class InventoryClickEvent extends Event {
         this.cursorItem = cursor;
     }
 
+    /**
+     * Get the player who clicked in the inventory
+     *
+     * @return the player who clicked in the inventory
+     */
+    public Player getPlayer() {
+        return player;
+    }
+
     /**
      * Can be null if the clicked inventory is the player one
      *
@@ -30,18 +41,38 @@ public class InventoryClickEvent extends Event {
         return inventory;
     }
 
+    /**
+     * Get the clicked slot number
+     *
+     * @return the clicked slot number
+     */
     public int getSlot() {
         return slot;
     }
 
+    /**
+     * Get the click type
+     *
+     * @return the click type
+     */
     public ClickType getClickType() {
         return clickType;
     }
 
+    /**
+     * Get the clicked item
+     *
+     * @return the clicked item
+     */
     public ItemStack getClickedItem() {
         return clickedItem;
     }
 
+    /**
+     * Get the item in the player cursor
+     *
+     * @return the cursor item
+     */
     public ItemStack getCursorItem() {
         return cursorItem;
     }

src/main/java/net/minestom/server/event/inventory/InventoryCloseEvent.java

@@ -1,24 +1,43 @@
 package net.minestom.server.event.inventory;
 
+import net.minestom.server.entity.Player;
 import net.minestom.server.event.Event;
 import net.minestom.server.inventory.Inventory;
 
 public class InventoryCloseEvent extends Event {
 
+    private Player player;
     private Inventory inventory;
     private Inventory newInventory;
 
-    public InventoryCloseEvent(Inventory inventory) {
+    public InventoryCloseEvent(Player player, Inventory inventory) {
+        this.player = player;
         this.inventory = inventory;
     }
 
     /**
+     * Get the player who closed the inventory
+     *
+     * @return the player who closed the inventory
+     */
+    public Player getPlayer() {
+        return player;
+    }
+
+    /**
+     * Get the closed inventory
+     *
      * @return the closed inventory, null if this is the player inventory
      */
     public Inventory getInventory() {
         return inventory;
     }
 
+    /**
+     * Get the new inventory to open
+     *
+     * @return the new inventory to open, null if there isn't any
+     */
     public Inventory getNewInventory() {
         return newInventory;
     }
@@ -26,7 +45,7 @@ public class InventoryCloseEvent extends Event {
     /**
      * Can be used to open a new inventory after closing the previous one
      *
-     * @param newInventory the inventory to open, can be null
+     * @param newInventory the inventory to open, null to do not open any
      */
     public void setNewInventory(Inventory newInventory) {
         this.newInventory = newInventory;

src/main/java/net/minestom/server/event/inventory/InventoryOpenEvent.java

@@ -3,7 +3,6 @@ package net.minestom.server.event.inventory;
 import net.minestom.server.entity.Player;
 import net.minestom.server.event.CancellableEvent;
 import net.minestom.server.inventory.Inventory;
-import net.minestom.server.utils.validate.Check;
 
 public class InventoryOpenEvent extends CancellableEvent {
 
@@ -15,16 +14,32 @@ public class InventoryOpenEvent extends CancellableEvent {
         this.inventory = inventory;
     }
 
+    /**
+     * Get the player who opens the inventory
+     *
+     * @return the player who opens the inventory
+     */
     public Player getPlayer() {
         return player;
     }
 
+    /**
+     * Get the inventory to open, this could have been change by the {@link #setInventory(Inventory)}
+     *
+     * @return the inventory to open
+     */
     public Inventory getInventory() {
         return inventory;
     }
 
+    /**
+     * Change the inventory to open.
+     * to do not open any inventory see {@link #setCancelled(boolean)}
+     *
+     * @param inventory the inventory to open
+     * @throws NullPointerException if {@code inventory} is null
+     */
     public void setInventory(Inventory inventory) {
-        Check.notNull(inventory, "Inventory cannot be null!");
         this.inventory = inventory;
     }
 }

src/main/java/net/minestom/server/event/inventory/InventoryPreClickEvent.java

@@ -1,5 +1,6 @@
 package net.minestom.server.event.inventory;
 
+import net.minestom.server.entity.Player;
 import net.minestom.server.event.CancellableEvent;
 import net.minestom.server.inventory.Inventory;
 import net.minestom.server.inventory.click.ClickType;
@@ -8,13 +9,15 @@ import net.minestom.server.utils.item.ItemStackUtils;
 
 public class InventoryPreClickEvent extends CancellableEvent {
 
+    private Player player;
     private Inventory inventory;
     private int slot;
     private ClickType clickType;
     private ItemStack clickedItem;
     private ItemStack cursorItem;
 
-    public InventoryPreClickEvent(Inventory inventory, int slot, ClickType clickType, ItemStack clicked, ItemStack cursor) {
+    public InventoryPreClickEvent(Player player, Inventory inventory, int slot, ClickType clickType, ItemStack clicked, ItemStack cursor) {
+        this.player = player;
         this.inventory = inventory;
         this.slot = slot;
         this.clickType = clickType;
@@ -22,6 +25,15 @@ public class InventoryPreClickEvent extends CancellableEvent {
         this.cursorItem = cursor;
     }
 
+    /**
+     * Get the player who is trying to click on the inventory
+     *
+     * @return the player who clicked
+     */
+    public Player getPlayer() {
+        return player;
+    }
+
     /**
      * Can be null if the clicked inventory is the player one
      *
@@ -31,26 +43,56 @@ public class InventoryPreClickEvent extends CancellableEvent {
         return inventory;
     }
 
+    /**
+     * Get the clicked slot number
+     *
+     * @return the clicked slot number
+     */
     public int getSlot() {
         return slot;
     }
 
+    /**
+     * Get the click type
+     *
+     * @return the click type
+     */
     public ClickType getClickType() {
         return clickType;
     }
 
+    /**
+     * Get the item who have been clicked
+     *
+     * @return the clicked item
+     */
     public ItemStack getClickedItem() {
         return clickedItem;
     }
 
+    /**
+     * Change the clicked item
+     *
+     * @param clickedItem the clicked item
+     */
     public void setClickedItem(ItemStack clickedItem) {
         this.clickedItem = ItemStackUtils.notNull(clickedItem);
     }
 
+    /**
+     * Get the item who was in the player cursor
+     *
+     * @return the cursor item
+     */
     public ItemStack getCursorItem() {
         return cursorItem;
     }
 
+    /**
+     * Change the cursor item
+     *
+     * @param cursorItem the cursor item
+     */
     public void setCursorItem(ItemStack cursorItem) {
         this.cursorItem = ItemStackUtils.notNull(cursorItem);
     }

src/main/java/net/minestom/server/inventory/EquipmentHandler.java

@@ -4,16 +4,45 @@ import net.minestom.server.entity.Player;
 import net.minestom.server.item.ItemStack;
 import net.minestom.server.network.packet.server.play.EntityEquipmentPacket;
 
+/**
+ * Represent an entity which can have item in hand and armor slots
+ */
 public interface EquipmentHandler {
 
+    /**
+     * Get the item in main hand
+     *
+     * @return the item in main hand
+     */
     ItemStack getItemInMainHand();
 
+    /**
+     * Change the main hand item
+     *
+     * @param itemStack the main hand item
+     */
     void setItemInMainHand(ItemStack itemStack);
 
+    /**
+     * Get the item in off hand
+     *
+     * @return the item in off hand
+     */
     ItemStack getItemInOffHand();
 
+    /**
+     * Change the off hand item
+     *
+     * @param itemStack the off hand item
+     */
     void setItemInOffHand(ItemStack itemStack);
 
+    /**
+     * Get the item in the specific hand
+     *
+     * @param hand the hand to get the item from
+     * @return the item in {@code hand}
+     */
     default ItemStack getItemInHand(Player.Hand hand) {
         switch (hand) {
             case MAIN:
@@ -27,6 +56,12 @@ public interface EquipmentHandler {
         }
     }
 
+    /**
+     * Change the item in the specific hand
+     *
+     * @param hand  the hand to set the item to
+     * @param stack the itemstack to set
+     */
     default void setItemInHand(Player.Hand hand, ItemStack stack) {
         switch (hand) {
             case MAIN:
@@ -39,22 +74,68 @@ public interface EquipmentHandler {
         }
     }
 
+    /**
+     * Get the helmet
+     *
+     * @return the helmet
+     */
     ItemStack getHelmet();
 
+    /**
+     * Change the helmet
+     *
+     * @param itemStack the helmet
+     */
     void setHelmet(ItemStack itemStack);
 
+    /**
+     * Get the chestplate
+     *
+     * @return the chestplate
+     */
     ItemStack getChestplate();
 
+    /**
+     * Change the chestplate
+     *
+     * @param itemStack the chestplate
+     */
     void setChestplate(ItemStack itemStack);
 
+    /**
+     * Get the leggings
+     *
+     * @return the leggings
+     */
     ItemStack getLeggings();
 
+    /**
+     * Change the leggings
+     *
+     * @param itemStack the leggings
+     */
     void setLeggings(ItemStack itemStack);
 
+    /**
+     * Get the boots
+     *
+     * @return the boots
+     */
     ItemStack getBoots();
 
+    /**
+     * Change the boots
+     *
+     * @param itemStack the boots
+     */
     void setBoots(ItemStack itemStack);
 
+    /**
+     * Get the equipment in a specific slot
+     *
+     * @param slot the equipment to get the item from
+     * @return the equipment item
+     */
     default ItemStack getEquipment(EntityEquipmentPacket.Slot slot) {
         switch (slot) {
             case MAIN_HAND:

src/main/java/net/minestom/server/inventory/Inventory.java

@@ -183,7 +183,15 @@ public class Inventory implements InventoryModifier, InventoryClickHandler, View
         return result;
     }
 
+    /**
+     * Get the cursor item of a viewer
+     *
+     * @param player the player to get the cursor item from
+     * @return the player cursor item
+     * @throws IllegalStateException if {@code player} is not in the viewer list
+     */
     public ItemStack getCursorItem(Player player) {
+        Check.stateCondition(!isViewer(player), "You can only get the cursor item of a viewer");
         return cursorPlayersItem.getOrDefault(player, ItemStack.getAirItem());
     }
 

src/main/java/net/minestom/server/inventory/InventoryClickHandler.java

@@ -8,28 +8,75 @@ import net.minestom.server.item.ItemStack;
 /**
  * Represent an inventory which can receive click input
  * all methods returning boolean returns true if the action is successful, false otherwise
+ * <p>
+ * See https://wiki.vg/Protocol#Click_Window for more information
  */
 public interface InventoryClickHandler {
 
+    /**
+     * Called when a player left click in the inventory. Can also be to drop the cursor item
+     *
+     * @param player the player who clicked
+     * @param slot   the slot number
+     * @return true if the click hasn't been cancelled, false otherwise
+     */
     boolean leftClick(Player player, int slot);
 
+    /**
+     * Called when a player right click in the inventory. Can also be to drop the cursor item
+     *
+     * @param player the player who clicked
+     * @param slot   the slot number
+     * @return true if the click hasn't been cancelled, false otherwise
+     */
     boolean rightClick(Player player, int slot);
 
+    /**
+     * Called when a player shift click in the inventory
+     *
+     * @param player the player who clicked
+     * @param slot   the slot number
+     * @return true if the click hasn't been cancelled, false otherwise
+     */
     boolean shiftClick(Player player, int slot); // shift + left/right click have the same behavior
 
+    /**
+     * Called when a player held click in the inventory
+     *
+     * @param player the player who clicked
+     * @param slot   the slot number
+     * @param key    the held slot (0-8) pressed
+     * @return true if the click hasn't been cancelled, false otherwise
+     */
     boolean changeHeld(Player player, int slot, int key);
 
     boolean middleClick(Player player, int slot);
 
+    /**
+     * Called when a player press the drop button
+     *
+     * @param player the player who clicked
+     * @param mode
+     * @param slot   the slot number
+     * @param button -999 if clicking outside, normal if he is not
+     * @return true if the drop hasn't been cancelled, false otherwise
+     */
     boolean drop(Player player, int mode, int slot, int button);
 
     boolean dragging(Player player, int slot, int button);
 
+    /**
+     * Called when a player double click in the inventory
+     *
+     * @param player the player who clicked
+     * @param slot   the slot number
+     * @return true if the click hasn't been cancelled, false otherwise
+     */
     boolean doubleClick(Player player, int slot);
 
     default void callClickEvent(Player player, Inventory inventory, int slot,
                                 ClickType clickType, ItemStack clicked, ItemStack cursor) {
-        InventoryClickEvent inventoryClickEvent = new InventoryClickEvent(inventory, slot, clickType, clicked, cursor);
+        InventoryClickEvent inventoryClickEvent = new InventoryClickEvent(player, inventory, slot, clickType, clicked, cursor);
         player.callEvent(InventoryClickEvent.class, inventoryClickEvent);
     }
 

src/main/java/net/minestom/server/inventory/InventoryProperty.java

@@ -1,5 +1,10 @@
 package net.minestom.server.inventory;
 
+/**
+ * List of inventory property and their ID
+ * <p>
+ * See https://wiki.vg/Protocol#Window_Property for more information
+ */
 public enum InventoryProperty {
 
     FURNACE_FIRE_ICON((short) 0),

src/main/java/net/minestom/server/inventory/InventoryRule.java

@@ -1,4 +0,0 @@
-package net.minestom.server.inventory;
-
-public class InventoryRule {
-}

src/main/java/net/minestom/server/inventory/PlayerInventory.java

@@ -166,18 +166,37 @@ public class PlayerInventory implements InventoryModifier, InventoryClickHandler
         safeItemInsert(BOOTS_SLOT, itemStack);
     }
 
+    /**
+     * Refresh the player inventory by sending a {@link WindowItemsPacket} containing all
+     * the inventory items
+     */
     public void update() {
         PacketWriterUtils.writeAndSend(player, createWindowItemsPacket());
     }
 
+    /**
+     * Refresh only a specific slot with the updated item stack data
+     *
+     * @param slot the slot to refresh
+     */
     public void refreshSlot(int slot) {
         sendSlotRefresh((short) convertToPacketSlot(slot), getItemStack(slot));
     }
 
+    /**
+     * Get the item in player cursor
+     *
+     * @return the cursor item
+     */
     public ItemStack getCursorItem() {
         return cursorItem;
     }
 
+    /**
+     * Change the player cursor item
+     *
+     * @param cursorItem the new cursor item
+     */
     public void setCursorItem(ItemStack cursorItem) {
         this.cursorItem = ItemStackUtils.notNull(cursorItem);
     }

src/main/java/net/minestom/server/inventory/click/InventoryClickProcessor.java

@@ -506,7 +506,7 @@ public class InventoryClickProcessor {
                 player.getInventory().getInventoryConditions() : inventory.getInventoryConditions();
         if (!inventoryConditions.isEmpty()) {
 
-            InventoryPreClickEvent inventoryPreClickEvent = new InventoryPreClickEvent(inventory, slot, clickType, clicked, cursor);
+            InventoryPreClickEvent inventoryPreClickEvent = new InventoryPreClickEvent(player, inventory, slot, clickType, clicked, cursor);
             player.callEvent(InventoryPreClickEvent.class, inventoryPreClickEvent);
             cursor = inventoryPreClickEvent.getCursorItem();
             clicked = inventoryPreClickEvent.getClickedItem();
@@ -544,7 +544,7 @@ public class InventoryClickProcessor {
 
     private void callClickEvent(Player player, Inventory inventory, int slot,
                                 ClickType clickType, ItemStack clicked, ItemStack cursor) {
-        InventoryClickEvent inventoryClickEvent = new InventoryClickEvent(inventory, slot, clickType, clicked, cursor);
+        InventoryClickEvent inventoryClickEvent = new InventoryClickEvent(player, inventory, slot, clickType, clicked, cursor);
         player.callEvent(InventoryClickEvent.class, inventoryClickEvent);
     }
 

src/main/java/net/minestom/server/listener/WindowListener.java

@@ -112,7 +112,7 @@ public class WindowListener {
 
     public static void closeWindowListener(ClientCloseWindow packet, Player player) {
         // if windowId == 0 then it is player's inventory, meaning that they hadn't been any open inventory packet
-        InventoryCloseEvent inventoryCloseEvent = new InventoryCloseEvent(player.getOpenInventory());
+        InventoryCloseEvent inventoryCloseEvent = new InventoryCloseEvent(player, player.getOpenInventory());
         player.callEvent(InventoryCloseEvent.class, inventoryCloseEvent);
 
         player.closeInventory();