Add Player#give (#11995)

paper-api/src/main/java/io/papermc/paper/entity/PlayerGiveResult.java

@@ -0,0 +1,39 @@
+package io.papermc.paper.entity;
+
+import java.util.Collection;
+import org.bukkit.entity.Item;
+import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.Unmodifiable;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A result type used by {@link org.bukkit.entity.Player#give(ItemStack...)} and its overloads.
+ */
+@NullMarked
+public interface PlayerGiveResult {
+
+    /**
+     * A collection of itemstacks that were not added to the player's inventory as they did not fit.
+     * The collection is derived from the collections of items to add by creating copies of each stack that was not
+     * fully added to the inventory and assigning the non-added count as their amount.
+     * <p>
+     * Itemstacks found here *may* also be found as item entities in the {@link #drops()} collection, as the
+     * give logic may have dropped them.
+     *
+     * @return the unmodifiable collection of itemstacks that are leftover as they could not be added. Each element is a
+     * copy of the input stack they are derived from.
+     */
+    @Unmodifiable
+    Collection<ItemStack> leftovers();
+
+    /**
+     * A collection of item entities dropped as a result of this call to {@link org.bukkit.entity.Player#give(ItemStack...)}.
+     * The item entities contained here are not guaranteed to match the {@link #leftovers()} as plugins may cancel the
+     * spawning of item entities.
+     *
+     * @return the unmodifiable collection of dropped item entities.
+     */
+    @Unmodifiable
+    Collection<Item> drops();
+
+}

paper-api/src/main/java/org/bukkit/entity/Player.java

@@ -6,10 +6,12 @@ import java.time.Duration;
 import java.time.Instant;
 import java.util.Collection;
 import java.util.Date;
+import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import io.papermc.paper.entity.LookAnchor;
+import io.papermc.paper.entity.PlayerGiveResult;
 import org.bukkit.BanEntry;
 import org.bukkit.DyeColor;
 import org.bukkit.Effect;
@@ -3892,4 +3894,38 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
      */
     void sendEntityEffect(org.bukkit.@NotNull EntityEffect effect, @NotNull Entity target);
     // Paper end - entity effect API
+
+    /**
+     * Gives the player the items following full vanilla logic,
+     * making the player drop the items that did not fit into
+     * the inventory.
+     *
+     * @param items the items to give.
+     * @return the result of this method, holding leftovers and spawned items.
+     */
+    default @NotNull PlayerGiveResult give(@NotNull final ItemStack @NotNull ... items) {
+        return this.give(List.of(items));
+    }
+
+    /**
+     * Gives the player those items following full vanilla logic,
+     * making the player drop the items that did not fit into
+     * the inventory.
+     *
+     * @param items the items to give
+     * @return the result of this method, holding leftovers and spawned items.
+     */
+    default @NotNull PlayerGiveResult give(@NotNull final Collection<@NotNull ItemStack> items) {
+        return this.give(items, true);
+    }
+
+    /**
+     * Gives the player those items following full vanilla logic.
+     *
+     * @param items      the items to give
+     * @param dropIfFull whether the player should drop items that
+     *                   did not fit the inventory
+     * @return the result of this method, holding leftovers and spawned items.
+     */
+    @NotNull PlayerGiveResult give(@NotNull Collection<@NotNull ItemStack> items, boolean dropIfFull);
 }