Skip to content

Commit

Permalink
Document inventories (#3641)
Browse files Browse the repository at this point in the history
  • Loading branch information
apple502j authored Aug 24, 2023
1 parent 7701c0d commit 2af369c
Show file tree
Hide file tree
Showing 11 changed files with 242 additions and 16 deletions.
1 change: 1 addition & 0 deletions mappings/net/minecraft/inventory/CraftingInventory.mapping
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
CLASS net/minecraft/class_1715 net/minecraft/inventory/CraftingInventory
COMMENT Represents an inventory for crafting inputs.
FIELD field_7802 handler Lnet/minecraft/class_1703;
FIELD field_7803 height I
FIELD field_7804 width I
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
CLASS net/minecraft/class_1731 net/minecraft/inventory/CraftingResultInventory
COMMENT Represents an inventory for the crafting output slot.
FIELD field_7865 lastRecipe Lnet/minecraft/class_1860;
FIELD field_7866 stacks Lnet/minecraft/class_2371;
6 changes: 6 additions & 0 deletions mappings/net/minecraft/inventory/DoubleInventory.mapping
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
CLASS net/minecraft/class_1258 net/minecraft/inventory/DoubleInventory
COMMENT Represents a combined inventory that is backed by two inventories.
COMMENT This is used by double chests.
COMMENT
COMMENT <p>It is possible to nest this inventory to create triple or quadruple
COMMENT inventories.
FIELD field_5769 first Lnet/minecraft/class_1263;
FIELD field_5771 second Lnet/minecraft/class_1263;
METHOD <init> (Lnet/minecraft/class_1263;Lnet/minecraft/class_1263;)V
ARG 1 first
ARG 2 second
METHOD method_5405 isPart (Lnet/minecraft/class_1263;)Z
COMMENT {@return whether {@code inventory} is part of the combined inventory}
ARG 1 inventory
6 changes: 6 additions & 0 deletions mappings/net/minecraft/inventory/EnderChestInventory.mapping
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
CLASS net/minecraft/class_1730 net/minecraft/inventory/EnderChestInventory
COMMENT Represents an inventory used for ender chests.
COMMENT A new instance is created for each player.
FIELD field_7864 activeBlockEntity Lnet/minecraft/class_2611;
METHOD method_31556 isActiveBlockEntity (Lnet/minecraft/class_2611;)Z
COMMENT {@return whether this inventory is being accessed from {@code blockEntity}}
ARG 1 blockEntity
METHOD method_7661 setActiveBlockEntity (Lnet/minecraft/class_2611;)V
COMMENT Sets the block entity the player is using to access the inventory to {@code
COMMENT blockEntity}. The block entity is used to delegate {@link #canPlayerUse},
COMMENT {@link #onOpen}, and {@link #onClose}.
ARG 1 blockEntity
48 changes: 48 additions & 0 deletions mappings/net/minecraft/inventory/Inventories.mapping
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
CLASS net/minecraft/class_1262 net/minecraft/inventory/Inventories
COMMENT Contains utility methods used by {@link Inventory} implementations or for working
COMMENT with inventories.
METHOD method_29234 remove (Lnet/minecraft/class_1263;Ljava/util/function/Predicate;IZ)I
COMMENT Removes a number, not exceeding {@code maxCount}, of items from an inventory based on a predicate and returns that number.
COMMENT @return the number of items removed
Expand All @@ -16,19 +18,65 @@ CLASS net/minecraft/class_1262 net/minecraft/inventory/Inventories
ARG 3 dryRun
COMMENT whether to return the number of items which would have been removed without actually removing them
METHOD method_5426 writeNbt (Lnet/minecraft/class_2487;Lnet/minecraft/class_2371;)Lnet/minecraft/class_2487;
COMMENT Writes the inventory to {@code nbt}. This method will always write to the NBT,
COMMENT even if {@code stacks} only contains empty stacks.
COMMENT
COMMENT <p>See {@link #writeNbt(NbtCompound, DefaultedList, boolean)} for the serialization
COMMENT format.
COMMENT
COMMENT @see #readNbt(NbtCompound, DefaultedList)
COMMENT @see #writeNbt(NbtCompound, DefaultedList, boolean)
COMMENT @return the passed {@code nbt}
ARG 0 nbt
ARG 1 stacks
METHOD method_5427 writeNbt (Lnet/minecraft/class_2487;Lnet/minecraft/class_2371;Z)Lnet/minecraft/class_2487;
COMMENT Writes the inventory to {@code nbt}.
COMMENT
COMMENT <p>The inventory is serialized as a list of non-empty {@linkplain ItemStack#writeNbt
COMMENT item stacks}. In addition, each compound has a byte entry with the key {@code Slot},
COMMENT indicating the slot. The list is then written to {@code nbt} under the key {@code
COMMENT Items}.
COMMENT
COMMENT <p>If {@code setIfEmpty} is {@code false} and each stack in {@code stacks} is empty,
COMMENT then {@code nbt} will not be modified at all. Otherwise, the {@code Items} entry
COMMENT will always be present.
COMMENT
COMMENT @see #readNbt(NbtCompound, DefaultedList)
COMMENT @return the passed {@code nbt}
ARG 0 nbt
ARG 1 stacks
ARG 2 setIfEmpty
METHOD method_5428 removeStack (Ljava/util/List;I)Lnet/minecraft/class_1799;
COMMENT Sets the stack at {@code slot} to {@link ItemStack#EMPTY} and returns the old stack.
COMMENT
COMMENT <p>This returns {@link ItemStack#EMPTY} when {@code slot} is out of bounds.
COMMENT
COMMENT @apiNote This is used to implement {@link Inventory#removeStack(int)}.
COMMENT This should not otherwise be used directly.
COMMENT
COMMENT @returns the stack previously at {@code slot}
ARG 0 stacks
ARG 1 slot
METHOD method_5429 readNbt (Lnet/minecraft/class_2487;Lnet/minecraft/class_2371;)V
COMMENT Reads {@code nbt} and sets the elements of {@code stacks} accordingly.
COMMENT
COMMENT <p>See {@link #writeNbt(NbtCompound, DefaultedList, boolean)} for the serialization
COMMENT format. If the slot is out of bounds, it is ignored.
COMMENT
COMMENT @see #writeNbt(NbtCompound, DefaultedList)
COMMENT @see #writeNbt(NbtCompound, DefaultedList, boolean)
ARG 0 nbt
ARG 1 stacks
METHOD method_5430 splitStack (Ljava/util/List;II)Lnet/minecraft/class_1799;
COMMENT {@return the copy of the stack split from the stack at {@code slot}}
COMMENT
COMMENT <p>This returns {@link ItemStack#EMPTY} when {@code slot} is out of bounds,
COMMENT the stack at the slot is empty, or when {@code amount <= 0}.
COMMENT
COMMENT @apiNote This is used to implement {@link Inventory#removeStack(int, int)}.
COMMENT This should not otherwise be used directly.
COMMENT
COMMENT @see ItemStack#split(int)
ARG 0 stacks
ARG 1 slot
ARG 2 amount
132 changes: 120 additions & 12 deletions mappings/net/minecraft/inventory/Inventory.mapping
Original file line number Diff line number Diff line change
@@ -1,60 +1,168 @@
CLASS net/minecraft/class_1263 net/minecraft/inventory/Inventory
COMMENT A container of {@link ItemStack}s. In general, when a player stores an item stack
COMMENT and can retrieve the same item stack back, that stack is stored in an
COMMENT inventory. The inventory can be persistent, like chests or donkeys, or it can
COMMENT be created without backing storage, like the slots in crafting tables.
COMMENT It is the responsibility of the user to sync or save the contents of the
COMMENT inventory.
COMMENT
COMMENT <p>Entities and block entities that can hold item stacks generally
COMMENT implement this interface themselves, allowing hopper interactions. Call {@link
COMMENT net.minecraft.entity.player.PlayerEntity#getInventory} to get the player's
COMMENT inventory (including armors and offhand).
COMMENT
COMMENT <p>An inventory has a fixed size, and each element in the inventory is identified
COMMENT by the slot number, which is between zero and {@code size() - 1} like arrays.
COMMENT When a slot of the inventory is empty, it should be filled with {@link
COMMENT ItemStack#EMPTY}.
COMMENT
COMMENT <p>An implementation of this interface should have a field of {@link
COMMENT net.minecraft.util.collection.DefaultedList#ofSize(int, Object)} with the second
COMMENT argument as {@link ItemStack#EMPTY}, and implement methods by delegating to the
COMMENT list. The list itself should not be modified directly, and the list's size
COMMENT should remain constant throughout the lifetime of the inventory.
COMMENT Implementations must call {@link #markDirty} when the inventory is modified.
COMMENT
COMMENT @apiNote If an inventory is needed for temporary storage, use {@link
COMMENT SimpleInventory}. For persistent storage in entities or block entities,
COMMENT use {@link net.minecraft.entity.vehicle.VehicleInventory} or
COMMENT {@link net.minecraft.block.entity.LockableContainerBlockEntity}.
COMMENT
COMMENT @see net.minecraft.entity.vehicle.VehicleInventory
COMMENT @see net.minecraft.block.entity.LockableContainerBlockEntity
FIELD field_29952 MAX_COUNT_PER_STACK I
METHOD method_18861 count (Lnet/minecraft/class_1792;)I
COMMENT Returns the number of times the specified item occurs in this inventory across all stored stacks.
COMMENT {@return the number of times {@code item} occurs in this inventory
COMMENT across all stored stacks}
ARG 1 item
METHOD method_18862 containsAny (Ljava/util/Set;)Z
COMMENT Determines whether this inventory contains any of the given candidate items.
COMMENT {@return whether this inventory contains any of {@code items}}
COMMENT
COMMENT @see #containsAny(Predicate)
ARG 1 items
METHOD method_43255 (Ljava/util/Set;Lnet/minecraft/class_1799;)Z
ARG 1 stack
METHOD method_43256 containsAny (Ljava/util/function/Predicate;)Z
COMMENT {@return whether this inventory contains any of the stacks matching {@code
COMMENT predicate}}
COMMENT
COMMENT @see #containsAny(Set)
ARG 1 predicate
METHOD method_49104 canTransferTo (Lnet/minecraft/class_1263;ILnet/minecraft/class_1799;)Z
COMMENT {@return whether a hopper can transfer {@code stack} from {@code slot} to
COMMENT the hopper}
COMMENT
COMMENT <p>This returns {@code true} by default.
ARG 1 hopperInventory
ARG 2 slot
ARG 3 stack
METHOD method_49105 canPlayerUse (Lnet/minecraft/class_2586;Lnet/minecraft/class_1657;)Z
COMMENT {@return whether {@code player} can use this {@code blockEntity}}
COMMENT
COMMENT @apiNote This is used by block entities to implement {@link
COMMENT #canPlayerUse(PlayerEntity)}.
COMMENT
COMMENT @implNote This method checks whether the given block entity exists and whether
COMMENT the player is within 8 blocks of the block entity.
COMMENT
COMMENT @see #canPlayerUse(BlockEntity, PlayerEntity, int)
ARG 0 blockEntity
ARG 1 player
METHOD method_49106 canPlayerUse (Lnet/minecraft/class_2586;Lnet/minecraft/class_1657;I)Z
COMMENT {@return whether {@code player} can use this {@code blockEntity}}
COMMENT
COMMENT @apiNote This is used by block entities to implement {@link
COMMENT #canPlayerUse(PlayerEntity)}.
COMMENT
COMMENT @implNote This method checks whether the given block entity exists and whether
COMMENT the player is within {@code range} blocks of the block entity.
COMMENT
COMMENT @see #canPlayerUse(BlockEntity, PlayerEntity)
ARG 0 blockEntity
ARG 1 player
ARG 2 range
METHOD method_5431 markDirty ()V
COMMENT Marks the inventory as modified. Implementations should call this method
COMMENT every time the inventory is changed in any way.
COMMENT
COMMENT @apiNote Implementations should mark the inventory for synchronization or
COMMENT saving in this method. Since this is called frequently, it is not recommended to
COMMENT synchronize or save the inventory directly in this method. If this inventory is
COMMENT implemented in a block entity, then it should <strong>always</strong> call
COMMENT {@code super.markDirty();} to ensure the block entity gets saved.
COMMENT
COMMENT @see net.minecraft.block.entiy.BlockEntity#markDirty
METHOD method_5432 onClose (Lnet/minecraft/class_1657;)V
COMMENT Called when the inventory is closed. Specifically, this is called inside
COMMENT {@link net.minecraft.screen.ScreenHandler#onClosed}. This does nothing
COMMENT by default.
COMMENT
COMMENT <p>The method is called in both the client and the server. However, because
COMMENT clientside screen handler is created with a {@link SimpleInventory},
COMMENT other implementations can (and the vanilla code does) assume that the method is called
COMMENT in the server.
ARG 1 player
METHOD method_5434 removeStack (II)Lnet/minecraft/class_1799;
COMMENT Removes a specific number of items from the given slot.
COMMENT Removes a specific number of items from {@code slot}.
COMMENT
COMMENT @return the removed items as a stack
ARG 1 slot
ARG 2 amount
METHOD method_5435 onOpen (Lnet/minecraft/class_1657;)V
COMMENT Called when the inventory is opened. Specifically, this is called inside the
COMMENT {@link net.minecraft.screen.ScreenHandler} constructor. This does nothing
COMMENT by default.
COMMENT
COMMENT <p>The method is called in both the client and the server. However, because
COMMENT clientside screen handler is created with a {@link SimpleInventory},
COMMENT other implementations can (and the vanilla code does) assume that the method is called
COMMENT in the server.
ARG 1 player
METHOD method_5437 isValid (ILnet/minecraft/class_1799;)Z
COMMENT Returns whether the given stack is a valid for the indicated slot position.
COMMENT {@return whether {@code stack} is valid for the {@code slot}}
COMMENT
COMMENT <p>Implementations can, for example, use this to check whether the item
COMMENT is in a specific tag. This returns {@code true} by default.
ARG 1 slot
ARG 2 stack
METHOD method_5438 getStack (I)Lnet/minecraft/class_1799;
COMMENT Fetches the stack currently stored at the given slot. If the slot is empty,
COMMENT or is outside the bounds of this inventory, returns see {@link ItemStack#EMPTY}.
COMMENT {@return the stack currently stored at {@code slot}}
COMMENT
COMMENT <p>If the slot is empty, or is outside the bounds of this inventory,
COMMENT this returns {@link ItemStack#EMPTY}.
ARG 1 slot
METHOD method_5439 size ()I
COMMENT {@return the size of the inventory}
COMMENT
COMMENT <p>The inventory should support the slot ID from {@code 0} to {@code size() - 1}.
COMMENT This should remain constant throughout the inventory's lifetime.
METHOD method_5441 removeStack (I)Lnet/minecraft/class_1799;
COMMENT Removes the stack currently stored at the indicated slot.
COMMENT Removes the stack currently stored at {@code slot}.
COMMENT
COMMENT @return the stack previously stored at the indicated slot.
COMMENT @return the stack previously stored at the indicated slot
ARG 1 slot
METHOD method_5442 isEmpty ()Z
COMMENT {@return whether the inventory consists entirely of {@linkplain ItemStack#isEmpty
COMMENT empty item stacks}}
METHOD method_5443 canPlayerUse (Lnet/minecraft/class_1657;)Z
COMMENT {@return whether {@code player} can use this inventory}
COMMENT
COMMENT <p>This is called by {@link net.minecraft.screen.ScreenHandler#canUse}.
COMMENT
COMMENT @apiNote Implementations should check the distance between the inventory
COMMENT holder and {@code player}. For convenience, this interface offers two methods
COMMENT used by block entities to implement this check.
COMMENT
COMMENT @see #canPlayerUse(BlockEntity, PlayerEntity)
COMMENT @see #canPlayerUse(BlockEntity, PlayerEntity, int)
ARG 1 player
METHOD method_5444 getMaxCountPerStack ()I
COMMENT Returns the maximum number of items a stack can contain when placed inside this inventory.
COMMENT No slots may have more than this number of items. It is effectively the
COMMENT stacking limit for this inventory's slots.
COMMENT {@return the maximum {@linkplain ItemStack#getCount number of items} a stack
COMMENT can contain when placed inside this inventory}
COMMENT
COMMENT @return the max {@link ItemStack#getCount() count} of item stacks in this inventory
COMMENT <p>No slots may have more than this number of items. It is effectively the
COMMENT stacking limit for this inventory's slots.
METHOD method_5447 setStack (ILnet/minecraft/class_1799;)V
COMMENT Sets the stack stored at {@code slot} to {@code stack}.
ARG 1 slot
ARG 2 stack
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
CLASS net/minecraft/class_1265 net/minecraft/inventory/InventoryChangedListener
COMMENT A functional interface used in {@link SimpleInventory#addListener}.
COMMENT
COMMENT <p>Other inventories can listen for inventory changes by overriding
COMMENT {@link Inventory#markDirty}.
METHOD method_5453 onInventoryChanged (Lnet/minecraft/class_1263;)V
ARG 1 sender
5 changes: 5 additions & 0 deletions mappings/net/minecraft/inventory/RecipeInputInventory.mapping
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
CLASS net/minecraft/class_8566 net/minecraft/inventory/RecipeInputInventory
COMMENT Represents an inventory that is an input for a recipe, such as
COMMENT crafting table inputs.
METHOD method_17397 getHeight ()I
COMMENT {@return the height of the recipe grid}
METHOD method_17398 getWidth ()I
COMMENT {@return the width of the recipe grid}
METHOD method_51305 getInputStacks ()Ljava/util/List;
COMMENT {@return the stacks held by the inventory}
8 changes: 5 additions & 3 deletions mappings/net/minecraft/inventory/SidedInventory.mapping
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
CLASS net/minecraft/class_1278 net/minecraft/inventory/SidedInventory
COMMENT A special inventory interface for inventories that expose different slots for different sides, such as furnaces.
METHOD method_5492 canInsert (ILnet/minecraft/class_1799;Lnet/minecraft/class_2350;)Z
COMMENT Determines whether the given stack can be inserted into this inventory at the specified slot position from the given direction.
COMMENT {@return whether the given stack can be inserted into this inventory
COMMENT at the specified slot position from the given direction}
ARG 1 slot
ARG 2 stack
ARG 3 dir
METHOD method_5493 canExtract (ILnet/minecraft/class_1799;Lnet/minecraft/class_2350;)Z
COMMENT Determines whether the given stack can be removed from this inventory at the specified slot position from the given direction.
COMMENT {@return whether the given stack can be removed from this inventory at the
COMMENT specified slot position from the given direction}
ARG 1 slot
ARG 2 stack
ARG 3 dir
METHOD method_5494 getAvailableSlots (Lnet/minecraft/class_2350;)[I
COMMENT Gets the available slot positions that are reachable from a given side.
COMMENT {@return the available slot positions that are reachable from a given side}
ARG 1 side
Loading

0 comments on commit 2af369c

Please sign in to comment.