Modding Guide: Adding a New Item
Relevant source files
The following files were used as context for generating this wiki page:
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_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_7_X_Changes.java
- core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_9_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/v3_X_Changes.java
- README.md
Introduction
This guide provides a high-level overview for modders on how to add new items to Shattered Pixel Dungeon. As direct source code for item implementation is not provided, this document derives its information from a historical analysis of the game's changelog files. It examines the patterns and components involved when new items were officially introduced, offering insights into the underlying structure and design philosophy.
The guide covers the core components that constitute an item, the various categories of items present in the game, methods for integrating them into the game world, and the iterative process of balancing and refinement that follows their introduction.
The Anatomy of a New Item
Based on the changelogs, every new item consists of three primary components: a core Java class, a visual sprite, and its defined gameplay mechanics.
The Java Class
Every item in the game is represented by its own Java class. These classes are typically located in packages corresponding to their item type, such as com.shatteredpixel.shatteredpixeldungeon.items.wands or com.shatteredpixel.shatteredpixeldungeon.items.artifacts. When a new item is added, a new class is created for it, as seen with the introduction of items like WandOfWarding and AlchemistsToolkit.
The conceptual class hierarchy for an item can be visualized as follows.
This diagram illustrates the likely inheritance structure for different item types, as inferred from package names in import statements.
The Item Sprite
Each item requires a visual representation, or sprite. The changelogs show that new items are often associated with an ItemSprite object, which frequently references a constant from ItemSpriteSheet. This indicates a centralized sprite sheet for item graphics.
| ItemSpriteSheet Constant | Representative Item | Source Version |
|---|---|---|
ItemSpriteSheet.CROSSBOW | Crossbow | v0.6.4 |
ItemSpriteSheet.WAND_WARDING | Wand of Warding | v0.7.4 |
ItemSpriteSheet.RING_ARCANA | Ring of Arcana | v1.4.0 |
ItemSpriteSheet.RAT_SKULL | Trinkets | v2.4.0 |
ItemSpriteSheet.PICKAXE | Blacksmith Quest | v2.2.0 |
ItemSpriteSheet.SEAL | Warrior's Broken Seal | v3.1.0 |
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.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/v3_X_Changes.java
Gameplay Mechanics
The core functionality of an item is detailed in its description upon release. For example, the v0.7.4 changelog describes the WandOfWarding as a new wand that "spawns autonomous wards which attack enemies." These mechanics are the essence of the item and are subject to change in subsequent balance patches.
Item Categories
Shattered Pixel Dungeon features a diverse range of item categories, each with distinct characteristics. New items are consistently added to these existing categories.
| Category | Description | Introduction Examples | Source Version |
|---|---|---|---|
| Artifacts | Unique, equippable items that grow stronger through special means. | Cloak of Shadows, Horn of Plenty | v0.2.0 |
| Wands | Magical items that use charges to cast spells. | Wand of Warding, Wand of Living Earth | v0.7.4 |
| Weapons | Melee and thrown weapons used for combat. | Crossbow, Gauntlet, Kunai | v0.6.4, v0.7.3 |
| Rings | Equippable items providing passive statistical bonuses. | Ring of Force, Ring of Furor | v0.2.0 |
| Consumables | Single-use items like potions, scrolls, and seeds. | Potion of Haste, Scroll of Transmutation | v0.7.0 |
| Trinkets | Items that tweak gameplay variables, crafted with alchemy. | Rat Skull, Pumpkin Pie | v2.4.0 |
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_2_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_7_X_Changes.java, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java
Integration into the Game World
Once created, a new item must be made available to the player. The changelogs reveal several common methods for item integration.
Loot Drops and Spawning
The most straightforward method is adding an item to the game's loot tables.
- General Drops: Items can become part of the standard loot pool. For instance, the
Master Thieves' Armbandwas changed to a regular artifact drop in v0.7.0. - Enemy Drops: Specific enemies can be configured to drop certain items. Guards initially dropped healing potions, a drop that was later moved to Necromancers in v0.7.5.
- Guaranteed Spawns: Some items are guaranteed to appear in a run, such as the
Dew Vial(now Waterskin) always spawning on floor 1.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:1071-1073, 131-132, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:1012-1013
The Alchemy System
The alchemy system, introduced in v0.7.0 and overhauled in v1.1.0, is a primary method for creating new and exotic items.
Initial System (v0.7.0): The original system focused on combining specific items, such as a potion and two seeds, to create an exotic potion. It also introduced Alchemical Energy as a resource for certain recipes.
Overhauled System (v1.1.0): The system was reworked to make Alchemical Energy the central resource. Players can now break down unwanted consumables into energy, which is then used to craft a wide variety of items, including exotic variants, spells, and trinkets. This made the system more flexible.
The following diagram illustrates the evolution of the alchemy crafting flow.
Quest Rewards
New items are also introduced as rewards for completing quests. The Sad Ghost's quest offers a choice of equipment, and the overhauled Blacksmith quest in v2.2.0 provides various smithing services, including reforging items, as a reward for mining ore.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java:1003-1011, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_9_X_Changes.java:1008-1010
The Development and Balancing Lifecycle
The developer commentary included in the changelogs provides a clear picture of the iterative design process for new items. A modder should anticipate that a new item will likely require several rounds of balancing.
This diagram shows the typical lifecycle of an item from concept to a balanced state.
Initial Release and Feedback
New items are introduced with specific design goals, as often explained in the "Developer Commentary" sections. For example, the v0.7.4 commentary notes that the Wand of Warding and Wand of Living Earth were added to expand ally-focused gameplay. After release, player feedback and gameplay data are collected to assess the item's performance.
Iterative Balancing
It is extremely common for items to be adjusted in subsequent patches. These changes can be simple buffs, nerfs, or more complex reworks. The Ring of Wealth is a prime example of an item that has evolved over multiple updates.
| Version | Change to Ring of Wealth |
|---|---|
| v0.6.1 | Reworked to generate extra loot from defeated enemies instead of affecting level generation. |
| v0.7.2 | Significantly buffed: special drops happen ~50% more often and include a greater variety of items. |
| v1.4.0 | Buffed again: equipment drops from the ring scale better with the ring's level. |
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:1052-1059, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:825-832, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java:1400-1406
Reworks and Removals
In some cases, an item's core mechanic may be fundamentally flawed or redundant, leading to a complete rework or removal.
- Removal: In v0.7.0,
Lloyd's BeaconandCape of Thornswere removed from the game, with their functionality intended to be replaced by other systems. - Rework: In v0.6.3, the
Wand of Venomwas reworked into theWand of Corrosion, changing its visual theme and slightly altering its mechanics.
Sources: core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java:1083-1089, core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_6_X_Changes.java:623-627
Conclusion
Adding a new item to Shattered Pixel Dungeon is a multi-faceted process. It involves creating a new Java class with defined mechanics, providing a corresponding sprite, and integrating it into the game through loot tables, alchemy, or quests. The historical data clearly shows that item creation is not a one-time event but an iterative cycle of design, release, feedback, and balancing. Modders seeking to add their own content should be prepared to follow a similar path of refinement to ensure their creations are both balanced and engaging.