Alchemy System

Relevant source files

The following files were used as context for generating this wiki page: - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/Recipe.java](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/Recipe.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/AlchemyScene.java](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/scenes/AlchemyScene.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/potions/Potion.java](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/potions/Potion.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/artifacts/AlchemistsToolkit.java](httpshttps://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/artifacts/AlchemistsToolkit.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/QuickRecipe.java](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/QuickRecipe.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Document.java](httpshttps://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/journal/Document.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/journal/AlchemyPage.java](httpshttps://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/items/journal/AlchemyPage.java) - [core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v0_7_X_Changes.java](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/https/github.com/Alonso-pixel/shattered-pixel-dungeon/blob/main/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](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/https/github.com/Alonso-pixel/shattered-pixel-dungeon/blob/main/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v1_X_Changes.java) - [core/src/main/java/com/shatteredpixel/shatterdpixeldungeon/ui/changelist/v2_X_Changes.java](https://github.com/Alonso-pixel/shattered-pixel-dungeon/blob/HEAD/httpshttps/github.com/Alonso-pixel/shattered-pixel-dungeon/blob/main/core/src/main/java/com/shatteredpixel/shatteredpixeldungeon/ui/changelist/v2_X_Changes.java)

The Alchemy system is a consumable crafting mechanic in Shattered Pixel Dungeon. It allows players to combine items at an alchemy pot to create a wide variety of new items, including exotic potions, exotic scrolls, powerful spells, and enhanced bombs. The system is designed to give consumable items new uses and allow players to recycle unwanted items into more desirable ones. The primary resource for crafting is Alchemical Energy, which can be obtained from alchemy pots, by scrapping items, or through the Alchemist's Toolkit artifact.

The system was first introduced in version v0.7.0 and has undergone significant overhauls, notably in v1.1.0 which made Alchemical Energy a core resource, and v2.4.0 which removed catalysts in favor of higher energy costs for simplicity.

Sources: ui/changelist/v0_7_X_Changes.java:553-560, ui/changelist/v1_X_Changes.java:604-615, ui/changelist/v2_X_Changes.java:1010-1015

Core Components

The Alchemy system is composed of several key parts: the AlchemyScene UI, the Recipe logic, Alchemical Energy, and the in-game Alchemy Guide.

Alchemical Energy

Alchemical Energy is the primary resource for crafting. It is a global resource stored in Dungeon.energy.

• Acquisition:
  • Found in alchemy pots throughout the dungeon.
  • Generated by the AlchemistsToolkit artifact.
  • Obtained by "energizing" (scrapping) consumable items via the WndEnergizeItem window. Potions and scrolls grant energy when converted.
• Consumption:
  • Most recipes have an energy cost, defined in the Recipe's cost() method.
  • The player's available energy is checked before a recipe can be brewed. If the AlchemistsToolkit is equipped, its stored energy can also be used.

Sources: scenes/AlchemyScene.java:410-427, items/artifacts/AlchemistsToolkit.java:112-118, ui/changelist/v1_X_Changes.java:605-608, items/potions/Potion.java:312-315

Alchemy Scene

The AlchemyScene class provides the user interface for all alchemy interactions. It is displayed when the player interacts with an alchemy pot.

The UI consists of:

• Input Slots: Three InputButton components where players can place items from their inventory to be used as ingredients.
• Output Slots: Up to three OutputSlot components that display the potential items that can be crafted from the current ingredients.
• Combine Buttons: An arrow-shaped CombineButton next to each output slot, which initiates the crafting process. It also displays the Alchemical Energy cost of the recipe.
• Energy Display: Shows the player's current Alchemical Energy, plus any available from the AlchemistsToolkit. An adjacent button allows the player to energize items to gain more energy.
• Guidebook: A button to open the Alchemy Guide, which can be displayed either as a popup window or as a split-screen view on larger displays.

Sources: scenes/AlchemyScene.java:115-300

This diagram illustrates the user flow within the AlchemyScene.

Alchemy Guide

Players learn recipes through the Alchemy Guide, a document (Document.ALCHEMY_GUIDE) found in the journal. Pages for this guide (AlchemyPage) are found in alchemy rooms.

• The guide is organized into pages, each covering a category of recipes (e.g., Potions, Bombs, Spells).
• The QuickRecipe UI component is used to visually represent each recipe within the guide, showing the required ingredients and the resulting item.
• Initially, the guide was a separate window, but was later integrated into the AlchemyScene on larger displays for better usability.

Sources: journal/Document.java:161-170, items/journal/AlchemyPage.java, ui/QuickRecipe.java, scenes/AlchemyScene.java:271-298

Recipe Architecture

The crafting logic is defined by the Recipe class and its subclasses.

This diagram shows the inheritance structure for recipes. SimpleRecipe provides a template for recipes with fixed inputs and outputs.

Sources: items/Recipe.java:61-140

Recipe Class

The Recipe class is an abstract class that defines the core interface for any crafting recipe.

• testIngredients(ArrayList<Item> ingredients): Checks if the provided list of items matches the recipe's requirements.
• cost(ArrayList<Item> ingredients): Returns the Alchemical Energy cost for the recipe.
• brew(ArrayList<Item> ingredients): Consumes the ingredients and returns the crafted item.
• sampleOutput(ArrayList<Item> ingredients): Returns a sample of the output item for display in the UI, without consuming ingredients.

Sources: items/Recipe.java:63-68

SimpleRecipe Subclass

SimpleRecipe is an abstract subclass of Recipe designed for recipes with a static, predefined list of ingredients and a fixed output. It simplifies implementation by handling the ingredient checking and brewing logic based on class arrays.

• inputs: An array of Class<? extends Item> defining the required ingredient types.
• inQuantity: An array of integers for the quantity of each ingredient.
• cost: The fixed Alchemical Energy cost.
• output: The Class<? extends Item> of the resulting item.
• outQuantity: The quantity of the output item.

Sources: items/Recipe.java:71-82

Recipe Discovery

The system identifies valid recipes from a given set of ingredients using the Recipe.findRecipes() static method. This method checks the ingredients against pre-defined lists of recipes, categorized by the number of ingredients.

This flowchart shows how findRecipes efficiently filters recipes based on the number of items placed in the alchemy pot.

Sources: items/Recipe.java:214-239

Key Recipe Categories

The alchemy system supports a wide range of craftable items.

Category	Description	Example Recipes	Source File
Exotic Potions/Scrolls	Powerful variants of standard potions and scrolls, created by transmuting them or brewing them with energy.	PotionOfMastery, ScrollOfMetamorphosis	ui/changelist/v1_X_Changes.java:620-630
Spells	Unique, powerful consumables that provide utility or combat effects.	SummonElemental, TelekineticGrab, Alchemize	ui/changelist/v1_X_Changes.java:632-646
Brews & Elixirs	Potions made from boss-dropped ingredients or other special components.	CausticBrew, ElixirOfArcaneArmor	items/Recipe.java:193-195
Enhanced Bombs	Standard bombs combined with other items to add special effects like freezing or blinding.	FrostBomb, HolyBomb	ui/changelist/v0_7_X_Changes.java:280-287
Food	Combining meat or pasties to create more satiating food items.	StewedMeat, MeatPie	items/Recipe.java:208-210
Weapon/Wand Recycling	Recipes to break down unwanted equipment into materials for upgrading other items.	LiquidMetal, ArcaneResin	ui/changelist/v1_X_Changes.java:700-706

System Evolution

The Alchemy system has evolved significantly since its introduction.

• v0.7.0: The system was overhauled into a full consumable crafting system with Alchemical Energy as a resource. It introduced exotic potions/scrolls, runestones, and many new recipes.
  Sources: ui/changelist/v0_7_X_Changes.java:553-596
• v0.7.2: Introduced Alchemical Catalysts and Arcane Catalysts to make high-cost recipes more flexible by replacing specific potion/scroll ingredients. Several "filler" combination items were removed.
  Sources: ui/changelist/v0_7_X_Changes.java:388-395, 420-428
• v1.1.0: A major overhaul that made Alchemical Energy a portable resource carried by the player, rather than being tied to each pot. Players could now scrap consumables for energy. Exotic potion/scroll recipes were changed to require energy instead of seeds/stones.
  Sources: ui/changelist/v1_X_Changes.java:604-615
• v2.4.0: Catalysts were removed entirely. Recipes that required them were updated to have a higher direct energy cost to streamline the system.
  Sources: ui/changelist/v2_X_Changes.java:1010-1012