feat: add more api functions to the Inventory class

include/endstone/detail/inventory/inventory.h

@@ -26,6 +26,11 @@ class EndstoneInventory : public Inventory {
     [[nodiscard]] int getMaxStackSize() const override;
     [[nodiscard]] std::shared_ptr<ItemStack> getItem(int index) const override;
     void setItem(int index, std::shared_ptr<ItemStack> item) override;
+    void addItem(ItemStack &item) override;
+    [[nodiscard]] std::vector<std::shared_ptr<ItemStack>> getContents() const override;
+    [[nodiscard]] int first(ItemStack &item) override;
+    [[nodiscard]] bool isEmpty() const override;
+    void clear() override;
 
 private:
     ::Container &container_;

include/endstone/detail/inventory/player_inventory.h

@@ -28,6 +28,11 @@ class EndstonePlayerInventory : public EndstoneInventory, public PlayerInventory
     [[nodiscard]] int getMaxStackSize() const override;
     [[nodiscard]] std::shared_ptr<ItemStack> getItem(int index) const override;
     void setItem(int index, std::shared_ptr<ItemStack> item) override;
+    void addItem(ItemStack &item) override;
+    [[nodiscard]] std::vector<std::shared_ptr<ItemStack>> getContents() const override;
+    [[nodiscard]] int first(ItemStack &item) override;
+    [[nodiscard]] bool isEmpty() const override;
+    void clear() override;
 
 private:
     ::Player &holder_;

include/endstone/inventory/inventory.h

@@ -15,6 +15,7 @@
 #pragma once
 
 #include <memory>
+#include <vector>
 
 #include "endstone/inventory/item_stack.h"
 
@@ -54,5 +55,41 @@ class Inventory {
      * @param item The ItemStack to set
      */
     virtual void setItem(int index, std::shared_ptr<ItemStack> item) = 0;
+
+    /**
+     * @brief Stores the given ItemStacks in the inventory. This will try to fill
+     * existing stacks and empty slots as well as it can.
+     *
+     * @param item The ItemStack to add
+     */
+    virtual void addItem(ItemStack &item) = 0;
+
+    /**
+     * @brief Returns all ItemStacks from the inventory
+     *
+     * @return An array of ItemStacks from the inventory. Individual items may be null.
+     */
+    [[nodiscard]] virtual std::vector<std::shared_ptr<ItemStack>> getContents() const = 0;
+
+    /**
+     * @brief Returns the first slot in the inventory containing an ItemStack with the given stack.
+     *
+     * @param item The ItemStack to match against
+     * @return The slot index of the given ItemStack or -1 if not found
+     */
+    [[nodiscard]] virtual int first(ItemStack &item) = 0;
+
+    /**
+     * @brief Check whether this inventory is empty. An inventory is considered
+     * to be empty if there are no ItemStacks in any slot of this inventory.
+     *
+     * @return true if empty, false otherwise
+     */
+    [[nodiscard]] virtual bool isEmpty() const = 0;
+
+    /**
+     * @brief Clears out the whole Inventory.
+     */
+    virtual void clear() = 0;
 };
 }  // namespace endstone

python/src/endstone/_internal/endstone_python.pyi

@@ -1072,6 +1072,30 @@ class Inventory:
     """
     Interface to the various inventories.
     """
+    def __get_item__(self, index: int) -> ItemStack:
+        """
+        Returns the ItemStack found in the slot at the given index
+        """
+    def __len__(self) -> int:
+        """
+        Returns the size of the inventory
+        """
+    def __set_item__(self, index: int, item: ItemStack | None) -> None:
+        """
+        Stores the ItemStack at the given index of the inventory.
+        """
+    def add_item(self, item: ItemStack) -> None:
+        """
+        Stores the given ItemStacks in the inventory. This will try to fill existing stacks and empty slots as well as it can.
+        """
+    def clear(self) -> None:
+        """
+        Clears out the whole Inventory.
+        """
+    def first(self, item: ItemStack) -> int:
+        """
+        Returns the first slot in the inventory containing an ItemStack with the given stack.
+        """
     def get_item(self, index: int) -> ItemStack:
         """
         Returns the ItemStack found in the slot at the given index
@@ -1081,6 +1105,16 @@ class Inventory:
         Stores the ItemStack at the given index of the inventory.
         """
     @property
+    def contents(self) -> list[ItemStack]:
+        """
+        Returns all ItemStacks from the inventory
+        """
+    @property
+    def is_empty(self) -> bool:
+        """
+         Check whether this inventory is empty. An inventory is considered to be empty if there are no ItemStacks in any slot of this inventory.
+        """
+    @property
     def max_stack_size(self) -> int:
         """
         Returns the maximum stack size for an ItemStack in this inventory.

src/endstone_core/inventory/inventory.cpp

@@ -37,7 +37,42 @@ std::shared_ptr<ItemStack> EndstoneInventory::getItem(int index) const
 
 void EndstoneInventory::setItem(int index, std::shared_ptr<ItemStack> item)
 {
-    container_.setItem(index, *EndstoneItemStack::toMinecraft(item));
+    container_.setItemWithForceBalance(index, *EndstoneItemStack::toMinecraft(item), true);
+}
+
+void EndstoneInventory::addItem(ItemStack &item)
+{
+    container_.addItemWithForceBalance(*EndstoneItemStack::toMinecraft(item.shared_from_this()));
+}
+
+std::vector<std::shared_ptr<ItemStack>> EndstoneInventory::getContents() const
+{
+    const auto slots = container_.getSlots();
+    std::vector<std::shared_ptr<ItemStack>> contents;
+    for (const auto &slot : slots) {
+        if (slot && !slot->isNull()) {
+            contents.push_back(EndstoneItemStack::fromMinecraft(const_cast<::ItemStack &>(*slot)));
+        }
+        else {
+            contents.push_back(nullptr);
+        }
+    }
+    return contents;
+}
+
+int EndstoneInventory::first(ItemStack &item)
+{
+    return container_.findFirstSlotForItem(*EndstoneItemStack::toMinecraft(item.shared_from_this()));
+}
+
+bool EndstoneInventory::isEmpty() const
+{
+    return container_.isEmpty();
+}
+
+void EndstoneInventory::clear()
+{
+    container_.removeAllItems();
 }
 
 }  // namespace endstone::detail

src/endstone_core/inventory/player_inventory.cpp

@@ -37,4 +37,29 @@ void EndstonePlayerInventory::setItem(int index, std::shared_ptr<ItemStack> item
     holder_.sendInventory(false);
 }
 
+void EndstonePlayerInventory::addItem(ItemStack &item)
+{
+    EndstoneInventory::addItem(item);
+}
+
+std::vector<std::shared_ptr<ItemStack>> EndstonePlayerInventory::getContents() const
+{
+    return EndstoneInventory::getContents();
+}
+
+int EndstonePlayerInventory::first(ItemStack &item)
+{
+    return EndstoneInventory::first(item);
+}
+
+bool EndstonePlayerInventory::isEmpty() const
+{
+    return EndstoneInventory::isEmpty();
+}
+
+void EndstonePlayerInventory::clear()
+{
+    EndstoneInventory::clear();
+}
+
 }  // namespace endstone::detail

src/endstone_python/inventory.cpp

@@ -44,6 +44,25 @@ void init_inventory(py::module_ &m)
             [](Inventory &self, int index, std::optional<std::shared_ptr<ItemStack>> item) {
                 self.setItem(index, item.value_or(nullptr));
             },
+            py::arg("index"), py::arg("item"), "Stores the ItemStack at the given index of the inventory.")
+        .def("add_item", &Inventory::addItem, py::arg("item"),
+             "Stores the given ItemStacks in the inventory. This will try to fill existing stacks and empty slots as "
+             "well as it can.")
+        .def_property_readonly("contents", &Inventory::getContents, "Returns all ItemStacks from the inventory")
+        .def("first", &Inventory::first, py::arg("item"),
+             "Returns the first slot in the inventory containing an ItemStack with the given stack.")
+        .def_property_readonly("is_empty", &Inventory::isEmpty,
+                               " Check whether this inventory is empty. An inventory is considered to be empty if "
+                               "there are no ItemStacks in any slot of this inventory.")
+        .def("clear", &Inventory::clear, "Clears out the whole Inventory.")
+        .def("__len__", &Inventory::getSize, "Returns the size of the inventory")
+        .def("__get_item__", &Inventory::getItem, py::arg("index"),
+             "Returns the ItemStack found in the slot at the given index")
+        .def(
+            "__set_item__",
+            [](Inventory &self, int index, std::optional<std::shared_ptr<ItemStack>> item) {
+                self.setItem(index, item.value_or(nullptr));
+            },
             py::arg("index"), py::arg("item"), "Stores the ItemStack at the given index of the inventory.");
 
     py::class_<PlayerInventory, Inventory>(