# Recipes

Alkatraz features a fully configurable recipe manager that lets you browse, craft, and edit magic item recipes across **every crafting station** -- from crafting tables and furnaces to brewing stands, smithing tables, stonecutters, and anvils, plus custom recipe types. Recipes can be **gated behind unlock progression** -- players must meet requirements (or be granted the recipe) before they can craft it.

---

## Opening the Recipe Manager

Run `/recipes` to open the **Recipe Manager** GUI. From here you can browse every craftable magic item, search, inspect requirements, unlock recipes, and (with the right permissions) create, edit, duplicate, or delete recipes in-game.

The manager is organized into **9 categories**, each covering one or more recipe types:

| Category | Icon | Recipe Types |
|----------|------|--------------|
| **Crafting** | Crafting Table | `shaped`, `shapeless` |
| **Furnace** | Furnace | `furnace` |
| **Blast Furnace** | Blast Furnace | `blast_furnace` |
| **Smoker** | Smoker | `smoker` |
| **Campfire** | Campfire | `campfire` |
| **Brewing** | Brewing Stand | `brewing` |
| **Smithing** | Smithing Table | `smithing` |
| **Stonecutter** | Stonecutter | `stonecutter` |
| **Other** | Chest | `anvil`, `custom` |

---

## Recipe Types

Each recipe has a `type` that determines which station it is crafted at:

| Type | Station |
|------|---------|
| `shaped` | Crafting Table (3x3 grid) |
| `shapeless` | Crafting Table (any arrangement) |
| `furnace` | Furnace |
| `blast_furnace` | Blast Furnace |
| `smoker` | Smoker |
| `campfire` | Campfire |
| `brewing` | Brewing Stand |
| `smithing` | Smithing Table |
| `stonecutter` | Stonecutter |
| `anvil` | Anvil |
| `custom` | Custom GUI (handled by third-party adapters) |

---

## The GUI

### Category Menu

The first screen lists all categories. Each button shows how many recipes it contains. There are two additional buttons:

- **Search** (compass) -- Prompts for a search query. Matches recipe ID, display name, or result item across all categories.
- **Create** (emerald, admins only) -- Opens the recipe creation flow.

### Recipe List

Clicking a category opens a paged list of its recipes. Each entry shows the recipe's key, type, and lock status (`Unlocked` / `Locked`).

- **Sort** (hopper) -- Cycles between sort modes: Alphabetical, By Result, By ID, and Recently Edited.
- **Left-click** a recipe for details.
- **Right-click** a recipe to edit it (requires edit permission).
- **Shift-click** a recipe to delete it (requires delete permission).

### Recipe Details

The detail view shows the recipe's ingredients, result, and requirements. For locked recipes, each requirement is listed with a checkmark and a **progress bar** so players can see exactly what they still need to do.

When all requirements are met but the recipe is not yet unlocked, an **Unlock** button appears. Clicking it unlocks the recipe immediately.

### Recipe Editor

With `alkatraz.recipes.edit`, `alkatraz.recipes.create`, or `alkatraz.recipes.delete` you can manage recipes entirely in-game:

- **Edit** -- Change the result, result amount, display name, shape/ingredients, station inputs, experience, cooking time, requirements, permissions, unlock message, and toggles (override vanilla, hidden when locked).
- **Create** -- Choose a type, drag in the result item, name the recipe, then edit it.
- **Duplicate** -- Copy an existing recipe into a new key.
- **Delete** -- Remove a recipe file permanently.

All changes write directly to `plugins/Alkatraz/magic/recipes/<key>.yml` and reload the recipe registry.

---

## Unlock Progression

Recipes with `requirements` are **locked** by default. A player must unlock the recipe before it can be crafted:

- Requirements are evaluated automatically when the player joins and whenever they open a crafting menu.
- When all requirements are met, the player can click the **Unlock** button in the recipe detail view (or be unlocked via command).
- Once unlocked, the recipe stays unlocked permanently for that player.

### Unlock Notifications

When a recipe is unlocked, Alkatraz can send a chat message, title, sound, and particles. Configure these channels in `config.yml`:

```yaml
recipes:
  unlock_notifications:
    chat: true
    title: true
    actionbar: false
    sound: true
    particles: true
```

The notification shows the recipe's `display_name` (or `unlock.message` if set) and defaults to the result item's name.

### Admin Commands

| Command | Permission | Description |
|---------|------------|-------------|
| `/recipes unlock <id> [player]` | `alkatraz.recipe.unlock` | Unlock a recipe for a player |
| `/recipes lock <id> [player]` | `alkatraz.recipe.lock` | Lock a recipe for a player |
| `/recipes give <id> [player]` | `alkatraz.recipe.give` | Grant a recipe to a player |
| `/recipes check <player> <id>` | `alkatraz.recipe.check` | Check a player's unlock status |
| `/recipes reload` | `alkatraz.recipe.reload` | Reload all recipe definitions |

---

## Requirements

Requirements are conditions a player must satisfy to unlock (and craft) a recipe. Built-in requirement types:

| Type | Fields | Description |
|------|--------|-------------|
| `number_stat` | `stat`, `minimum`, `description` | A stat (e.g. `circleLevel`) must be at least `minimum` |
| `boolean_stat` | `stat`, `requires` | A boolean stat must be `true` |
| `permission` | `permission`, `description` | Player must have the permission node |
| `option_value` | `option`, `value` | A spell option must be set to a value |
| `composite` | `requirements` (nested list) | AND/OR combination of requirements |
| `arcane_knowledge` | `amount` | Minimum arcane knowledge |
| `research` | `provider`, `research` | Completed research node |
| `spell_mastery` | `spell`, `mastery` (or `minimum`) | Mastery level of a spell |
| `spell_discovered` | `spell` | Spell must be discovered |
| `mastered_spell_count` | `circle` (or `level`), `count`, `mastery` | N mastered spells of a given circle |
| `xp_level` | `minimum` | Player XP level |
| `playtime` | `minutes` | Total playtime in minutes |
| `world` | `worlds` | Player must be in one of the listed worlds |
| `recipe_unlocked` | `recipe` | Another recipe must be unlocked |

> Note: a recipe with requirements must be **explicitly unlocked** to craft -- meeting the stats alone is not enough (it only enables the Unlock button). See [Crafting Gating](#crafting-gating).

---

## Crafting Gating

- **Shaped / Shapeless** -- The result slot is cleared until the player can craft the recipe.
- **Smithing** -- The result slot is cleared for gated recipes.
- **Stonecutter** -- Result clicks are cancelled for gated recipes.
- **Brewing / Anvil** -- Results are gated, but the brewing and anvil events do not expose the crafting player, so recipes with requirements are effectively uncraftable at these stations.
- **Cooking (furnace / blast furnace / smoker / campfire)** -- Gated recipes are not registered as native smelting recipes, so they will not smelt at all (the `FurnaceStartSmeltEvent` is not cancellable in the supported Spigot API version).
- **`custom`** -- No built-in custom crafting GUI exists; custom recipes are registered in the registry and handled by third-party `CustomCraftingAdapter` implementations.

---

## Recipe Configuration

Recipes are defined in YAML files under `plugins/Alkatraz/magic/recipes/`. See [Configuration](https://github.com/NagasonicDev/Alkatraz/wiki/Configuration#recipe-configuration) for the full schema reference.