Expresso Inventory System Documentation

Expresso Inventory System is a comprehensive inventory solution for Godot. Key features include:

• Core Inventory: Item stacks, item definitions as extendable resources, and categories.
• UI & Layouts: Separate UI inventory logic, hotbars, equipment inventories, and grid-based inventories (similar to Resident Evil 4).
• Systems: Loot system, crafting system (including autocrafts), and item pickup/drop mechanics.
• Advanced Support: Multiplayer compatibility and unconventional inventory layouts.
• Tools: Item Editor for managing item data.

Note: Grid Inventory and Grid UIs are based on the Gloot plugin.

An ItemDefinition is an abstract Resource that defines the core properties of an item. It is not the same as a string identifier or an instance of an item in an inventory; rather, it provides the metadata (such as stack size, icon, name, and weight) required to manage items within an ItemStack or GridInventory.

To use an item in the system, you must configure an ItemDefinition and add it to the items list of an InventoryDatabase. This is typically done via the plugin's editor.

A CraftStation is a node that manages the transformation of items into products using Recipe resources. It acts as a bridge between input inventories (containing ingredients) and output inventories (receiving products).

Key responsibilities include:

• Filtering recipes based on the station's type.
• Validating ingredient availability.
• Managing concurrent crafting processes (either sequentially or in parallel).
• Handling timing and progression.
• Automatically moving items between inventories.
• Emitting signals for UI and game logic integration.

# Conceptual flow: 
# 1. Station monitors Input Inventories for ingredients.
# 2. Station validates Recipe from InventoryDatabase.
# 3. Station processes craft over time.
# 4. Station moves products to Output Inventories.

The Loot resource is a container for a weighted list of LootItem resources. It is used to handle random item generation for mechanics like treasure chests, enemy drops, or resource gathering.

Key behaviors:

• Weighted Selection: Items with higher weights in their respective LootItem configurations are more likely to be selected.
• Roll Ranges: You can configure a range of rolls using min_rolls and max_rolls. This allows a single loot generation call to produce a variable number of items (e.g., 2 to 4 items).
• Automatic Weighting: The total weight is automatically calculated from all contained LootItem resources to ensure correct probability distribution.

The InventoryConstraint class is a Resource that you can extend to define custom rules for how an Inventory behaves when items are added. By overriding its virtual methods, you can control stack creation, item eligibility, quantity limits, and maximum stack sizes.

# Example of creating a custom constraint by extending InventoryConstraint
class_name MyCustomConstraint
extends InventoryConstraint

func _can_add_on_inventory(inventory: Node, item_id: String, amount: int, properties: Dictionary) -> bool:
    return item_id == "wood"

An ItemCategory is a Resource used to apply a shared set of properties to multiple ItemDefinition objects simultaneously. It also serves as a filter for InventoryConstraint, allowing you to define stacks that only accept items belonging to a specific category.

Common use cases include:

• Applying uniform properties (like weight modifiers or special behaviors) to all items in a category.
• Providing UI metadata like colors and icons for categorized inventory slots.

The NodeInventories class is a base Node used by any node that requires access to an inventory database. It provides the mechanism to link a node to a specific InventoryDatabase and offers utility methods to resolve item definitions via IDs.

Common nodes that inherit from NodeInventories include:

• CraftStation
• Hotbar
• Inventory
• LootGenerator

Required items are items that must be present in the input inventories for crafting to begin, but they are not consumed. This is the standard way to implement:

• Crafting tools (e.g., hammer, anvil).
• Fuel sources that are not consumed per recipe.
• Permanent machinery or equipment.

Recipes are resources that define the requirements and outcomes for crafting items at CraftStation nodes. A recipe acts as a blueprint containing the following components:

• Ingredients: Items consumed during the crafting process.
• Required Items: Items that must be present to start crafting but are not consumed (e.g., tools like a hammer).
• Products: The items produced upon successful completion.
• Station Type: The specific CraftStationType required to execute the recipe.
• Craft Time: The duration (in seconds) required to complete the process.