feat(hotbar): allow clearing the inventory before applying a layout

src/main/java/net/theevilreaper/aves/hotbar/HotBarLayout.java

@@ -13,8 +13,8 @@
  * Use {@link #apply(Player)} to write the layout into a player's inventory.
  *
  * @author theEvilReaper
- * @version 1.14.0
- * @since 0.1.0
+ * @version 1.1.0
+ * @since 1.14.0
  */
 public final class HotBarLayout {
 
@@ -65,6 +65,19 @@ public ItemStack get(int slot) {
      * @param player the player whose hotbar is updated
      */
     public void apply(Player player) {
+        apply(player, false);
+    }
+
+    /**
+     * Writes this layout into the player's inventory (slots 0–8).
+     *
+     * @param player         the player whose hotbar is updated
+     * @param clearInventory whether to clear the player's entire inventory before applying
+     */
+    public void apply(Player player, boolean clearInventory) {
+        if (clearInventory) {
+            player.getInventory().clear();
+        }
         for (int i = 0; i < items.length; i++) {
             player.getInventory().setItemStack(i, items[i]);
         }

src/test/java/net/theevilreaper/aves/hotbar/HotBarLayoutIntegrationTest.java

@@ -0,0 +1,71 @@
+package net.theevilreaper.aves.hotbar;
+
+import net.minestom.server.item.ItemStack;
+import net.minestom.server.item.Material;
+import net.minestom.testing.Env;
+import net.minestom.testing.extension.MicrotusExtension;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+@ExtendWith(MicrotusExtension.class)
+class HotBarLayoutIntegrationTest {
+
+    @Test
+    void testApplyWithoutClearingInventory(Env env) {
+        var instance = env.createFlatInstance();
+        var player = env.createPlayer(instance);
+        player.getInventory().setItemStack(10, ItemStack.of(Material.DIAMOND));
+
+        var layout = new HotBarLayout().set(0, ItemStack.of(Material.STICK));
+        layout.apply(player, false);
+
+        assertEquals(Material.STICK, player.getInventory().getItemStack(0).material());
+        assertEquals(Material.DIAMOND, player.getInventory().getItemStack(10).material());
+        env.destroyInstance(instance, true);
+    }
+
+    @Test
+    void testApplyWithClearingInventory(Env env) {
+        var instance = env.createFlatInstance();
+        var player = env.createPlayer(instance);
+        player.getInventory().setItemStack(10, ItemStack.of(Material.DIAMOND));
+
+        var layout = new HotBarLayout().set(0, ItemStack.of(Material.STICK));
+        layout.apply(player, true);
+
+        assertEquals(Material.STICK, player.getInventory().getItemStack(0).material());
+        assertEquals(ItemStack.AIR, player.getInventory().getItemStack(10));
+        env.destroyInstance(instance, true);
+    }
+
+    @Test
+    void testApplyClearsEntireInventoryAndArmor(Env env) {
+        var instance = env.createFlatInstance();
+        var player = env.createPlayer(instance);
+
+        player.getInventory().setItemStack(15, ItemStack.of(Material.GOLD_INGOT));
+        player.getInventory().setItemStack(25, ItemStack.of(Material.IRON_INGOT));
+        player.setHelmet(ItemStack.of(Material.DIAMOND_HELMET));
+        player.setChestplate(ItemStack.of(Material.DIAMOND_CHESTPLATE));
+        player.setLeggings(ItemStack.of(Material.DIAMOND_LEGGINGS));
+        player.setBoots(ItemStack.of(Material.DIAMOND_BOOTS));
+        player.setItemInOffHand(ItemStack.of(Material.SHIELD));
+
+        var layout = new HotBarLayout().set(2, ItemStack.of(Material.COMPASS));
+        layout.apply(player, true);
+
+        assertEquals(Material.COMPASS, player.getInventory().getItemStack(2).material());
+
+        assertEquals(ItemStack.AIR, player.getInventory().getItemStack(15));
+        assertEquals(ItemStack.AIR, player.getInventory().getItemStack(25));
+        assertEquals(ItemStack.AIR, player.getHelmet());
+        assertEquals(ItemStack.AIR, player.getChestplate());
+        assertEquals(ItemStack.AIR, player.getLeggings());
+        assertEquals(ItemStack.AIR, player.getBoots());
+        assertEquals(ItemStack.AIR, player.getItemInOffHand());
+
+        env.destroyInstance(instance, true);
+    }
+}