Configuration

Configuring enchants.yml

The enchants.yml file is the heart of EnchantCore's customization, allowing you to define and modify every aspect of the enchantments available on your server.

File Location: /plugins/EnchantCore/enchants.yml

Structure Overview:

The file is primarily divided into two main sections:

1. EnchantGUI: Settings for the main enchantment upgrade GUI.

2. enchants: A map where each key is a unique identifier for an enchantment (e.g., efficiency, explosive_custom), and its value is a section containing all configurations for that specific enchant.

EnchantGUI Section:

This section controls the appearance and global behavior of the enchantment upgrade menu.

YAML

EnchantGUI:
  Title: "#3B3B98&lPickaxe Enchantments" # Title of the GUI, supports color codes
  Size: 54 # Must be a multiple of 9, up to 54
  FillEmptySlots: true # true/false - whether to fill empty GUI slots
  FillerMaterial: BLACK_STAINED_GLASS_PANE # Material for filler items
  FillerName: " " # Name for filler items (can be empty for no name)
  FillerCustomModelData: 0 # CustomModelData for filler items
  # Static Items (Optional)
  Items:
    # Example: A border item
    # border_top:
    #   Material: LIME_STAINED_GLASS_PANE
    #   Name: "&a "
    #   Lore:
    #     - "&7This is a border item."
    #   Slots: [0,1,2,3,4,5,6,7,8] # List of slots to place this item
    #   CustomModelData: 0
    #   Amount: 1
    #   # CommandsOnClick: # Commands run when this static item is clicked
    #   #  - "console: say Player %player% clicked the border!"
    #   #  - "player: somecommand"
    # Example: An info item
    # info_book:
    #   Material: BOOK
    #   Name: "&eInformation"
    #   Lore:
    #     - "&7Click here for help!"
    #   Slots: [4] # Typically center-top

• Title: The title displayed at the top of the GUI. Supports standard Minecraft color codes (&) and hex codes (#RRGGBB).

• Size: The number of slots in the GUI. Must be a multiple of 9 (e.g., 9, 18, 27, 36, 45, 54).

• FillEmptySlots: If true, empty slots not occupied by enchantments or static items will be filled with the FillerMaterial.

• FillerMaterial: The Bukkit Material name for the item used to fill empty slots.

• FillerName: The display name for filler items. Use " " for a visually empty name.

• FillerCustomModelData: If using a resource pack, the custom model data for the filler item.

• Items (Static Items - Premium Feature):

  • Define static, non-enchantment items in your GUI (e.g., borders, info buttons, navigation items).

  • Each key under Items (e.g., border_top, info_book) is a unique ID for that static item.

  • Material: Bukkit Material name.

  • Name: Display name (supports color codes).

  • Lore: List of lore lines (supports color codes and placeholders if relevant to context).

  • Slots: A list of slot numbers (0-indexed) where this item should be placed.

  • CustomModelData: (Optional) For resource packs.

  • Amount: (Optional, defaults to 1) Number of items in the stack.

  • CommandsOnClick: (Optional) A list of commands to execute when this static item is clicked.

    • Prefix with console: to run as console (e.g., console: eco give %player% 100).

    • Prefix with player: or no prefix to run as player (e.g., player: warp help).

    • %player% placeholder is available.

enchants Section - Defining Enchantments:

This is where you define each individual enchantment. Each enchantment has its own section, keyed by a unique identifier you choose (e.g., efficiency, my_explosive_enchant).

Example Structure for one Enchantment:

YAML

enchants:
  # --- Efficiency Example (Vanilla Wrapper) ---
  efficiency:
    RawName: "efficiency"             # REQUIRED: Unique internal ID (lowercase, no spaces). Used by commands/PDC.
    Name: "#a1e8a1&lEfficiency"       # REQUIRED: Display name used in chat, messages. Supports color codes.
    GuiName: "#a1e8a1&lEfficiency"    # (Optional) Name in GUI item title (appends level). Defaults to Name.
    Material: BEACON                  # REQUIRED: Bukkit Material for the GUI item.
    # Base64: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYmFkY..." # (Optional) For custom player heads. Overrides Material if valid.
    CustomModelData: 0                # (Optional) For resource pack item models.
    Enabled: true                     # REQUIRED: true/false - Whether this enchant is loaded and usable.
    InGuiSlot: 19                     # REQUIRED: Slot number in GUI (0-indexed). -1 to hide from GUI (still usable via commands if enabled).
    MaxLevel: 100                     # REQUIRED: Maximum level (must be >= 1). Use 0 for effectively unlimited (plugin might cap).
    Cost: 100.0                       # REQUIRED: Cost for the first level (or level 0 to 1).
    IncreaseCostBy: 1.12              # REQUIRED: Factor/amount cost increases by. Behavior depends on CostFormula.
    CostFormula: "EXPONENTIAL"        # REQUIRED: "LINEAR" or "EXPONENTIAL".
    PickaxeLevelRequired: 0           # REQUIRED: Minimum EnchantCore Pickaxe level needed to purchase/upgrade. 0 for no requirement.
    MinecraftEnchantKey: "minecraft:efficiency" # (Optional) If wrapping a vanilla enchant, its Minecraft key (e.g., "minecraft:sharpness").
                                      # Plugin will attempt to apply the vanilla effect alongside custom logic.
    Description:                      # (Optional) General description for the enchant (used by %description% placeholder).
      - "&7Breaks blocks faster."
      - "&7A classic enhancement."
    lore:                             # REQUIRED: List of strings for the GUI item's lore. Supports placeholders.
      - "&7Gives your pickaxe an ability to break blocks faster"
      - " " # Empty line for spacing
      - "&3&lInfo:"
      - "&8| &bPrice: &f%cost%"
      - "&8| &bMax Level: &f%max_level%"
      - "&8| &bCurrent Level: &f%current_level%"
      - "&8| &bReq. Pick Level: &f%pickaxe_level_required%"
      - " "
      # Specific attribute lines can be added here if your placeholders support them
      # E.g., for a chance-based enchant:
      # - "&6&lAttributes:"
      # - "&8| &eChance: &f%chance%%"

    Settings:                         # (Optional) Section for enchant-specific custom settings.
                                      # Common settings examples:
      # For Chance-Based Enchants:
      ChanceBase: 0.05                # Base chance as a decimal (e.g., 0.05 = 5%)
      ChanceIncreasePerLevel: 0.01    # Decimal increase per level (e.g., 0.01 = +1% per level)
      Message: "&6&lBOOM! &fExplosive activated!" # Message on activation

      # For Enchants with Radius (e.g., Explosive):
      RadiusTier: 2                   # Maps to predefined radii (1=2, 2=3, 3=4, 4=5, 5=6)
      # OR
      RadiusBase: 2                   # Base radius for level 1
      RadiusIncreasePerLevel: 0.5     # How much radius increases per level

      # For Enchants with Duration (e.g., BlockBooster):
      DurationBase: 30                # Base duration in seconds for level 1
      DurationIncreasePerLevel: 5     # Seconds added per level

      # For Enchants with Multiplier (e.g., BlockBooster):
      MultiplierBase: 1.1             # Base multiplier for level 1 (e.g., 1.1 for 1.1x)
      MultiplierIncreasePerLevel: 0.1 # Added per level

      # For Enchants giving Rewards (e.g., Salary, Tokenator, Blessing, Charity):
      RewardMinBase: 100              # Minimum reward amount at level 1
      RewardMinIncreasePerLevel: 10   # How much min reward increases per level
      RewardMaxBase: 500              # Maximum reward amount at level 1
      RewardMaxIncreasePerLevel: 50   # How much max reward increases per level
      # Specific messages for enchants like Blessing/Charity:
      MessageGave: "&b&lBLESSED! &fYou shared %amount% with %count% players!"
      MessageReceived: "&b&lBLESSED! &fYou received %amount% from %player%!"

      # For Enchants running Commands (e.g., KeyFinder, VoucherFinder):
      Commands:                       # List of commands to run by console
        - "crate key give %player% Common 1"
        - "eco give %player% 50"
      # CommandMessage: "&eYou found something special!" # Replaced by 'Message' generally

      # For Nuke Enchant:
      BreakBedrock: false             # true/false
      CountdownSeconds: 5
      CountdownBossBarEnabled: true
      BossBarTitle: "&c&lNuke Detonating in: &e%countdown%s"
      BossBarColor: "RED"             # (BLUE, GREEN, PINK, PURPLE, RED, WHITE, YELLOW)
      ParticleEffectEnabled: true

Key Enchantment Parameters Explained:

• RawName (Required): The internal, unique ID for the enchantment. Must be all lowercase with no spaces (underscores or hyphens are okay). This is used for commands, storing data (PDC), and identifying the enchant in other configs. Cannot be changed once set without data loss.

• Name (Required): The display name of the enchantment, shown in messages, chat, and potentially in lore via placeholders. Supports color codes.

• GuiName (Optional): The name shown for the item in the GUI. If omitted, it defaults to the Name. The player's current level for that enchant is automatically appended to this in the GUI.

• Material (Required): The Bukkit Material name for the item that represents this enchantment in the GUI (e.g., DIAMOND_SWORD, TNT, EXPERIENCE_BOTTLE).

• Base64 (Optional): For using custom player heads as icons. Provide the Base64 texture value here. If valid, this will override the Material.

• CustomModelData (Optional): An integer value for custom model data if you are using a resource pack to change item appearances. Defaults to 0.

• Enabled (Required): Set to true for the enchantment to be loaded and usable. Set to false to disable it.

• InGuiSlot (Required): The numerical slot where this enchantment will appear in the /enchant GUI (0 is the top-left slot). Use -1 if you want the enchant to be active but not visible in the GUI (e.g., hidden admin enchants, or enchants only obtainable via commands).

• MaxLevel (Required): The maximum level this enchantment can reach. Must be 1 or greater. A value of 0 is typically interpreted by the plugin as effectively unlimited, though there might be an internal hard cap.

• Cost (Required): The base cost (in Tokens or Vault currency, depending on config.yml) to acquire Level 1 of this enchantment (or to upgrade from Level 0 to 1).

• IncreaseCostBy (Required):

  • This value controls how the cost increases with each level. It works differently depending on the CostFormula you choose:

    • LINEAR The cost goes up by a fixed amount every level. Formula: Cost = BaseCost + IncreaseCostBy × (Level - 1) Example: If BaseCost = 100 and IncreaseCostBy = 50, then Level 1 = 100, Level 2 = 150, Level 3 = 200, and so on.

    • EXPONENTIAL The cost multiplies each level, growing faster over time. Formula: Cost = BaseCost × (IncreaseCostBy ^ (Level - 1)) Example: If BaseCost = 100 and IncreaseCostBy = 1.1, then Level 1 = 100, Level 2 = 110, Level 3 = 121, and so on.

    💡 For exponential growth, use a value greater than 1.0 (like 1.1) to make the cost increase with each level.

• CostFormula (Required): Defines how the cost scales.

  • LINEAR: Additive increase.

  • EXPONENTIAL: Multiplicative increase.

• PickaxeLevelRequired (Required): The minimum level the player's EnchantCore Pickaxe must be before they can purchase or upgrade this specific enchantment. Set to 0 if there's no pickaxe level restriction.

• MinecraftEnchantKey (Optional): If this custom enchantment should also apply a corresponding vanilla Minecraft enchantment effect (e.g., your custom "Super Efficiency" also gives vanilla Efficiency), specify the vanilla key here (e.g., minecraft:efficiency, minecraft:looting). The plugin will attempt to apply this vanilla enchant to the pickaxe alongside its custom effects.

• Description (Optional): A list of strings providing a general description of the enchant. This can be used in lore with the %description% (for the first line) or %description_multiline% (for all lines joined) placeholders.

• lore (Required): A list of strings that define the lore for this enchantment's item in the GUI. This is highly customizable.

  • Supports color codes (& and #RRGGBB).

  • Supports various Placeholders (see below).

• Settings (Optional): A sub-section for enchantment-specific parameters. The available settings depend on the enchantment's type and how it's coded in the Java part of the plugin. Common examples are provided above (Chance, Radius, Duration, Rewards, Commands, etc.).

Common Lore Placeholders:

When defining the lore for an enchantment item in the GUI, you can use these placeholders:

• %enchant_name%: The display Name of the enchantment.

• %current_level% or %level%: The player's current level for this enchantment.

• %max_level%: The MaxLevel defined for this enchantment.

• %cost%: The cost to upgrade to the next level. Displays "Maxed" or "N/A" appropriately.

• %pickaxe_level_required%: The PickaxeLevelRequired for this enchant.

• %description%: The first line from the enchant's Description list.

• %description_multiline%: All lines from the enchant's Description list, joined.

Placeholders from Settings (Examples - depend on what your Java code looks for):

• %chance%: Typically ChanceBase + (ChanceIncreasePerLevel * level), formatted as a percentage.

• %radius%: Current radius of an AoE enchant.

• %duration%: Current duration of a timed enchant.

• %multiplier%: Current multiplier of a booster enchant.

• %min_amount%: Minimum reward amount for the current level.

• %max_amount%: Maximum reward amount for the current level.

• (Your plugin's Java code for EnchantmentWrapper.applyPlaceholdersToLine() determines exactly which placeholders from the Settings section are processed and how).

Creating Your Own Enchantments ((Command Based Only)Premium Feature)

With EnchantCore-Premium, you can create custom enchantments that run commands when triggered. These enchantments do not require any Java coding and can be added directly in the enchants.yml file.

You can add as many of these command-based enchantments as you like. Just make sure the action is limited to executing commands.

For example, the VoucherFinder enchantment gives players a voucher while they are mining by simply executing a command. You can define how often it triggers, what command it runs, and customize messages or rewards.

To create your own (you can just copy and paste the voucherfinder enchant):

• Add a new section under enchants:

• Give it a unique RawName like AnotherKeyAllEnchant

• Fill out required fields such as Name, Material, MaxLevel, and Cost

• Under Settings, specify the command you want to run when the enchant activates

Since these enchants are based on command execution, there is no need to touch the plugin’s Java code. Everything can be controlled through configuration.

Make sure to back up your enchants.yml file before making any changes.

Always back up your enchants.yml before making significant changes! Refer to the Java documentation or specific examples for how to make new enchant Settings readable by the plugin if you are developing custom Java handlers.