Items System

The items module provides item management, inventory, equipment, and loot drop systems.

Item Base Classes

Item system for equipment, consumables, and quest items.

This module provides the base item system that can be extended for different item types.

class barebones_rpg.items.item.ItemType(value)

Bases: Enum

Types of items.

WEAPON = 1

ARMOR = 2

ACCESSORY = 3

CONSUMABLE = 4

QUEST = 5

MATERIAL = 6

KEY = 7

MISC = 8

class barebones_rpg.items.item.EquipSlot(value)

Bases: Enum

Equipment slots.

WEAPON = 'weapon'

HEAD = 'head'

BODY = 'body'

LEGS = 'legs'

FEET = 'feet'

HANDS = 'hands'

ACCESSORY_1 = 'accessory_1'

ACCESSORY_2 = 'accessory_2'

SHIELD = 'shield'

class barebones_rpg.items.item.Item(**data)

Bases: BaseModel

Base item class.

All items in the game inherit from this class.

Example

>>> sword = Item(
...     name="Iron Sword",
...     item_type=ItemType.WEAPON,
...     description="A basic iron sword",
...     stat_modifiers={"atk": 5},
...     range=1
... )
>>> bow = Item(
...     name="Longbow",
...     item_type=ItemType.WEAPON,
...     base_damage=8,
...     range=5
... )
>>> potion = Item(
...     name="Health Potion",
...     item_type=ItemType.CONSUMABLE,
...     on_use=lambda entity: entity.heal(50)
... )
>>> legendary = Item(
...     name="Legendary Sword",
...     item_type=ItemType.WEAPON,
...     unique=True,
...     base_damage=50
... )

id: str

name: str

description: str

item_type: ItemType

value: int

weight: float

stackable: bool

max_stack: int

quantity: int

unique: bool

equip_slot: Optional[EquipSlot]

stat_modifiers: Dict[str, int]

required_level: int

base_damage: int

damage_type: str

range: int

consumable: bool

on_use: Optional[Callable]

metadata: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

use(target, context=None)

Use the item.

Parameters:

• target (Any) – Entity or object that the item is used on

• context (Optional[Dict[str, Any]]) – Additional context for item use

Return type:

Any

Returns:

Result of using the item

can_stack_with(other)

Check if this item can stack with another.

Parameters:

other (Item) – Another item

Return type:

bool

Returns:

True if items can stack

stack_with(other)

Stack this item with another.

Parameters:

other (Item) – Another item to stack with

Return type:

int

Returns:

Number of items that couldn’t be stacked (overflow)

split(amount)

Split a stack into two.

Parameters:

amount (int) – Number of items to split off

Return type:

Optional[Item]

Returns:

New item stack or None if can’t split

to_dict()

Convert item to dictionary for saving.

Return type:

Dict[str, Any]

Returns:

Dictionary representation

classmethod from_dict(data)

Create item from dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary representation

Return type:

Item

Returns:

Item instance

barebones_rpg.items.item.create_weapon(name, base_damage, damage_type='physical', range=1, description='', value=0, **kwargs)

Create a weapon item.

Parameters:

• name (str) – Weapon name

• base_damage (int) – Base damage dealt by weapon

• damage_type (str) – Type of damage (physical, magic, or custom)

• range (int) – Weapon range (1=melee, higher for ranged)

• description (str) – Description

• value (int) – Gold value

• **kwargs – Additional properties (stat_modifiers, metadata, etc.)

Return type:

Item

Returns:

Weapon item

Example

>>> sword = create_weapon("Iron Sword", base_damage=10, range=1)
>>> bow = create_weapon("Longbow", base_damage=8, range=5)
>>> spear = create_weapon("Spear", base_damage=9, range=2)

barebones_rpg.items.item.create_armor(name, physical_defense=0, magic_defense=0, slot=EquipSlot.BODY, description='', value=0, **kwargs)

Create an armor item.

Parameters:

• name (str) – Armor name

• physical_defense (int) – Physical defense bonus

• magic_defense (int) – Magic defense bonus

• slot (EquipSlot) – Equipment slot

• description (str) – Description

• value (int) – Gold value

• **kwargs – Additional properties

Return type:

Item

Returns:

Armor item

barebones_rpg.items.item.create_consumable(name, on_use, description='', value=0, stackable=True, max_stack=99, **kwargs)

Create a consumable item.

Parameters:

• name (str) – Item name

• on_use (Callable) – Function to call when used

• description (str) – Description

• value (int) – Gold value

• stackable (bool) – Can stack

• max_stack (int) – Max stack size

• **kwargs – Additional properties

Return type:

Item

Returns:

Consumable item

barebones_rpg.items.item.create_quest_item(name, description='', **kwargs)

Create a quest item.

Parameters:

• name (str) – Item name

• description (str) – Description

• **kwargs – Additional properties

Return type:

Item

Returns:

Quest item

Inventory System

Inventory management system.

This module provides inventory functionality for managing collections of items.

class barebones_rpg.items.inventory.Inventory(**data)

Bases: BaseModel

Inventory for storing items.

Supports auto-stacking, slot limits, and weight limits.

Example

>>> inv = Inventory(max_slots=20)
>>> sword = create_weapon("Sword", atk=5)
>>> inv.add_item(sword)
>>> print(inv.count_items())
1

max_slots: int

max_weight: float

items: List[Item]

auto_stack: bool

gold: int

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

add_item(item)

Add an item to inventory.

Parameters:

item (Item) – Item to add

Return type:

bool

Returns:

True if item was added successfully

remove_item(item, quantity=1)

Remove an item from inventory.

Parameters:

• item (Item) – Item to remove

• quantity (int) – How many to remove

Return type:

bool

Returns:

True if item was removed

remove_item_by_name(item_name, quantity=1)

Remove an item by name.

Parameters:

• item_name (str) – Name of item to remove

• quantity (int) – How many to remove

Return type:

bool

Returns:

True if item was removed

find_item(item_name)

Find an item by name.

Parameters:

item_name (str) – Name of item to find

Return type:

Optional[Item]

Returns:

Item if found, None otherwise

find_items_by_type(item_type)

Find all items of a specific type.

Parameters:

item_type (ItemType) – Type of items to find

Return type:

List[Item]

Returns:

List of matching items

has_item(item_name, quantity=1)

Check if inventory has an item.

Parameters:

• item_name (str) – Name of item

• quantity (int) – Required quantity

Return type:

bool

Returns:

True if inventory has the item

count_items()

Count total number of item slots used.

Return type:

int

Returns:

Number of slots used

get_total_weight()

Calculate total weight of all items.

Return type:

float

Returns:

Total weight

get_available_slots()

Get number of available slots.

Return type:

int

Returns:

Number of free slots

is_full()

Check if inventory is full.

Return type:

bool

Returns:

True if inventory is full

sort_by_type()

Sort inventory by item type.

Return type:

None

sort_by_name()

Sort inventory by item name.

Return type:

None

sort_by_value()

Sort inventory by item value (descending).

Return type:

None

add_gold(amount)

Add gold to inventory.

Parameters:

amount (int) – Amount of gold to add

Return type:

None

remove_gold(amount)

Remove gold from inventory.

Parameters:

amount (int) – Amount of gold to remove

Return type:

bool

Returns:

True if enough gold was available

to_dict()

Convert inventory to dictionary.

Return type:

Dict[str, Any]

Returns:

Dictionary representation

classmethod from_dict(data)

Create inventory from dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary representation

Return type:

Inventory

Returns:

Inventory instance

class barebones_rpg.items.inventory.Equipment(**data)

Bases: BaseModel

Equipment manager for equipped items.

Manages which items are equipped in which slots.

Example

>>> equipment = Equipment()
>>> sword = create_weapon("Sword", atk=5)
>>> equipment.equip(sword)
>>> print(equipment.get_total_stat_bonus("atk"))
5

slots: Dict[str, Optional[Item]]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

equip(item)

Equip an item.

Parameters:

item (Item) – Item to equip

Return type:

Optional[Item]

Returns:

Previously equipped item in that slot (if any)

unequip(slot)

Unequip an item from a slot.

Parameters:

slot (EquipSlot) – Slot to unequip from

Return type:

Optional[Item]

Returns:

Unequipped item (if any)

get_equipped(slot)

Get the item equipped in a slot.

Parameters:

slot (EquipSlot) – Slot to check

Return type:

Optional[Item]

Returns:

Equipped item or None

get_all_equipped()

Get all equipped items.

Return type:

List[Item]

Returns:

List of equipped items

get_total_stat_bonus(stat_name)

Calculate total stat bonus from all equipment.

Parameters:

stat_name (str) – Name of the stat

Return type:

int

Returns:

Total bonus from equipment

get_all_stat_bonuses()

Get all stat bonuses from equipment.

Return type:

Dict[str, int]

Returns:

Dictionary of stat bonuses

is_slot_empty(slot)

Check if a slot is empty.

Parameters:

slot (EquipSlot) – Slot to check

Return type:

bool

Returns:

True if slot is empty

to_dict()

Convert equipment to dictionary.

Return type:

Dict[str, Any]

Returns:

Dictionary representation

classmethod from_dict(data)

Create equipment from dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary representation

Return type:

Equipment

Returns:

Equipment instance

Loot System

Loot drop system for handling item drops from enemies and containers.

This module provides functionality for rolling on loot tables and managing dropped items.

class barebones_rpg.items.loot.LootDrop(item, source=None, quantity=1)

Bases: object

Represents an item that has been dropped.

Example

>>> from barebones_rpg.items import LootDrop, create_material
>>> bone = create_material("Bone", value=5)
>>> drop = LootDrop(item=bone, source=goblin, quantity=1)

item: Item

The dropped Item instance

source: Optional[Any] = None

Entity or object that dropped the item (optional)

__init__(item, source=None, quantity=1)

quantity: int = 1

Number of items dropped (for stackable items)

barebones_rpg.items.loot.roll_loot_table(loot_table, source=None)

Roll on a loot table to determine which items drop.

The loot table should be a list of dictionaries with the following format:

[
    {"item": "Goblin Bone", "chance": 0.3},  # 30% drop chance, lookup by name
    {"item": bone_item, "chance": 0.5},      # 50% drop chance, direct Item object
    {"item": "Rare Gem", "chance": 0.05}     # 5% drop chance
]

For string item names, the LootManager is used to retrieve the item template. For Item objects, a deep copy is created. Each entry is rolled independently, so multiple items can drop from a single table.

Parameters:

• loot_table (List[Dict[str, Any]]) – List of loot entries with “item” and “chance” keys

• source (Optional[Any]) – Optional entity/object that is dropping the loot

Return type:

List[LootDrop]

Returns:

List of LootDrop objects for items that successfully dropped

Example

>>> from barebones_rpg.items import roll_loot_table, LootManager, create_material
>>>
>>> # Setup manager
>>> LootManager().register("Bone", create_material("Bone", value=5))
>>>
>>> # Define loot table
>>> loot_table = [
...     {"item": "Bone", "chance": 0.5},
...     {"item": create_material("Scale", value=10), "chance": 0.1}
... ]
>>>
>>> # Roll for loot
>>> drops = roll_loot_table(loot_table, source=goblin)
>>> for drop in drops:
...     print(f"Dropped: {drop.item.name}")

barebones_rpg.items.loot.create_loot_entry(item, chance, quantity=1)

Helper function to create a loot table entry.

Parameters:

• item (Union[str, Item]) – Item name (string) or Item object

• chance (float) – Drop chance (0.0 to 1.0)

• quantity (int) – Number of items to drop (default: 1)

Return type:

Dict[str, Any]

Returns:

Dictionary formatted for use in loot tables

Example

>>> entry = create_loot_entry("Goblin Bone", 0.3)
>>> entry2 = create_loot_entry(rare_item, 0.05, quantity=3)
>>> loot_table = [entry, entry2]

Loot Manager

Global loot manager for managing item drops.

This module provides a singleton manager for mapping item names to item templates or factory functions, enabling both data-driven and code-first loot systems.

class barebones_rpg.items.loot_manager.LootManager(*args, **kwargs)

Bases: object

Global manager for loot items (Singleton).

The LootManager allows registering item templates or factory functions that can be referenced by name in loot tables. It supports both static items (templates that get deep copied) and dynamic items (factory functions).

It also tracks unique items to ensure they only drop once per game.

Example

>>> from barebones_rpg.items import LootManager, create_material, Item
>>>
>>> # Register a static template
>>> bone = create_material("Goblin Bone", value=5)
>>> LootManager().register("Goblin Bone", bone)
>>>
>>> # Register a factory function
>>> def random_potion():
...     import random
...     healing = random.randint(30, 50)
...     return create_consumable(f"Potion ({healing}hp)",
...                             on_use=lambda t, c: t.heal(healing))
>>> LootManager().register("Random Potion", random_potion)
>>>
>>> # Get items (creates new instances)
>>> item1 = LootManager().get("Goblin Bone")
>>> item2 = LootManager().get("Goblin Bone")
>>> assert item1.id != item2.id  # Different instances

__init__()

Initialize the loot manager.

register(name, item_or_factory)

Register an item template or factory function.

Automatically registers any callbacks (on_use) to the CallbackRegistry for serialization support.

Parameters:

• name (str) – Name to register the item under

• item_or_factory (Union[Item, Callable[[], Optional[Item]]]) – Either an Item instance (will be deep copied when retrieved) or a callable that returns an Item or None

Return type:

None

Example

>>> LootManager().register("Gold Coin", create_material("Gold Coin", value=1))
>>> LootManager().register("Random Weapon", lambda: create_weapon(...))

get(name)

Get an item by name, creating a new instance.

For item templates, creates a deep copy. For factory functions, calls the function. Tracks unique items and returns None if a unique item has already been dropped.

Parameters:

name (str) – Name of the item to retrieve

Return type:

Optional[Item]

Returns:

New Item instance, or None if not found or unique already dropped

Example

>>> item = LootManager().get("Goblin Bone")
>>> if item:
...     player.inventory.add_item(item)

has(name)

Check if an item is registered.

Parameters:

name (str) – Name of the item

Return type:

bool

Returns:

True if item is registered

Example

>>> if LootManager().has("Goblin Bone"):
...     print("Item is registered")

clear()

Clear the entire manager.

This removes all registered items and resets unique item tracking. Useful for testing or resetting game state.

Example

>>> LootManager().clear()  # Start fresh

Return type:

None

reset_unique_tracking()

Reset unique item tracking without clearing the registry.

This allows unique items to drop again without re-registering them. Useful for new game+ or testing.

Example

>>> LootManager().reset_unique_tracking()

Return type:

None

save()

Save manager state.

Return type:

Dict[str, Any]

Returns:

Dictionary with dropped unique items

load(data)

Load manager state.

Parameters:

data (Dict[str, Any]) – Saved data containing dropped unique items

Return type:

None

classmethod reset()

Reset manager to initial state (for testing).

Clears the singleton instance, causing the next access to create a fresh instance with default initialization.

Return type:

None