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.