specify inventory changes

docs/scarpet/api/Inventories.md

@@ -26,7 +26,8 @@ use the same scheme.
  If the entity or a block doesn't have 
 an inventory, all API functions typically do nothing and return null.
 
-Most items returned are in the form of a triple of item name, count, and nbt or the extra data associated with an item. 
+Most items returned are in the form of a triple of item name, count, and the full nbt of an item. When saving an item, if the
+nbt is provided, it overrides the item type provided in the name.
 
 ### `item_list(tag?)`
 
@@ -139,20 +140,22 @@ negative numbers to indicate slots counted from 'the back'.
 
 <pre>
 inventory_get(player(), 0) => null // nothing in first hotbar slot
-inventory_get(x,y,z, 5) => ['stone', 1, {}]
-inventory_get(player(), -1) => ['diamond_pickaxe', 1, {Damage:4}] // slightly damaged diamond pick in the offhand
+inventory_get(x,y,z, 5) => ['stone', 1, {id:"minecraft:stone"}]
+inventory_get(player(), -1) => ['diamond_pickaxe', 1, {components:{"minecraft:damage":4},id:"minecraft:diamond_pickaxe"}] // slightly damaged diamond pick in the offhand
 </pre>
 
 ### `inventory_set(inventory, slot, count, item?, nbt?)`
 
 Modifies or sets a stack in inventory. specify count 0 to empty the slot. If item is not specified, keeps existing 
-item, just modifies the count. If item is provided - replaces current item. If nbt is provided - adds a tag to the 
-stack at slot. Returns previous stack in that slot.
+item, just modifies the count. If item is provided - replaces current item. If nbt is provided - uses the tag to create the item fully
+ignoring the item name. If nbt is provided and count is not null, the sets the custom count on the tag from the count parameter.
+If count is `null` and item is `null`, an item is entirely defined by the `nbt` parameter. Returns previous stack in that slot.
 
 <pre>
-inventory_set(player(), 0, 0) => ['stone', 64, {}] // player had a stack of stone in first hotbar slot
-inventory_set(player(), 0, 6) => ['diamond', 64, {}] // changed stack of diamonds in player slot to 6
-inventory_set(player(), 0, 1, 'diamond_axe','{Damage:5}') => null //added slightly damaged diamond axe to first player slot
+inventory_set(player(), 0, 0) => ['stone', 64, {id:"minecraft:stone"}] // player had a stack of stone in first hotbar slot
+inventory_set(player(), 0, 6) => ['diamond', 64, {id:"minecraft:diamond"}] // changed stack of diamonds in player slot to 6
+inventory_set(player(), 0, 1, 'diamond_axe','{components:{"minecraft:damage":5},id:"minecraft:diamond_axe"}') => null //added slightly damaged diamond axe to first player slot
+inventory_set(player(), 0, null, null, '{components:{"minecraft:damage":5},id:"minecraft:diamond_axe"}') => null // same effect as above
 </pre>
 
 ### `inventory_find(inventory, item, start_slot?, ), inventory_find(inventory, null, start_slot?)`

src/main/java/carpet/mixins/Inventory_scarpetEventMixin.java

@@ -27,10 +27,11 @@ public abstract class Inventory_scarpetEventMixin
         if (!PLAYER_PICKS_UP_ITEM.isNeeded() || !(player instanceof ServerPlayer))
             return playerInventory.add(-1, stack);
         int count = stack.getCount();
+        ItemStack previous = stack.copy();
         boolean res = playerInventory.add(-1, stack);
         if (count != stack.getCount()) // res returns false for larger item adding to a almost full ineventory
         {
-            ItemStack diffStack = stack.copyWithCount(count - stack.getCount());
+            ItemStack diffStack = previous.copyWithCount(count - stack.getCount());
             PLAYER_PICKS_UP_ITEM.onItemAction((ServerPlayer) player, null, diffStack);
         }
         return res;

src/main/java/carpet/script/utils/ShapeDispatcher.java

@@ -1661,7 +1661,7 @@ public class ShapeDispatcher
         public Value validate(Map<String, Value> options, MinecraftServer server, Value value)
         {
             ItemStack item = ValueConversions.getItemStackFromValue(value, true, server.registryAccess());
-            return new NBTSerializableValue(item.save(server.registryAccess()));
+            return new NBTSerializableValue(item.saveOptional(server.registryAccess()));
         }
 
         @Override

src/main/resources/assets/carpet/scripts/event_test.sc

@@ -313,11 +313,16 @@ __on_player_swaps_hands(player) -> (
 //    print(' Player '+player+' collides with '+entity);
 //);
 
-__on_player_picks_up_item(player, item) ->
+__on_player_picks_up_item(player, item_tuple) ->
 (
+    l(item, count, nbt) = item_tuple || l('None', 0, null);
     print('');
     print('__on_player_picks_up_item(player, item)');
-    print(' Player '+player+' injects '+item);
+    print('  - player: '+player);
+    print('  - item:');
+    print('    > name: '+item);
+    print('    > count: '+count);
+    print('    > nbt: '+nbt);
 );
 
 __on_player_trades(player, entity, buy_left, buy_right, sell) ->