# Items Items are database entries that define objects players can collect, use, equip, and trade. Every item has a type that determines its behavior and what extra fields it exposes. ## Creating an Item Entry Open the Spark Editor, go to **Items > Items** and click **Create New**. Every item has these core fields: | Field | Description | | -------------- | ------------------------------------------------------------------------- | | Display Name | Name shown in-game (e.g., "Iron Sword"). | | Description | Tooltip or info panel text. | | Icon | Sprite for inventory UI. | | Max Stack Size | How many can stack in one slot. Set to 1 for unique items like equipment. | | Item Rarity | Reference to an Item Rarity entry. | | Item Type | Determines behavior and additional type-specific fields (see below). | ## Item Types Each item has a type that controls its behavior and exposes type-specific configuration. The available types depend on which plugins and extensions are installed. ### Weapon Item Type Weapons are equippable items that attach a visual model to the character and can override animations. | Field | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Hand Type | **Main Hand**, **Off Hand**, **Any Hand** (can go in either), **Two Handed**, or **Ranged**. | | Equipment Slot | Which equipment slot this weapon occupies. | | Weapon Type | Reference to a Weapon Type entry (Sword, Axe, Bow, etc.). | | Weapon Prefab | The GameObject prefab instantiated when the weapon is equipped. | | Weapon Scale | Scale applied to the weapon model (default: 1,1,1). | | Animator Override Controller | Overrides the character's animations while this weapon is equipped (e.g., different idle/attack anims for sword vs. bow). | | Equip Requirements | List of requirement groups the player must meet to equip this weapon. | **Hand-specific visual configuration:** For each hand type, you configure where the weapon appears on the character in combat and non-combat states: | Field | Description | | --------------------------------- | ------------------------------------------------------------- | | Body Part (Non-Combat) | Where the weapon is attached when sheathed (e.g., back, hip). | | Position Coordinates (Non-Combat) | Local position and rotation when sheathed. | | Body Part (Combat) | Where the weapon is attached when drawn (e.g., right hand). | | Position Coordinates (Combat) | Local position and rotation when drawn. | | Character Coordinates | Per-character overrides for different character models. | **Sheath/Unsheath animations:** | Field | Description | | ------------------------ | ------------------------------------------------------------------------------- | | Play Unsheath Animation | Trigger an unsheath animation when entering combat. | | Play Sheathe Animation | Trigger a sheath animation when exiting combat. | | Unsheath Animation Delay | Seconds to wait before repositioning the weapon during unsheath (default: 0.3). | | Sheathe Animation Delay | Seconds to wait before repositioning during sheath (default: 0.3). | When combat state changes, the weapon transitions between its non-combat body part (e.g., back) and combat body part (e.g., hand) with optional animation. ### Armor Item Type Armor items are equippable items that show/hide GameObjects on the character and can control body mesh visibility. | Field | Description | | ----------------------- | ------------------------------------------------------------------------------------------- | | Equipment Slot | Which equipment slot this armor occupies. | | Armor GameObject Name | Name of a child GameObject on the character to show when equipped and hide when unequipped. | | Body Mesh Configuration | Which body meshes to hide while this armor is worn (e.g., hide hair under helmet). | | Equip Requirements | List of requirement groups the player must meet to equip this armor. | When a character equips armor: 1. The named child GameObject is found on the character and activated (made visible). 2. Body meshes defined in the configuration are hidden (e.g., hair under helmet, skin under gloves). 3. When unequipped, the process reverses: the armor object is hidden and body meshes are restored. ### Resource Item Type Resource items are generic items that serve as crafting materials, quest items, trade goods, or any other non-equippable item. They can be consumed through the item use system, and their specific behavior is defined through extensions. ### Currency Item Type Currency items bypass the inventory entirely. When a character obtains a currency item, the item is automatically converted into the corresponding currency and added to the character's wallet. The item's stack size determines the amount of currency granted. | Field | Description | | -------------- | ------------------------------------------------- | | Currency Entry | The currency to grant when this item is obtained. | This is useful for currency drops from enemies or loot tables — instead of taking up inventory space, the currency is added to the wallet immediately. ## Item Rarities Create item rarities in the **Items > Rarity** tab. Each rarity has: | Field | Description | | ------------ | -------------------------------------------------------------- | | Display Name | The rarity label (e.g., "Legendary"). | | UI Color | Color used for item name text, borders, and backgrounds in UI. | You can create as many rarities as you need. Items reference a rarity entry, and the UI uses the rarity's color to highlight them. Common examples: Common (white), Uncommon (green), Rare (blue), Epic (purple), Legendary (orange), Mythic (red). ## Weapon Types Weapon types classify weapons for targeting and requirement checking. Create them in the **Items > Weapon Types** tab. Each weapon type is a simple entry with a display name. Examples: Sword, Axe, Bow, Staff, Dagger, Mace, Spear, Crossbow. Weapon types are referenced by: * **HasWeaponTypeEquippedRequirementType**: Check if the player has a specific weapon type equipped (used to gate abilities, quests, etc.). * **Weapon items**: Each weapon item references its weapon type. ## Loot Tables Loot tables define randomized item drops. Create them in the **Items > Loot Tables** tab. ### Loot Table Fields | Field | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------- | | Drop Groups | Sets of items with weights and conditions. | | Guaranteed Drops | Items that always drop regardless of RNG. | | Global Drop Chance Multiplier | Multiplier applied to all drop chances (range 0.1–5.0, default: 1.0). Useful for difficulty scaling. | | Allow Duplicates | Whether the same item can drop multiple times in a single roll. | | Max Total Drops | Maximum items from one roll (0 = unlimited). | ### Guaranteed Drops Each guaranteed drop specifies: | Field | Description | | ------------ | -------------------------------------------------------- | | Item | The item entry that always drops. | | Min Quantity | Minimum amount to drop. | | Max Quantity | Maximum amount to drop (randomized between min and max). | ### Drop Groups Each drop group is a pool of items with its own configuration: | Field | Description | | ------------ | --------------------------------------------------------------------------------------------------------------- | | Group Name | Descriptive label (e.g., "Rare Weapons", "Common Materials"). | | Group Weight | Relative weight for group selection (range 0.1–1000, default: 1.0). Higher weight = more likely to be selected. | | Force Select | If true, this group is always processed regardless of weight. | | Min Drops | Minimum items to drop from this group when selected. | | Max Drops | Maximum items to drop from this group when selected. | | Requirements | Requirement groups that must be met for this group to be eligible. | | Items | Pool of items in this group. | ### Loot Items (within a Drop Group) Each item in a drop group has: | Field | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | Item | The item entry that can drop. | | Weight | Relative weight for weighted random selection (range 0.1–100, default: 1.0). | | Min Quantity | Minimum quantity when this item drops. | | Max Quantity | Maximum quantity when this item drops. | | Drop Chance | Additional chance modifier (0.0–1.0). At 1.0, the item is always in the pool. At 0.5, there's a 50% chance it's even considered. | | Nested Table | Instead of dropping an item, roll another loot table. This lets you create complex nested loot hierarchies. | To roll a loot table in-game, use the **Roll Loot Table** trigger type with the loot table entry and a target inventory. ## Item Lifecycle Each item type can respond to key moments in an item's life: | Moment | When it happens | | ---------------- | ---------------------------------------------- | | **On Use** | The player uses the item from their inventory. | | **On Obtained** | The item is added to an inventory. | | **On Destroyed** | The item is removed or destroyed. | | **On Drop** | The item is dropped from the inventory. | Different item types handle these moments differently. For example, currency items add currency to the wallet on obtained, while resource items may trigger crafting-related logic on use. --- # 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/user-guide/plugins/items/items.md?ask= ``` 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.