Skip to main content

​
ancBlacksmith Plugin Guide

This guide provides comprehensive instructions for setting up and configuring the ancBlacksmith plugin for your Minecraft server. The plugin allows players to trade resources for special items with customizable requirements, cooldowns, and special effects.

​
What is ancBlacksmith?

ancBlacksmith is a versatile trading plugin that allows server owners to create custom trade systems where players can exchange resources for special items. Key features include:
  • Custom trade systems with configurable requirements
  • Time-based crafting system (items take time to be “forged”)
  • Support for custom items from popular item plugins (MMOItems, EcoItems, ExecutableItems)
  • Boost system to speed up or instantly complete trades
  • Chance-based success/failure system with “burn” mechanics
  • PlaceholderAPI integration for conditional requirements
  • Multiple GUIs with customizable layouts and categories
  • Support for command execution instead of item rewards

​
Prerequisites

Before installing ancBlacksmith, you’ll need:
  • A Minecraft server running Spigot, Paper, or a compatible fork (1.19+)
  • Server operator permissions or FTP access to your server files
  • Optional but recommended plugins:
    • Vault (for economy integration)
    • PlayerPoints (for point-based trades)
    • PlaceholderAPI (for advanced conditions)
    • Item plugins: MMOItems, EcoItems, ExecutableItems (for special items)

​
Installation

  1. Download the ancBlacksmith plugin from a trusted source
  2. Place the plugin JAR file in your server’s plugins directory
  3. Restart your server to generate default configuration files
  4. The plugin will create several configuration files, including:
    • config.yml - Main configuration file
    • modules/boosts.yml - Configuration for time and instant boosts
    • modules/item-burns.yml - Configuration for the burn mechanic
    • lang/lang_en.yml - Language and GUI configuration

​
Configuration Overview

​
Main Configuration (config.yml)

The main configuration file is divided into several sections:

​
Basic Configuration

config:
  version: 1.1.1  # Auto-injected version number
  lang: "en"      # Language setting ("en" or "tr")
  complete:
    sound: "ENTITY_PLAYER_LEVELUP"  # Sound when trade completes
    particleEffect: "VILLAGER_HAPPY"  # Particles when trade completes
    particleCount: 10  # Number of particles

​
Category Menu Configuration

You can organize trades into categories for easier navigation: 
category_menu:
  title: "Trade Category Menu"
  size: 3  # Number of rows in the GUI
  categories:
    armors:
      material: "NETHERITE_CHESTPLATE"  # Item representing this category
      name: "&7Category: &c&lARMORS"  # Display name
      lore:  # Item description
        - ""
        - "&7 Click here to see all "
        - "&7 possible armor trades "
        - "&7 available. "
        - ""
      slot: 11  # Position in the GUI
      trades:  # List of trade IDs in this category
        - 1
    weapons:
      material: "IRON_SWORD"
      name: "&7Category: &6&lWEAPONS"
      lore:
        - ""
        - "&7 Click here to see all "
        - "&7 possible weapon trades "
        - "&7 available. "
        - ""
      slot: 15
      trades:
        - 2

​
Trade Configuration

Each trade is defined with a unique ID and includes reward item details and requirements: 
smith:
  trades:
    1:  # Trade ID
      item:  # Reward item configuration
        material: "DIAMOND_PICKAXE"
        name: "&6&lSAGARIS &8-- &5Rare"
        lore:
          - ""
          - "&7 This pickaxe, crafted by the "
          - "&7 ancient Persians holds a great "
          - "&7 value, it's power comes from the "
          - "&7 diamonds that were mined in the "
          - "&7 great cave, Sagaris. "
          - ""
        enchantments:
          - "EFFICIENCY:5"
          - "SILK_TOUCH:1"
        as-command: false  # Whether to run a command instead of giving an item
        time: 3600  # Time in seconds to complete the trade (1 hour)
      requirements:  # What players need to trade
        0:
          display_name: "&bDiamond"
          material: "DIAMOND"
          amount: 32
        1:
          display_name: "&ePoints"
          material: "PLAYERPOINT"
          amount: 500
        2:
          display_name: "&eMoney"
          material: "MONEY"
          amount: 1000

​
Boost Module Configuration (modules/boosts.yml)

Boosts allow players to speed up or instantly complete trades: 
boosts:
  boost1:  # Time boost example
    material: "EMERALD"
    name: "&e&lTIME BOOST &8(&f4x&8) (&f1 hour&8)"
    lore:
      - ""
      - "&8• &f&lINFORMATION"
      - ""
      - " &7Using this item will make your trades go 4x faster for 1 hour."
      - ""
      - "&a[Right click to use]"
      - ""
    boost-information:
      type: "TIME"
      multiplier: 4  # Speed multiplier
      duration: 60  # Duration in minutes
  
  boost2:  # Instant boost example
    material: "DIAMOND"
    name: "&e&lINSTANT BOOST &8(&f1 use&8)"
    lore:
      - ""
      - "&8• &f&lINFORMATION"
      - ""
      - " &7Using this item will instantly finish one of your trades."
      - ""
      - "&a[Right click to use]"
      - ""
    boost-information:
      type: "INSTANT"
      uses: 1  # Number of uses

​
Burn Module Configuration (modules/item-burns.yml)

The burn mechanism adds a chance for trades to fail: 
burns:
  enabled: true  # Enable/disable burn mechanics
  bypass-permission: "ancblacksmith.bypass-burns"  # Permission to bypass burns
  format:  # Display format for success rate
    - ""
    - "&8• &7Success rate:"
    - "&8 • &f{success_rate}%"
  burnSound: "ENTITY_ENDERDRAGON_GROWL"  # Sound when trade burns
  burnParticleEffect: "SMOKE_NORMAL"  # Particle effect when trade burns
  burnParticleCount: 10  # Number of particles
  bypassText: " &8(&6&lBYPASS&8)"  # Text shown to users with bypass permission
  configuration:  # Burn settings for specific trades
    1:
      burn-chance: 10  # 10% chance to burn
      active-trades:  # Trade IDs that use this setting
        - 2
    2:
      burn-chance: 5  # 5% chance to burn
      active-trades:
        - 1

​
Language and GUI Configuration (lang/lang_en.yml)

This file contains all messages and GUI settings: 
message:
  prefix: "&8[&6ancBlacksmith&8] &7"
  no_permission: "You do not have permission to use this feature."
  # ...other messages...

menu:
  main-gui:
    title: "Blacksmith Main Menu"
    rows: 6
    # ...GUI settings...
  
  second-gui:
    title: "&8Trade List"
    rows: 3
    # ...GUI settings...

​
Advanced Features

​
Custom Items Support

ancBlacksmith supports integration with popular custom item plugins:
  1. MMOItems:
item:
  material: "MMOITEMS"
  mmoitems-id: "DRAGON_HELMET"
  type: "ARMOR"
  time: 3600
  1. EcoItems:
item:
  material: "ECOITEMS"
  ecoitems-id: "enchanted_cobblestone"
  time: 3600
  1. ExecutableItems:
item:
  material: "EXECUTABLEITEMS"
  execitems-id: "armorpiece1_v1_8"
  time: 3600

​
PlaceholderAPI Conditions

You can create requirements based on PlaceholderAPI conditions: 
requirements:
  1:
    display_name: "&e10 Level Required"
    material: "PLACEHOLDER"
    condition: "%math_{player_level}>=10%"
    required-output: 1
  2:
    display_name: "&eVIP Required"
    material: "PLACEHOLDER"
    condition: "%vault_hasgroup_VIP%"
    required-output: "yes"

​
Item Requirements with Specific Properties

You can require items with specific names, lore, or custom model data: 
requirements:
  1:
    display_name: "&bDiamond"
    required_name: '&bRare Diamond'
    required_lore:
      - ''
      - '&bThis is a rare diamond!'
      - ''
    material: "DIAMOND"
    amount: 16

​
Commands and Permissions

​
Main Commands

  • /blacksmith or /bsmith - Opens the main blacksmith menu
  • /blacksmith reload - Reload plugin configuration files
  • /blacksmith giveboost <player> <boost> - Give a boost item to a player

​
Permissions

  • ancblacksmith.use - Base permission to use the plugin
  • ancblacksmith.admin - Admin permission for reload and giveboost commands
  • ancblacksmith.bypass-burns - Permission to bypass burn chance
  • ancblacksmith.slot.<number> - Permission to use specific trade slots

​
Troubleshooting

​
Common Issues and Solutions

ProblemSolution
Plugin doesn’t loadCheck server version compatibility and ensure all dependencies are installed
Trades not appearing in menuVerify trade IDs and category configurations
Custom items not workingMake sure required item plugins are installed and configured correctly
PlaceholderAPI conditions not workingInstall necessary PlaceholderAPI expansions with /papi ecloud download <expansion>
Players can’t start tradesCheck permission settings and requirement configurations
Items with wrong names not being acceptedEnsure required_name matches exactly (including color codes)

​
Debug Mode

To troubleshoot issues, you can enable debug mode in the config.yml file (if supported by your plugin version).

​
Example Configurations

​
Basic Diamond Tool Trade

smith:
  trades:
    1:
      item:
        material: "DIAMOND_PICKAXE"
        name: "&b&lMiner's Friend"
        lore:
          - "&7A powerful mining tool"
        enchantments:
          - "EFFICIENCY:3"
          - "UNBREAKING:2"
        time: 300
      requirements:
        1:
          display_name: "Iron Ingot"
          material: "IRON_INGOT"
          amount: 32
        2:
          display_name: "Diamond"
          material: "DIAMOND"
          amount: 3

​
Command Reward Trade

smith:
  trades:
    2:
      item:
        material: "PAPER"
        name: "&e&lVIP Rank Voucher"
        lore:
          - "&7Trade for temporary VIP rank"
        as-command: true
        command:
          - "lp user {player} parent add vip"
          - "broadcast &e{player} has acquired the VIP rank!"
        time: 7200
      requirements:
        1:
          display_name: "&eMoney"
          material: "MONEY"
          amount: 5000

​
Support and Contact

For additional assistance with ancBlacksmith configuration:
  • Join our Discord server for support
  • Email us for premium support options
  • Visit our website for more plugins and resources

​
Conclusion

The ancBlacksmith plugin offers powerful trading mechanics to enhance your Minecraft server’s economy and player engagement. With its extensive customization options, you can create a unique trading experience tailored to your server’s theme and needs.