API

Assembly: Spark.Items Interface: IItemPlugin Implementation: ItemPlugin

Interface

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:

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:

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:

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

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();
}