Inventory

endstone.inventory

Classes relating to player inventories and item interactions.

Classes:

Name	Description
BookMeta	Represents the meta for a written book that can have a title, an author, and pages.
BookMetaGeneration
CrossbowMeta	Represents the meta for a crossbow that can have a charged projectile.
EquipmentSlot
Inventory	Interface to the various inventories.
ItemFactory	An interface to the methods used to create item metadata.
ItemMeta	Represents the metadata of a generic item.
ItemStack	Represents a stack of items.
ItemType	Represents an item type.
MapMeta	Represents the metadata for a map item.
PlayerInventory	Interface to the inventory of a Player, including the four armor slots and any extra slots.
WritableBookMeta	Represents the meta for a writable book that can have pages.

BookMeta

Bases: WritableBookMeta

Represents the meta for a written book that can have a title, an author, and pages.

Attributes:

Name	Type	Description
author	str	The author of the book.
generation	BookMetaGeneration | None	The generation of the book.
has_author	bool	Whether the book has an author.
has_generation	bool	Whether the book has a generation level.
has_title	bool	Whether the book has a title.
title	str	The title of the book.

author property writable

author: str

The author of the book.

generation property writable

generation: BookMetaGeneration | None

The generation of the book.

has_author property

has_author: bool

Whether the book has an author.

has_generation property

has_generation: bool

Whether the book has a generation level.

has_title property

has_title: bool

Whether the book has a title.

title property writable

title: str

The title of the book.

BookMetaGeneration

Bases: Enum

Attributes:

Name	Type	Description
COPY_OF_COPY
COPY_OF_ORIGINAL
ORIGINAL

COPY_OF_COPY class-attribute instance-attribute

COPY_OF_COPY = 2

COPY_OF_ORIGINAL class-attribute instance-attribute

COPY_OF_ORIGINAL = 1

ORIGINAL class-attribute instance-attribute

ORIGINAL = 0

CrossbowMeta

Bases: ItemMeta

Represents the meta for a crossbow that can have a charged projectile.

Attributes:

Name	Type	Description
charged_projectile	ItemStack | None	The charged projectile, or None if none.
has_charged_projectile	bool	Whether the crossbow has a charged projectile.

charged_projectile property writable

charged_projectile: ItemStack | None

The charged projectile, or None if none.

has_charged_projectile property

has_charged_projectile: bool

Whether the crossbow has a charged projectile.

EquipmentSlot

Bases: Enum

Attributes:

Name	Type	Description
BODY		Only for certain entities such as horses and wolves.
CHEST
FEET
HAND
HEAD
LEGS
OFF_HAND

BODY class-attribute instance-attribute

BODY = 6

Only for certain entities such as horses and wolves.

CHEST class-attribute instance-attribute

CHEST = 4

FEET class-attribute instance-attribute

FEET = 2

HAND class-attribute instance-attribute

HAND = 0

HEAD class-attribute instance-attribute

HEAD = 5

LEGS class-attribute instance-attribute

LEGS = 3

OFF_HAND class-attribute instance-attribute

OFF_HAND = 1

Inventory

Interface to the various inventories.

Methods:

Name	Description
add_item	Stores the given ItemStack objects in the inventory.
all
clear
contains
contains_at_least
first
get_item	Returns the ItemStack found in the slot at the given index.
remove
remove_item	Removes the given ItemStack objects from the inventory.
set_item	Stores the ItemStack at the given index of the inventory.

Attributes:

Name	Type	Description
contents	list[ItemStack | None]	All ItemStack objects from the inventory. Empty slots are represented as None.
first_empty	int	The first empty Slot found, or -1 if no empty slots.
is_empty	bool	Whether this inventory is empty.
max_stack_size	int	The maximum stack size for an ItemStack in this inventory.
size	int	The size of the inventory.

contents property writable

contents: list[ItemStack | None]

All ItemStack objects from the inventory. Empty slots are represented as None.

first_empty property

first_empty: int

The first empty Slot found, or -1 if no empty slots.

is_empty property

is_empty: bool

Whether this inventory is empty.

An inventory is considered to be empty if there are no ItemStack objects in any slot of this inventory.

max_stack_size property

max_stack_size: int

The maximum stack size for an ItemStack in this inventory.

size property

size: int

The size of the inventory.

add_item

add_item(*args) -> dict[int, ItemStack]

Stores the given ItemStack objects in the inventory.

Note

This will try to fill existing stacks and empty slots as well as it can.

Note

The returned map contains what it couldn't store, where the key is the index, and the value is the ItemStack. If all items are stored, it will return an empty dict.

Returns:

Type	Description
dict[int, ItemStack]	A map containing items that couldn't be added.

all

all(item: ItemStack) -> dict[int, ItemStack]

all(
    type: Identifier[ItemType] | str,
) -> dict[int, ItemStack]

clear

clear(index: int) -> None

clear() -> None

contains

contains(item: ItemStack, amount: int) -> bool

contains(item: ItemStack) -> bool

contains(type: Identifier[ItemType] | str) -> bool

contains_at_least

contains_at_least(item: ItemStack, amount: int) -> bool

contains_at_least(
    type: Identifier[ItemType] | str, amount: int
) -> bool

first

first(item: ItemStack) -> int

first(type: Identifier[ItemType] | str) -> int

get_item

get_item(index: int) -> ItemStack | None

Returns the ItemStack found in the slot at the given index.

Parameters:

Name	Type	Description	Default
index	int	The index of the Slot's ItemStack to return.	required

Returns:

Type	Description
ItemStack | None	The ItemStack in the slot.

remove

remove(item: ItemStack) -> None

remove(type: Identifier[ItemType] | str) -> None

remove_item

remove_item(*args) -> dict[int, ItemStack]

Removes the given ItemStack objects from the inventory.

Note

It will try to remove 'as much as possible' from the types and amounts you give as arguments.

Note

The returned map contains what it couldn't remove, where the key is the index, and the value is the ItemStack. If all the given ItemStack objects are removed, it will return an empty dict.

Returns:

Type	Description
dict[int, ItemStack]	A map containing items that couldn't be removed.

set_item

set_item(index: int, item: ItemStack | None) -> None

Stores the ItemStack at the given index of the inventory.

Parameters:

Name	Type	Description	Default
index	int	The index where to put the ItemStack.	required
item	ItemStack | None	The ItemStack to set.	required

ItemFactory

An interface to the methods used to create item metadata.

Methods:

Name	Description
as_meta_for	Returns an appropriate item meta for the specified item type.
equals	This method is used to compare two ItemMeta objects.
get_item_meta	This creates a new item meta for the item type.
is_applicable	This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified ItemStack.

as_meta_for

as_meta_for(
    meta: ItemMeta, type: Identifier[ItemType] | str
) -> ItemMeta

Returns an appropriate item meta for the specified item type.

The item meta returned will always be a valid meta for a given ItemStack of the specified item type. It may be a more or less specific meta, and could also be the same meta or meta type as the parameter. The item meta returned will also always be the most appropriate meta.

Parameters:

Name	Type	Description	Default
meta	ItemMeta	The meta to convert.	required
type	Identifier[ItemType] | str	The item type to convert the meta for.	required

Returns:

Type	Description
ItemMeta	An appropriate item meta for the specified item type.

equals

equals(meta1: ItemMeta, meta2: ItemMeta) -> bool

This method is used to compare two ItemMeta objects.

Parameters:

Name	Type	Description	Default
meta1	ItemMeta	First meta to compare; may be None to indicate no data.	required
meta2	ItemMeta	Second meta to compare; may be None to indicate no data.	required

Returns:

Type	Description
bool	False if one of the meta has data the other does not, otherwise True.

get_item_meta

get_item_meta(type: Identifier[ItemType] | str) -> ItemMeta

This creates a new item meta for the item type.

Parameters:

Name	Type	Description	Default
type	Identifier[ItemType] | str	The item type to consider as base for the meta.	required

Returns:

Type	Description
ItemMeta	A new ItemMeta that could be applied to an item stack of the specified item type.

is_applicable

is_applicable(
    meta: ItemMeta, type: Identifier[ItemType] | str
) -> bool

This method checks the item meta to confirm that it is applicable (no data lost if applied) to the specified ItemStack.

Parameters:

Name	Type	Description	Default
meta	ItemMeta	Meta to check.	required
type	Identifier[ItemType] | str	The item type that meta will be applied to.	required

Returns:

Type	Description
bool	True if the meta can be applied without losing data, False otherwise.

ItemMeta

Represents the metadata of a generic item.

Methods:

Name	Description
add_enchant	Adds the specified enchantment to this item meta.
clone	Creates a clone of the current metadata.
get_enchant_level	Checks for the level of the specified enchantment.
has_enchant	Checks for existence of the specified enchantment.
remove_enchant	Removes the specified enchantment from this item meta.
remove_enchants	Removes all enchantments from this item meta.

Attributes:

Name	Type	Description
damage	int	The damage.
display_name	str	The display name that is set.
enchants	dict[Enchantment, int]	Returns a copy of the enchantments in this ItemMeta.
has_damage	bool	Whether this item has damage.
has_display_name	bool	Whether this has a display name.
has_enchants	bool	Whether an enchantment exists on this meta.
has_lore	bool	Whether this has lore.
has_repair_cost	bool	Whether this item has a repair penalty.
is_unbreakable	bool	The unbreakable tag. An unbreakable item will not lose durability.
lore	list[str]	The lore for this item.
repair_cost	int	The repair penalty.

damage property writable

damage: int

The damage.

display_name property writable

display_name: str

The display name that is set.

enchants property

enchants: dict[Enchantment, int]

Returns a copy of the enchantments in this ItemMeta.

Returns an empty map if none.

has_damage property

has_damage: bool

Whether this item has damage.

has_display_name property

has_display_name: bool

Whether this has a display name.

has_enchants property

has_enchants: bool

Whether an enchantment exists on this meta.

has_lore property

has_lore: bool

Whether this has lore.

has_repair_cost property

has_repair_cost: bool

Whether this item has a repair penalty.

is_unbreakable property writable

is_unbreakable: bool

The unbreakable tag. An unbreakable item will not lose durability.

lore property writable

lore: list[str]

The lore for this item.

repair_cost property writable

repair_cost: int

The repair penalty.

add_enchant

add_enchant(
    id: Identifier[Enchantment] | str,
    level: int,
    force: bool = False,
) -> bool

Adds the specified enchantment to this item meta.

Parameters:

Name	Type	Description	Default
id	Identifier[Enchantment] | str	Enchantment id to add.	required
level	int	Level for the enchantment.	required
force	bool	This indicates the enchantment should be applied, ignoring the level limit.	False

Returns:

Type	Description
bool	True if the item meta changed as a result of this call, False otherwise.

clone

clone() -> ItemMeta

Creates a clone of the current metadata.

Returns:

Type	Description
ItemMeta	A copy of the metadata containing the same state as the original.

get_enchant_level

get_enchant_level(id: Identifier[Enchantment] | str) -> int

Checks for the level of the specified enchantment.

Parameters:

Name	Type	Description	Default
id	Identifier[Enchantment] | str	Enchantment id to check.	required

Returns:

Type	Description
int	The level that the specified enchantment has, or 0 if none.

has_enchant

has_enchant(id: Identifier[Enchantment] | str) -> bool

Checks for existence of the specified enchantment.

Parameters:

Name	Type	Description	Default
id	Identifier[Enchantment] | str	Enchantment id to check.	required

Returns:

Type	Description
bool	True if this enchantment exists for this meta.

remove_enchant

remove_enchant(id: Identifier[Enchantment] | str) -> bool

Removes the specified enchantment from this item meta.

Parameters:

Name	Type	Description	Default
id	Identifier[Enchantment] | str	Enchantment id to remove.	required

Returns:

Type	Description
bool	True if the item meta changed as a result of this call, False otherwise.

remove_enchants

remove_enchants() -> None

Removes all enchantments from this item meta.

ItemStack

ItemStack(
    type: Identifier[ItemType] | str,
    amount: int = 1,
    data: int = 0,
)

Represents a stack of items.

Methods:

Name	Description
is_similar	Checks if the two stacks are equal, but does not consider stack size (amount).
set_item_meta	Set the ItemMeta of this ItemStack.

Attributes:

Name	Type	Description
amount	int	The amount of items in this stack.
data	int	The data for this stack of items.
item_meta	ItemMeta	A copy of the ItemMeta of this ItemStack.
max_stack_size	int	The maximum stack size for this item.
nbt	CompoundTag	The NBT compound tag of this item stack.
translation_key	str	The translation key for this item.
type	ItemType	The type of this item.

amount property writable

amount: int

The amount of items in this stack.

data property writable

data: int

The data for this stack of items.

item_meta property

item_meta: ItemMeta

A copy of the ItemMeta of this ItemStack.

max_stack_size property

max_stack_size: int

The maximum stack size for this item.

nbt property writable

nbt: CompoundTag

The NBT compound tag of this item stack.

translation_key property

translation_key: str

The translation key for this item.

type property writable

type: ItemType

The type of this item.

is_similar

is_similar(other: ItemStack) -> bool

Checks if the two stacks are equal, but does not consider stack size (amount).

Parameters:

Name	Type	Description	Default
other	ItemStack	The item stack to compare to.	required

Returns:

Type	Description
bool	True if the two stacks are equal, ignoring the amount.

set_item_meta

set_item_meta(meta: ItemMeta) -> bool

Set the ItemMeta of this ItemStack.

Parameters:

Name	Type	Description	Default
meta	ItemMeta	New ItemMeta, or None to clear the metadata.	required

Returns:

Type	Description
bool	True if successfully applied ItemMeta.

ItemType

Represents an item type.

Methods:

Name	Description
create_item_stack	Constructs a new ItemStack with this item type.
get	Attempts to get the ItemType with the given name.
get_translation_key	Get the translation key, suitable for use in a translation component.

Attributes:

Name	Type	Description
id	Identifier[ItemType]	The identifier of this item type.
max_durability	int	The maximum durability of this item type.
max_stack_size	int	The maximum amount of this item type that can be held in a stack.
translation_key	str	The translation key, suitable for use in a translation component.

id property

id: Identifier[ItemType]

The identifier of this item type.

max_durability property

max_durability: int

The maximum durability of this item type.

max_stack_size property

max_stack_size: int

The maximum amount of this item type that can be held in a stack.

translation_key property

translation_key: str

The translation key, suitable for use in a translation component.

create_item_stack

create_item_stack(amount: int = 1) -> ItemStack

Constructs a new ItemStack with this item type.

Parameters:

Name	Type	Description	Default
amount	int	The amount in the stack.	1

Returns:

Type	Description
ItemStack	An ItemStack of this item type.

get staticmethod

get(name: Identifier[ItemType] | str) -> ItemType

Attempts to get the ItemType with the given name.

get_translation_key

get_translation_key(data: int = 0) -> str

Get the translation key, suitable for use in a translation component.

Parameters:

Name	Type	Description	Default
data	int	Data for this item type.	0

Returns:

Type	Description
str	The translation key.

MapMeta

Bases: ItemMeta

Represents the metadata for a map item.

Attributes:

Name	Type	Description
has_map_id	bool	Whether this has a map ID number.
has_map_view	bool	Whether this item has an associated map.
map_id	int	The map ID. This is used to determine what map is displayed.
map_view	MapView	The map view associated with this map item.

has_map_id property

has_map_id: bool

Whether this has a map ID number.

has_map_view property

has_map_view: bool

Whether this item has an associated map.

map_id property writable

map_id: int

The map ID. This is used to determine what map is displayed.

map_view property writable

map_view: MapView

The map view associated with this map item.

PlayerInventory

Bases: Inventory

Interface to the inventory of a Player, including the four armor slots and any extra slots.

Attributes:

Name	Type	Description
boots	ItemStack | None	The ItemStack in the boots slot.
chestplate	ItemStack | None	The ItemStack in the chestplate slot.
held_item_slot	int	The slot number of the currently held item.
helmet	ItemStack | None	The ItemStack in the helmet slot.
item_in_main_hand	ItemStack | None	The item the player is currently holding in their main hand.
item_in_off_hand	ItemStack | None	The item the player is currently holding in their off hand.
leggings	ItemStack | None	The ItemStack in the leg slot.

boots property writable

boots: ItemStack | None

The ItemStack in the boots slot.

chestplate property writable

chestplate: ItemStack | None

The ItemStack in the chestplate slot.

held_item_slot property writable

held_item_slot: int

The slot number of the currently held item.

helmet property writable

helmet: ItemStack | None

The ItemStack in the helmet slot.

item_in_main_hand property writable

item_in_main_hand: ItemStack | None

The item the player is currently holding in their main hand.

item_in_off_hand property writable

item_in_off_hand: ItemStack | None

The item the player is currently holding in their off hand.

leggings property writable

leggings: ItemStack | None

The ItemStack in the leg slot.

WritableBookMeta

Bases: ItemMeta

Represents the meta for a writable book that can have pages.

Methods:

Name	Description
add_page	Adds new pages to the end of the book.
get_page	Gets the specified page in the book. The given page must exist.
set_page	Sets the specified page in the book. Pages of the book must be contiguous.

Attributes:

Name	Type	Description
has_pages	bool	Whether the book has pages.
page_count	int	The number of pages in the book.
pages	list[str]	All the pages in the book.

has_pages property

has_pages: bool

Whether the book has pages.

page_count property

page_count: int

The number of pages in the book.

pages property writable

pages: list[str]

All the pages in the book.

add_page

add_page(*args: str) -> None

Adds new pages to the end of the book.

Note

Up to a maximum of 50 pages with 256 characters per page.

Parameters:

Name	Type	Description	Default
pages		A list of strings, each being a page.	required

get_page

get_page(page: int) -> str

Gets the specified page in the book. The given page must exist.

Note

Pages are 1-indexed.

Parameters:

Name	Type	Description	Default
page	int	The page number to get, in range [1, page_count].	required

Returns:

Type	Description
str	The page from the book.

set_page

set_page(page: int, data: str) -> None

Sets the specified page in the book. Pages of the book must be contiguous.

Note

The data can be up to 1024 characters in length, additional characters are truncated.

Pages are 1-indexed.

Parameters:

Name	Type	Description	Default
page	int	The page number to set, in range [1, page_count].	required
data	str	The data to set for that page.	required