# Configuration

This page is for server administrators who want to configure Alkatraz.

---

## Plugin Configuration (config.yml)

Located at `plugins/Alkatraz/config.yml`:

```yaml
# Update Checker
check_updates: true

# Determines how much info is logged.
# Allowed values: low, normal, high, very high, debug
verbose: normal

# The amount of stat points a player starts with. DEFAULT: 5
default_stat_points: 5

# The amount of stat reset tokens a player starts with. DEFAULT: 1
default_reset_tokens: 1

# How much affinity you gain from investing 1 stat point. DEFAULT: 10
affinity_per_point: 10

# How much resistance you gain from investing 1 stat point. DEFAULT: 10
resistance_per_point: 10

# The delay (ticks) of spawning the magic circle particles. DEFAULT: 10
circle_ticks: 10

# Unused at the moment, but keep false, otherwise some names/titles will appear weird.
resource_pack_override: false

# Whether to show the first-join tutorial to new players
first_join_tutorial: true

# Spellbook circle weights (rarity in random spellbooks)
spellbook:
  circle_weights:
    circle_1: 10000
    circle_2: 5000
    circle_3: 2500
    circle_4: 1250
    circle_5: 750
    circle_6: 375
    circle_7: 150
    circle_8: 75
    circle_9: 30

# Magic Stone drops from magic mobs
magic_stone:
  base_drop_chance: 0.75
  looting_bonus: 0.10

# Villager spellbook trading
villager_trading:
  enabled: true
  chance_two_trades: 20
  chance_one_trade: 40
  max_trades_per_villager: 2
  trade_max_uses: 3
  tiers:
    1:
      emerald_min: 4
      emerald_max: 7
      stone_min: 1
      stone_max: 1
    2:
      emerald_min: 8
      emerald_max: 13
      stone_min: 1
      stone_max: 2
    3:
      emerald_min: 14
      emerald_max: 21
      stone_min: 2
      stone_max: 3
    4:
      emerald_min: 22
      emerald_max: 31
      stone_min: 3
      stone_max: 5
    5:
      emerald_min: 32
      emerald_max: 47
      stone_min: 5
      stone_max: 8

# Imbuing system -- converts vanilla tools/weapons/armor into magic items
# using magic stones in a crafting table
imbuing:
  # Stone cost per tier (tier determined by material). DEFAULT: 1-5
  stone_costs:
    1: 1
    2: 2
    3: 3
    4: 4
    5: 5

# Recipe unlock notifications
recipes:
  unlock_notifications:
    chat: true
    title: true
    actionbar: false
    sound: true
    particles: true

# PlaceholderAPI integration settings
placeholders:
  leaderboard:
    enabled: true
    refresh_interval_minutes: 5
    max_entries: 10
```

---

## Spell Configuration

Spells are configured in `plugins/Alkatraz/spells/<spell_id>.yml`. Each file defines:

```yaml
id: 'fireball'
display_name: '&6Fireball'
description:
  - '&7A small ball of fire that can be shot'
  - '&7at an enemy.'
enabled: true              # Set to false to disable a spell
element: 'FIRE'
code: 'LLLLL'              # 5-character cast code (R/L/S)
level: 1
cooldown: 3                # Seconds
cast_time: 0.5             # Seconds
mana_cost: 15
maximum_mastery: 100
power: 2                   # Base damage
mastery_bar_color: 'RED'
gui_item: 'FIRE_CHARGE'
```

Type-specific fields (e.g., `power`, `max_hitpoints`, `base_heal`, `radius`, `duration`, `damage_per_tick`, `pull_strength`) vary by spell.

---

## Spell Options

Spell options are configured in `plugins/Alkatraz/spells/<spell_id>_options.yml`. Example:

```yaml
options:
  speed:
    description: "Adjust fireball velocity"
    icon: FEATHER
    default_index: 1

    values:
      slow:
        display_name: "Slow"
        description: "Slower projectile"
        icon: SOUL_SAND
        value_type: double
        value: 0.3
        impacts:
          - type: stat_modifier
            stat: projectile_speed
            value: 0.3
            modifier: SET
```

Option values can have:

-   **requirements** -- Conditions to unlock the value (circle level, mastery, permission)
-   **impacts** -- Effects when the value is selected (stat modifiers, mana cost changes, tags)

### Requirement Types

| Type | Description |
|------|-------------|
| `number_stat` | Requires a stat to meet a minimum value (e.g., circleLevel >= 2) |
| `boolean_stat` | Requires a boolean stat to be true |
| `permission` | Requires a Bukkit permission node |
| `option_value` | Requires another option to have a specific value |
| `composite` | AND/OR combination of requirements |
| `arcane_knowledge` | Requires minimum arcane knowledge |
| `research` | Requires completed research |
| `spell_mastery` | Requires mastery of a specific spell |
| `spell_discovered` | Requires a specific spell to be discovered |
| `mastered_spell_count` | Requires N mastered spells of a given circle |

### Impact Types

| Type | Description |
|------|-------------|
| `stat_modifier` | Modifies a spell stat (ADD/MULTIPLY/SET) |
| `mana_cost` | Changes mana cost |
| `tag` | Applies a tag to the spell |
| `cast_modifier` | Applies attribute/stat/potion effect during cast |

---

## Progression Configuration

`plugins/Alkatraz/progression.yml` defines circle requirements and rewards:

```yaml
arcane_knowledge:
  sources:
    spell_cast:
      enabled: true
      amount: 1
      circle_amounts:       # Bonus per caster circle level
        0: 1
        1: 2
        2: 4
        3: 7
        4: 14
        5: 26
        6: 50
        7: 94
        8: 179
        9: 340

research_points:
  sources:
    mastery_max:
      enabled: true
      amount: 10
    magic_mob_kill:
      enabled: true
      amount: 3
    circle_up_bonus:
      enabled: true
      amount: 50

circle:
  auto_advance: true
  levels:
    1:
      stat_points: 5
      max_mana: 200
      mana_regeneration: 2
      magic_affinity: 2
      magic_resistance: 1
      requirements:
        - type: arcane_knowledge
          amount: 300
        - type: spell_mastery
          spell: magic_missile
          mastery: 250
          description: "Requires max mastery Magic Missile"
```

---

## Magic Item Configuration

Items are defined in YAML files under `magic/items/`:

```yaml
id: 'reinforced_wand'
display_name: '&r&9Reinforced Wand'
material: BLAZE_ROD
lore:
  - '&7A wand forged in dragonfire.'
components:
  - wand
  - mana_container
  - socket_holder
attributes:
  alkatraz:spell_power: 10
  alkatraz:max_mana: 50
max_engravings: 2
max_circle: 5
cast_time_multiplier: 0.8
triggers:
  - event: on_equip
    conditions:
      - type: always
    effects:
      - type: apply_potion
        effect: HASTE
        duration_ticks: 200
        amplifier: 0
recipe:
  shape:
    - " L "
    - "IBI"
    - " S "
  ingredients:
    L: LAPIS_LAZULI
    I: IRON_INGOT
    B: BLAZE_ROD
    S: STICK
```

---

## Engraving Configuration

Engravings are defined in `magic/engravings/<engraving_id>.yml`:

```yaml
key: alkatraz:frost_rune
allowed_item_types:
  - sword
  - axe
  - wand
item:
  material: ICE
  display_name: '&bFrost Rune'
  lore:
    - '&7&oA shard of eternal ice.'
attributes:
  alkatraz:water_affinity: 10
conditions:
  - type: spell_element
    element: WATER
effects:
  - type: potion_effect
    effect: SLOWNESS
    duration_ticks: 100
    amplifier: 1
recipe:
  shape:
    - " I "
    - "SMS"
    - " M "
  ingredients:
    I: ICE
    S: SNOWBALL
    M: AMETHYST_SHARD
```

---

## Recipe Configuration

Recipes are defined in YAML files under `magic/recipes/`. Each recipe targets one crafting station (`type`) and can be gated behind requirements and permissions.

```yaml
definition: alkatraz:reinforced_wand   # Required. Magic item key (alias: id)
type: shaped                           # shaped | shapeless | furnace | blast_furnace |
                                       # smoker | campfire | brewing | smithing |
                                       # stonecutter | anvil | custom
result:
  item: BLAZE_ROD                      # Material name, or a magic item key
  amount: 1
display_name: 'Reinforced Wand'        # Optional GUI/notification name
override_vanilla: false                # Remove the conflicting Bukkit recipe with this key
hidden_when_locked: false              # Reserved GUI hint (not yet rendered)
experience: 0                          # Cooking experience default
cooking_time: 0                        # Cooking time default (native recipes use 200 if <= 0)
permissions:
  - some.permission.node               # Optional: gates crafting on a permission
unlock:
  message: '&dYou unlocked a powerful wand!'  # Optional per-recipe unlock message
requirements:
  - type: number_stat
    stat: circleLevel
    minimum: 5
    description: "Requires Circle Level 5"
```

### Ingredients

A single-character key in a shaped recipe (or an entry in a shapeless list) resolves to an ingredient:

| Form | Example | Description |
|------|---------|-------------|
| Material name | `M: MAGIC_STONE` or `- MAGIC_STONE` | A vanilla material |
| Type | `type:log` or `"type:log"` | Every material of an item type |
| Tag | `tag:minecraft:logs` or `"tag:minecraft:logs"` | A vanilla material tag |
| Magic item | `alkatraz:magic_stone` | An exact magic item (matched by definition key) |

### Station-specific fields

Station recipes use a section named after the type (or top-level `input` for cooking):

```yaml
# FURNACE / BLAST_FURNACE / SMOKER / CAMPFIRE
furnace:
  input: IRON_ORE
  experience: 0.7
  cooking_time: 200

# BREWING (potion input + brewing ingredient)
brewing:
  input: AWKWARD_POTION
  ingredient: MAGMA_CREAM

# SMITHING
smithing:
  base: DIAMOND_CHESTPLATE
  addition: NETHERITE_INGOT

# ANVIL
anvil:
  base: DIAMOND_SWORD
  addition: ENCHANTED_BOOK

# STONECUTTER
stonecutter:
  input: STONE
```

### Shaped vs Shapeless

Shaped recipes use a `shape` list plus an `ingredients` map of single characters:

```yaml
type: shaped
shape:
  - " L "
  - "IBI"
  - " S "
ingredients:
  L: LAPIS_LAZULI
  I: IRON_INGOT
  B: BLAZE_ROD
  S: STICK
```

Shapeless recipes use a plain list:

```yaml
type: shapeless
ingredients:
  - OAK_LOG
  - type:log
  - MAGIC_STONE
```

### Requirements

See [Recipes](Recipes.md#requirements) for the full list of built-in requirement types. Recipes with requirements are **locked** until the player unlocks them (via the GUI, `/recipes unlock`, or automatic evaluation). See [Crafting Gating](Recipes.md#crafting-gating) for station-specific behavior.

---

## Set Bonuses

Set bonuses are defined in `magic/set_bonuses.yml`:

```yaml
sets:
  flameheart:
    display_name: '&cFlameheart Set'
    required_count: 4
    bonus:
      - type: stat_modifier
        stat: fire_affinity
        value: 20
        modifier: ADD
```

---

## Item Types

Item type categories are defined in `magic/item_types.yml`. These determine which equipment slot an item can occupy.

---

## Loot Configuration

Loot tables and spellbook drop rates are configured in `plugins/Alkatraz/loot.yml`:

```yaml
loot:
  loot_multiplier: 1.0    # Global multiplier for all loot weights

  chest_loot:
    enabled: true
    common:
      spellbook_weight: 100
      spellbook_1_2_weight: 30
      filler_weight: 100
      max_items: 5
    dungeon:
      spellbook_1_2_weight: 80
      spellbook_1_3_weight: 60
      spellbook_2_4_weight: 20
      max_items: 1
    nether:
      fire_element_weight: 100
      spellbook_2_4_weight: 50
      spellbook_4_6_weight: 20
      max_items: 1
    end:
      spellbook_2_4_weight: 100
      spellbook_4_6_weight: 80
      spellbook_6_9_weight: 40
      air_element_weight: 60
      max_items: 2

  structure_loot:
    enabled: true
    desert_pyramid:
      fire_element_weight: 100
      spellbook_2_4_weight: 40
    ocean_ruins:
      water_element_weight: 100
      spellbook_1_3_weight: 50
    stronghold:
      spellbook_2_4_weight: 100
      spellbook_4_6_weight: 60
      dark_element_weight: 40
    woodland_mansion:
      dark_element_weight: 100
      spellbook_2_4_weight: 80

  mob_drops:
    enabled: true
    zombie:
      spellbook_weight: 100
      filler_weight: 1900
    # ... more mobs ...

  fishing:
    enabled: true
    random_spellbook_weight: 40
    water_element_weight: 50
    air_element_weight: 30
    light_element_weight: 20

  piglin_bartering:
    enabled: true
    fire_element_weight: 60
    random_spellbook_weight: 40
    nothing_weight: 900
```

See [Spellbooks & Loot](Spellbooks-and-Loot) for full details on loot sources and drop chances.

---

## Mob Configuration

Mob resistances and spell lists are in `plugins/Alkatraz/mobs/<mob>.yml`:

```yaml
# Simple mob
fire_resistance:  -40.0
water_resistance: 0.0
earth_resistance: 40.0
# ...
spells: []

# Replacement mob (spawns instead of vanilla)
replaces: zombie
spawn_chance: 5              # Percentage
spawn_reasons:
  - NATURAL
# ... resistances ...
spells:
  - fireball
```

---

## Research Configuration

Research nodes are defined in `plugins/Alkatraz/research.yml`. Each node has:

-   `display_name` -- Colored name
-   `category` -- One of: magic, fire, water, earth, air, light, dark
-   `icon` -- Material
-   `research_points_cost` -- Cost to unlock
-   `position` -- Grid position in the research tree
-   `parents` -- Prerequisite nodes
-   `objectives` -- Tasks to complete (event type, amount, optional filters)
-   `rewards` -- Bonuses granted on completion
-   `visibility` -- `hidden_until_available` controls if locked nodes are visible