# API

**Assembly:** `Spark.Items` **Interface:** `IItemPlugin` **Implementation:** `ItemPlugin`

## Interface

```csharp
public interface IItemPlugin
{
    // Item usage
    void UseItem(GameObject user, ItemEntry item, ItemContext context);
    void OnItemObtained(ItemContext context);
    void OnItemDestroyed(ItemContext context);
    void OnItemDropped(ItemContext context);
    bool CanUseItem(GameObject user, ItemEntry item, ItemContext context);

    // Type registration
    void RegisterItemType(Type itemType, ItemTypeInfo info);
    IReadOnlyDictionary<string, ItemTypeInfo> GetRegisteredItemTypes();
    ItemTypeBase CreateItemTypeInstance(string typeId);
    ItemInstance CreateItemInstance(ItemEntry entry, int quantity = 1);

    // Inventory management
    InventoryInstance GetInventory(string inventoryId);
    InventoryInstance GetEntityInventory(string entityId, string inventoryId);
    InventoryInstance CreateInventory(InventoryEntry entry,
        string instanceId = null);
    InventoryInstance CreateTemporaryInventory(InventoryEntry entry,
        TimeSpan? duration = null);
    bool DestroyInventory(string inventoryId);
    IReadOnlyList<InventoryInstance> GetAllInventories();
    InventoryOperationBuilder BeginOperation();

    // Inventory events
    event Action<InventoryInstance> OnInventoryCreated;
    event Action<string> OnInventoryDestroyed;
    event Action<InventoryContext> OnItemAdded;
    event Action<InventoryContext> OnItemRemoved;
    event Action<InventoryContext> OnItemMoved;

    // Equipment definitions
    List<EquipmentSlotEntry> GetAllEquipmentSlotDefinitions();
    List<CharacterSheetEntry> GetAllCharacterSheetDefinitions();
    List<BodyPartEntry> GetAllBodyPartDefinitions();
    List<BodyMeshTypeEntry> GetAllBodyMeshTypeDefinitions();
    List<BodyMeshConfigurationEntry> GetAllBodyMeshConfigurationDefinitions();

    // Equipment operations
    bool CanEquipItemToSlot(ItemEntry item, EquipmentSlotEntry slot);
    EquipmentSlotEntry GetEquipmentSlotForItem(ItemEntry item);
    bool IsItemEquippable(ItemEntry item);
    EquipmentSlot CreateEquipmentSlot(EquipmentSlotEntry entry);
    IVisualEquipmentData GetItemVisualEquipmentData(ItemEntry item);
    void EquipVisualItem(GameObject character, ItemEntry item,
        EquipmentSlot slot = null, bool isInCombat = false);
    void UnequipVisualItem(GameObject character, ItemEntry item,
        EquipmentSlot slot = null);
}
```

## Key Data Classes

### ItemEntry

Extends `SparkDatabaseEntry`. Defines an item template.

| Field          | Type            | Description                 |
| -------------- | --------------- | --------------------------- |
| `rarity`       | ItemRarityEntry | Item rarity level           |
| `maxStackSize` | int             | Maximum stack quantity      |
| `itemType`     | ItemTypeBase    | Item behavior type          |
| `itemTypeData` | ItemDataAsset   | Type-specific configuration |

**Enums:**

```csharp
public enum ItemRarity { Common, Uncommon, Rare, Epic, Legendary, Mythic }
public enum ItemBinding { None, OnPickup, OnEquip, OnUse, Account }
```

### ItemInstance

Runtime representation of an item stack.

| Field          | Type      | Description         |
| -------------- | --------- | ------------------- |
| `ItemEntry`    | ItemEntry | The item template   |
| `quantity`     | int       | Current stack count |
| `lastUsedTime` | float     | Cooldown tracking   |

**Methods:**

```csharp
void AddQuantity(int amount)
void RemoveQuantity(int amount)
ItemInstance Split(int amount)
bool CanStackWith(ItemInstance other)
string GetDisplayName()
```

### InventoryEntry

Extends `SparkDatabaseEntry`. Defines an inventory template.

| Field               | Type              | Description                 |
| ------------------- | ----------------- | --------------------------- |
| `slotCount`         | int               | Number of inventory slots   |
| `allowStacking`     | bool              | Enable item stacking        |
| `autoStackSimilar`  | bool              | Auto-stack matching items   |
| `inventoryType`     | InventoryTypeBase | Inventory behavior type     |
| `inventoryTypeData` | InventoryTypeData | Type-specific configuration |

### InventoryInstance

Runtime inventory with slot management.

**Methods:**

```csharp
InventorySlot FindSlotForItem(ItemEntry item)
List<InventorySlot> FindSlotsWithItem(ItemEntry item)
bool CanAddItem(ItemEntry item, int quantity)
bool AddItem(ItemInstance instance)
bool RemoveItem(ItemEntry item, int quantity)
bool MoveItem(int fromSlot, int toSlot)
```

**Events:** `OnInventoryChanged`, `OnInventoryExpired`

### EquipmentSlotEntry

Defines equipment slot types (head, chest, weapon, etc.).

### LootTableEntry

Defines loot drop rules with `LootDropGroup` entries and `LootItem` configurations.

## Events

| Event                  | Description                  |
| ---------------------- | ---------------------------- |
| `ItemAddedEvent`       | Item added to inventory      |
| `ItemRemovedEvent`     | Item removed from inventory  |
| `ItemEquippedEvent`    | Item equipped to slot        |
| `ItemUnequippedEvent`  | Item unequipped              |
| `LootTableRolledEvent` | Loot table generated results |

## Commands

| Command                    | Description                                           |
| -------------------------- | ----------------------------------------------------- |
| `GiveItemCommand`          | Give item to entity (auto-adds to inventory or drops) |
| `AddItemCommand`           | Add item to specific inventory                        |
| `RemoveItemCommand`        | Remove item from inventory                            |
| `MoveItemCommand`          | Move item between slots                               |
| `TransferItemCommand`      | Transfer between inventories                          |
| `CreateInventoryCommand`   | Create a new inventory                                |
| `DestroyInventoryCommand`  | Destroy an inventory                                  |
| `ClearInventoryCommand`    | Clear all items                                       |
| `EquipVisualItemCommand`   | Equip visual mesh                                     |
| `UnequipVisualItemCommand` | Remove visual mesh                                    |

## Components

| Component         | Description                                  |
| ----------------- | -------------------------------------------- |
| `InventoryEntity` | Manages inventories on a character           |
| `EquipmentEntity` | Manages equipment slots and visual equipment |
| `BodyEntity`      | Body mesh management for visual equipment    |

## Save Data

`ItemPluginSaveData` stores serialized inventory and equipment state per entity.

## Usage

```csharp
var items = Spark.GetPlugin<IItemPlugin>();
if (items != null)
{
    // Create an item instance
    ItemInstance sword = items.CreateItemInstance(swordEntry, 1);

    // Inventory operations
    var inventory = items.GetEntityInventory(entityId, "backpack");
    inventory.AddItem(sword);

    // Check equipment
    if (items.IsItemEquippable(swordEntry))
    {
        items.EquipVisualItem(playerObject, swordEntry);
    }

    // Fluent operation builder
    items.BeginOperation()
        .From(sourceInventory)
        .To(targetInventory)
        .Transfer(itemInstance)
        .Execute();
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sparkframework.dev/documentation/developer-guide/plugins/items/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.