Item System

Relevant source files

The following files were used as context for generating this wiki page:

• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/Item.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Catalog.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/ArcaneResin.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java
• core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_3_X_Changes.java

The Item System is a foundational module in Shattered Pixel Dungeon, governing all interactive objects the player can find, use, and equip. It defines the properties, behaviors, and interactions of everything from weapons and armor to potions, scrolls, and unique artifacts. The system is designed to be extensible, allowing for a wide variety of item types with distinct functionalities, managed through a hierarchy of classes originating from the base Item class.

This system also includes mechanics for item state management (e.g., upgrades, curses, identification), inventory interactions, and crafting through the Alchemy System. The evolution of the item system, as documented in the changelogs, shows a continuous effort to increase variety, improve balance, and add new gameplay mechanics like artifacts, thrown weapon overhauls, and talents that interact with items.

Core Architecture

The item system is built around the abstract Item class, which provides the basic framework for all items in the game. Specific item types extend this class to implement their unique logic.

Class Hierarchy

The following diagram illustrates the basic inheritance structure for items. Item is the base class, with more specialized types like EquipableItem and concrete implementations such as ArcaneResin inheriting from it.

Key Properties of Item

All items share a common set of properties defined in the Item.java class.

Property	Type	Description
image	int	The resource ID for the item's sprite.
stackable	boolean	If true, multiple instances of this item can be grouped into a single stack.
quantity	int	The number of items in the stack. Defaults to 1.
level	int	The upgrade level of the item. Can be positive or negative.
levelKnown	boolean	True if the item's level has been identified by the player.
cursed	boolean	True if the item is cursed.
cursedKnown	boolean	True if the item's cursed status is known to the player.
defaultAction	String	The action to be executed when the item is used from the inventory without a specific action selected.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/Item.java:42-60

Item Lifecycle and Management

Item Actions

Player interaction with items is managed through an action system. The Item class defines standard actions and a flow for executing them.

The actions() method returns a list of available string constants for a given item, such as AC_DROP and AC_THROW. The execute() method is the entry point for performing an action.

This flowchart shows the process when a player interacts with an item.

Item Pickup and Collection

When a player moves onto a tile with an item, the doPickUp() method is called. The collect() method handles adding the item to the player's inventory (Belongings).

The collection logic is as follows:

1. If the item is stackable, the game searches for a similar item in the inventory to merge with.
2. If no similar item is found or the item is not stackable, it checks for a suitable container (e.g., Seed Pouch, Scroll Holder).
3. If no container is available or suitable, it attempts to add the item to the main backpack.
4. If the collection is successful, the item is removed from the game world.

This sequence diagram illustrates the process of a hero picking up an item.

Persistence

Item state is saved and loaded via the Bundlable interface. The storeInBundle() and restoreFromBundle() methods handle serialization of key properties.

• storeInBundle(Bundle bundle): Saves properties like quantity, level, levelKnown, cursed, and cursedKnown into a Bundle.
• restoreFromBundle(Bundle bundle): Reads the properties from the Bundle and applies them to the item instance.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/Item.java:420-459

Item Categorization and Identification

The Catalog enum is a central registry that organizes all items, enchantments, and glyphs into logical categories. This is used for tracking player discoveries and unlocking badges.

Catalog Categories

The Catalog defines several categories for equipment and consumables.

Category	Examples
MELEE_WEAPONS	Dagger, Sword, Mace, Battle Axe, Glaive
ARMOR	Cloth Armor, Leather Armor, Mail Armor, Plate Armor
THROWN_WEAPONS	Dart, Shuriken, Javelin, Tomahawk, Boomerang
WANDS	Wand of Magic Missile, Wand of Fireblast, Wand of Corruption
RINGS	Ring of Might, Ring of Haste, Ring of Wealth, Ring of Energy
ARTIFACTS	Cloak of Shadows, Horn of Plenty, Chalice of Blood, Ethereal Chains
TRINKETS	Mossy Clump, Salt Cube, Ferret Tuft, Mimic Tooth
POTIONS	Potion of Healing, Potion of Strength, Potion of Levitation
SCROLLS	Scroll of Identify, Scroll of Remove Curse, Scroll of Upgrade
SPELLS	Alchemize, Curse Infusion, Recycle, Summon Elemental

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Catalog.java:100-188

Identification System

The game tracks which items the player has identified.

• isIdentified(): Returns true if both levelKnown and cursedKnown are true.
• identify(): Sets levelKnown and cursedKnown to true.
• Catalog.setSeen(Class<?> cls): Marks an item type as discovered in the journal once it's identified. This is used for progress tracking and unlocking badges.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/Item.java:362-378, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Catalog.java:251-260

Alchemy and Crafting

The Alchemy system, introduced in v0.7.0 and overhauled in v1.1.0, allows players to craft new items from existing ones.

Recipes

Crafting is handled by inner Recipe classes within an item's definition. For example, ArcaneResin.java contains a recipe to break down wands into resin.

A Recipe class typically implements:

• testIngredients(ArrayList<Item> ingredients): Checks if the provided items are valid for the recipe.
• cost(ArrayList<Item> ingredients): Determines the Alchemical Energy cost.
• brew(ArrayList<Item> ingredients): Consumes the ingredients and produces the resulting item.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/ArcaneResin.java:119-158

Alchemical Energy

Introduced in v0.7.0 and overhauled in v1.1.0, Alchemical Energy is a core resource for crafting.

• Originally, energy was contained within alchemy pots.
• The v1.1.0 overhaul changed energy into a portable resource, similar to gold, that players carry.
• Players can gain energy by scrapping consumable items.
• Many recipes were changed to require energy instead of specific secondary ingredients (like seeds or runestones), making the system more flexible.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:441-450, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java:541-557

Evolution of the Item System

The item system has undergone significant changes throughout the game's development, introducing new mechanics and rebalancing existing ones.

Version	Key Changes
v0.2.0	Artifacts Introduced: 7 rings were removed and replaced with 7 artifacts (e.g., Cloak of Shadows, Horn of Plenty), a new class of unique items that grow stronger through unique means. 6 new rings were also added.
v0.3.0	Wand Rework: Wands were completely reworked with new sprites, new mechanics (faster recharge when empty), and new types. The Mage class was also reworked around a unique staff.
v0.6.3	Ranged Weapons Overhaul: Thrown weapons were changed from single-use items to having durability, making them more viable throughout a run.
v0.7.0	Alchemy Overhaul: The alchemy system was introduced as a full consumable crafting system, with Alchemical Energy as a new resource. Exotic potions and scrolls were added.
v0.8.1	Item Icons: Rings received unique icons, and item icons were moved to the top-right of the inventory slot.
v1.1.0	Alchemical Energy Overhaul: Energy became a portable resource gained from scrapping items, making alchemy more flexible. Many recipes were reworked.
v2.4.0	Trinkets Introduced: A new category of item was added, produced and upgraded via alchemical energy, designed to tweak gameplay variables rather than give direct power.
v3.2.0	Thrown Weapon Sets: Thrown weapons were overhauled to spawn in sets of three, which are upgraded as a single unit.

Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_X_Changes.java:231-252, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_3_X_Changes.java:464-488, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:453-465, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:441-490, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_8_X_Changes.java:628-633, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java:541-557, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:1003-1013, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v3_X_Changes.java:1120-1136

Conclusion

The Item System is a comprehensive and evolving module that forms the backbone of the player's experience in Shattered Pixel Dungeon. From the fundamental properties defined in the Item class to the complex interactions of artifacts and alchemy, the system provides a deep and varied set of tools and equipment. Its history shows a clear trend towards increasing player choice, adding strategic depth, and refining core mechanics to create a more engaging and balanced roguelike experience.