Skip to content

Configuration

Jump to bottom
NagasonicDev edited this page Aug 16, 2026 · 2 revisions

Configuration

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

Plugin Configuration (config.yml)

Located at plugins/Alkatraz/config.yml:

# 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:

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:

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:

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/:

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:

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.

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):

# 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:

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

Shapeless recipes use a plain list:

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

Requirements

See Recipes 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 for station-specific behavior.

Set Bonuses

Set bonuses are defined in magic/set_bonuses.yml:

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:

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 for full details on loot sources and drop chances.

Mob Configuration

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

# 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

Alkatraz Wiki

Getting Started

Spells & Casting

Progression

Equipment & Items

World & Mobs

Commands & Admin

Developer

Clone this wiki locally