Add first empty slot in inventory expression (#7914)

* Add first empty slot expression

* plural support

* can't forget docs

* Update src/main/java/ch/njol/skript/expressions/ExprFirstEmptySlot.java

Author: sovdeeth

src/main/java/ch/njol/skript/expressions/ExprFirstEmptySlot.java

@@ -0,0 +1,52 @@
+package ch.njol.skript.expressions;
+
+import ch.njol.skript.Skript;
+import ch.njol.skript.doc.*;
+import ch.njol.skript.expressions.base.SimplePropertyExpression;
+import ch.njol.skript.lang.ExpressionType;
+import ch.njol.skript.util.slot.InventorySlot;
+import ch.njol.skript.util.slot.Slot;
+import org.bukkit.inventory.Inventory;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+@Name("First Empty Slot in Inventory")
+@Description("Returns the first empty slot in an inventory. If no empty slot is found, it returns nothing.")
+@Example("set the first empty slot in player's inventory to 5 diamonds")
+@Example("""
+	if the first empty slot in player's inventory is not set:
+		message "No empty slot available in your inventory!" to player
+	""")
+@Since("INSERT VERSION")
+@Keywords({"full", "inventory", "empty", "air", "slot"})
+public class ExprFirstEmptySlot extends SimplePropertyExpression<Inventory, Slot> {
+
+	static {
+		// support `first empty slot in inventory` as well as typical property syntax
+		List<String> patterns = new ArrayList<>(Arrays.asList(getPatterns("first empty slot[s]", "inventories")));
+		patterns.add("[the] first empty slot[s] in %inventories%");
+		Skript.registerExpression(ExprFirstEmptySlot.class, Slot.class, ExpressionType.PROPERTY, patterns.toArray(new String[0]));
+	}
+
+	@Override
+	public @Nullable Slot convert(Inventory from) {
+		int slotIndex = from.firstEmpty();
+		if (slotIndex == -1)
+			return null; // No empty slot found
+		return new InventorySlot(from, slotIndex);
+	}
+
+	@Override
+	public Class<? extends Slot> getReturnType() {
+		return Slot.class;
+	}
+
+	@Override
+	protected String getPropertyName() {
+		return "first empty slot";
+	}
+
+}

src/test/skript/tests/syntaxes/expressions/ExprFirstEmptySlot.sk

@@ -0,0 +1,18 @@
+test "first empty slot":
+	set {_inv} to a chest inventory with 3 rows
+	assert the index of the first empty slot in {_inv} is 0 with "First empty slot in empty inventory should be 0"
+	set slot 0 of {_inv} to a stone
+	assert the index of the first empty slot in {_inv} is 1 with "First empty slot in inventory should be 1"
+	set slot 3 of {_inv} to a stone
+	assert the index of the first empty slot in {_inv} is 1 with "First empty slot in inventory should be 1"
+	set slot 1 of {_inv} to a stone
+	assert the index of the first empty slot in {_inv} is 2 with "First empty slot in inventory should be 2"
+
+	set first empty slot of {_inv} to diamond sword
+	assert slot 2 of {_inv} is a diamond sword with "First empty slot should be set to diamond sword"
+	assert the index of the first empty slot in {_inv} is 4 with "First empty slot in inventory should be 4"
+
+	set {_inv2} to a hopper inventory named "Test Hopper"
+	set the first empty slots in {_inv2} and {_inv} to diamond sword
+	assert slot 0 of {_inv2} is a diamond sword with "First empty slot in hopper inventory should be set to diamond sword"
+	assert slot 4 of {_inv} is a diamond sword with "First empty slot in chest inventory should be set to diamond sword"