MekaWands Plugin Documentation
1. Overview
MekaWands is a powerful and intuitive plugin designed to enhance the building experience in Minecraft [cite: plugin.yml]. It introduces a series of tiered magic wands that allow players to perform complex block manipulation tasks—such as extending large surfaces and swapping thousands of blocks—with a single click.

The plugin is built to be efficient, server-friendly, and highly configurable, offering features like a real-time visual preview system, compatibility with protection plugins, and extensive customization options for server administrators.

2. Features

• Two Unique Wand Types: Build Wands for extending structures and Swap Wands for replacing materials [cite: config.yml].
  
  
• Tiered Progression: Each wand type comes in five distinct tiers, offering progressively larger areas of effect [cite: config.yml].
  
  
• Visual Mirage System: A real-time, client-side preview of the blocks that will be affected before the user clicks, preventing errors [cite: config.yml, MirageManager.java].
  
  
• Intuitive GUI: A simple graphical interface for selecting blocks for building and swapping [cite: BlockSelectionGUI.java].
  
  
• Infinite Durability: Wands have infinite uses and will never break [cite: WandManager.java].
  
  
• Protection Plugin Compatibility: Safely works with land-claiming plugins like WorldGuard by respecting cancelled block break and place events [cite: PlayerListener.java].
  
  
• Highly Configurable: Almost every aspect, from wand properties to mirage effects and block blacklists, can be customized in the configuration file [cite: config.yml].
  
  
• Multi-Language Support: All player-facing messages can be translated, and players can select their preferred language [cite: MessageManager.java, MekaWandsCommand.java].

3. Installation

1. Place the MekaWands.jar file into your server's /plugins folder.
   
   
2. Restart or reload your server to generate the default configuration files.
   
   
3. Modify config.yml and the language files in /plugins/MekaWands/ as needed.

4. How to Use
Obtaining Wands
Wands are given to players by an administrator using the /mekawands give command [cite: MekaWandsCommand.java].

Block Selection GUI
For Build and Swap wands, the player must first select a material to work with.

1. Hold the desired wand in your main hand.
   
   
2. Perform the action defined by gui_open_method in config.yml (default is Left-Click) [cite: config.yml, PlayerListener.java]. This will open the Block Selection GUI [cite: BlockSelectionGUI.java].
   
   
3. While the GUI is open, click on any block in your player inventory to select it. The selected block will appear in the center of the GUI [cite: BlockSelectionGUI.java].
   
   
4. To clear the selection, click the block in the center of the GUI [cite: BlockSelectionGUI.java].

Using a Build Wand

1. Select a block in the GUI. This will be the material the wand places.
   
   
2. Aim at a structure and Right-Click.
   
   
3. The wand will detect the plane of connected blocks of the same material you clicked on and extend it by one block deep in the direction you are facing [cite: PlayerListener.java].
   
   
4. Build Wands do not consume any blocks from the player's inventory [cite: PlayerListener.java].

Using a Swap Wand

1. Select a block in the GUI. This will be the new material you are swapping to.
   
   
2. Aim at a block and Right-Click.
   
   
3. The wand will replace the targeted block and all connected blocks of the same type with your selected material, up to the wand's limit [cite: PlayerListener.java].
   
   
4. This action consumes the new materials from your inventory and returns the original, swapped-out blocks to your inventory [cite: PlayerListener.java].

Swap Modes
Swap Wands have two modes, which can be toggled inside the Block Selection GUI [cite: BlockSelectionGUI.java]:

• Surfaces Only: Replaces only the blocks on the same flat plane as the clicked block [cite: PlayerListener.java, BlockSelectionGUI.java]. Ideal for changing walls and floors.
  
  
• Interiors Also: Replaces all connected blocks in a 3D space, regardless of the surface [cite: PlayerListener.java, BlockSelectionGUI.java]. Ideal for swapping ore veins or large volumes.

5. Commands and Permissions
The main command is /mekawands with the alias /mwand [cite: plugin.yml].

Command

Description

Permission

/mekawands help

Displays the help message with all commands [cite: MekaWandsCommand.java].

mekawands.command [cite: plugin.yml]

/mekawands give <player> <type> <id>

Gives a specified MekaWand to a player [cite: MekaWandsCommand.java]. type is build or swap [cite: MekaWandsCommand.java]. id is the wand's ID from config.yml [cite: MekaWandsCommand.java].

mekawands.command.give [cite: plugin.yml]

/mekawands reload

Reloads the plugin's configuration files [cite: MekaWandsCommand.java].

mekawands.command.reload [cite: plugin.yml]

/mekawands debug

Toggles debug mode for your player, showing detailed event information in chat [cite: MekaWandsCommand.java].

mekawands.command.debug [cite: plugin.yml]

/mekawands language <language_code>

Sets your preferred language for plugin messages [cite: MekaWandsCommand.java].

mekawands.command.language [cite: plugin.yml]

6. Configuration (config.yml)
The config.yml file allows for deep customization of the plugin's features.

Wand Definitions
Both build_wands and swap_wands sections follow a similar structure [cite: config.yml]. Each entry is a unique wand that can be spawned with the /mekawands give command.

build_wands:
tier_1: # This is the <id> used in the give command
name: "&aApprentice Builder's Wand" # Display name with color codes
lore: # Item description
- "&7Expands structures by 1 block deep."
- "&7Detects planes up to 4 blocks from click."
material: WOODEN_HOE # The base item for the wand
range: 4 # For Build Wands: the max search distance for the plane [cite: config.yml]
custom_model_data: 2001 # For custom textures via a resource pack

swap_wands:
tier_1:
# ...
radius: 4 # For Swap Wands: the maximum number of blocks to swap [cite: config.yml]
# ...

General Settings

• wand_nbt_key: The internal key used to identify wand items. Changing this will make existing wands stop working [cite: config.yml].
  
  
• invisible_enchantment: If true, wands will have a cosmetic enchantment glint [cite: config.yml].
  
  
• wand_cooldown_seconds: A global cooldown in seconds between each wand use [cite: config.yml].
  
  
• wand_activate_sound: The sound played on a successful right-click action [cite: config.yml].
  
  
• swap_wand_sound: A special sound played when a Swap Wand successfully swaps blocks [cite: config.yml].
  
  
• gui_open_method: Determines how to open the GUI. Options: "LEFT_CLICK", "SHIFT_RIGHT_CLICK" [cite: config.yml].

Language Settings

• default_language: The language code (e.g., "en", "pt_br") used for the console and for players who have not set a preference [cite: config.yml].

Mirage System Settings

• mirage_enabled_global: A master switch to enable or disable the entire mirage preview system [cite: config.yml].
  
  
• mirage_settings: Contains separate configuration blocks for build_wand_mirage and swap_wand_mirage [cite: config.yml].
  • enabled: Enables or disables the mirage for that specific wand type [cite: config.yml].
    
    
  • delay_seconds: Time in seconds a player must look at a block before the mirage appears [cite: config.yml].
    
    
  • display_mode (Swap Wands only): Determines the mirage material. Options are "SELECTED_BLOCK", "TARGET_BLOCK", or "FALLBACK_MATERIAL" [cite: config.yml].
    
    
  • display_material_fallback: The material used for the mirage if the primary material cannot be determined [cite: config.yml].
    
    
  • scale: The size of the mirage blocks (1.0 is full size) [cite: config.yml].
    
    
  • highlight_enabled: If true, adds a glowing outline to mirage blocks [cite: config.yml].
    
    
  • highlight_color: The hex color code for the glowing outline [cite: config.yml].
    
    
  • particle_effect_enabled, particle_effect, particle_color: Configure cosmetic particles around mirage blocks [cite: config.yml].
    
    
  • fade_in_duration_seconds, initial_brightness, final_brightness: Configure a smooth fade-in animation for the mirage blocks [cite: config.yml].

Blacklist Settings
The blacklist section allows you to prevent certain blocks from being interacted with by wands [cite: config.yml].

• build_wand_place_blocks: Blocks that cannot be selected in the GUI for building or swapping to.
  
  
• swap_wand_target_blocks: Blocks that cannot be the target of a Swap Wand (cannot be swapped from).
  
  
• build_wand_use_blocks: Blocks that cannot be right-clicked on to activate a Build Wand.
  
  
• swap_wand_use_blocks: Blocks that cannot be right-clicked on to activate a Swap Wand.

7. Language Files

• The plugin stores its language files in the /plugins/MekaWands/lang/ directory [cite: MessageManager.java].
  
  
• You can edit these files or add new ones following the messages_<locale>.yml format (e.g., messages_de.yml for German).
  
  
• To use a new language, set it as the default_language in config.yml or have players select it with the /mekawands language command [cite: config.yml, MekaWandsCommand.java].