BuildersWand

Introducing BuildersWand! A free, open-source solution that gives you, and your players, the power to build quickly without breaking a sweat.

Relevant commands:

• /builderswand (Aliases: /bw) » Main command for the plugin, shows valid usage if run without arguments.
• /builderswand reload (Alias: /bw reload) » Reloads wands from the configuration file into memory.
• /builderswand list (Alias: /bw list) » Lists all wands currently configured in the plugin.
• /builderswand give <wand> <player> (Alias: /bw give) » Gives the specified player the specified wand.

Relevant permissions:

• builderswand.admin » Grants access to all admin commands and permissions.
• builderswand.use.<wand> » Allows the player to use the specified wand. Has wildcard support (e.g., builderswand.use.* to allow all wands).
• builderswand.give » Allows the player to give wands to other players.
• builderswand.reload » Allows the player to reload the plugin configuration.
• builderswand.list » Allows the player to list all configured wands.
• builderswand.notify.update » Allows the player to receive update notifications. This is a configurable permission node.

If you have any questions, feature requests, or issues, please contact me through my support Discord: https://discord.gg/j8xgCJQfGN

For anyone wondering, this is (moreorless) a spiritual successor to the abandoned BuildersWand Premium resource: https://www.spigotmc.org/resources/abandoned-builders-wand-premium-building-util-api-configurable-1-8-1-20-4.105953/.

Additionally, feel free to contribute through the GitHub repository (if possible, please ask me first so that we can hash out a good plan for your implementation first).

API

BuildersWand does feature an API, but currently there is no documentation nor hosted API jar that can be depended on. If you are a plugin author and looking for an implementable API, please contact me via my support Discord above and let me know that there is some level of interest.

Default Configuration Files

# BuildersWand Main Configuration File

# DO NOT EDIT THIS LINE!!!
# IT IS USED TO CHECK IF THE FILE IS OUTDATED AND NEEDS TO BE UPDATED
config_version: 1.5.0

# this isn't required for the build wand to work, but it does reduce the amount of fired events when placing blocks through the wand.
# set to false if you want to handle block place event cancellations yourself and don't want extra events fired.
# set to true if you want to allow other plugins to handle block place event cancellations (like WorldGuard or SuperiorSkyblock).
fireWandBlockPlaceEvent: true

# this isn't required for the build wand to work, but it does reduce the amount of fired events when using the wand.
# set to false if you don't want to add extra logic to wand usage, ideal for servers with a lot of players.
fireWandPreviewEvent: true

# This can be disabled if you want blocks to be placed instantly.
# If you notice a performance impact definitely enable this and adjust the maxBlocksPerTick value.
placementQueue:
  enabled: true
  maxBlocksPerTick: 20 # max blocks to place per tick.

# Whether to automatically remove invalid wands from players' inventories.
# An invalid wand is one that has been removed from the config or has otherwise become invalid.
# this should be kept disabled until you are sure your wands are configured correctly.
destroyInvalidWands:
  enabled: false

updater:
  enabled: true
  checkIntervalMinutes: 60
  notify:
    console: true
    ingame: true

# Only recommended when troubleshooting issues since it can generate a lot of log spam. defaults to false.
debug: false

wands:
  my_special_wand:
    name: "&3Builders Wand"
    material: "BLAZE_ROD"
    lore:
      - "&7A powerful wand for <blue>building!"
      - "&7Use it <green>wisely."
    wandType: STANDARD # defaults to STANDARD. valid types: STANDARD & STATIC.
    staticLength: 5 # only used if wandType is STATIC, otherwise ignored.
    staticWidth: 5 # only used if wandType is STATIC, otherwise ignored.
    maxSize: 8 # max block search & placement size.
    maxSizeText: "&3Max Size: {maxSize}"
    maxRayTraceDistance: 16 # max distance that the plugin will search for a block in a given direction.
    consumeItems: true # whether the wand should consume items from the player's inventory when placing blocks.
    generatePreviewOnMove: false # whether to generate a preview (small white particles) of where blocks will be placed when the player moves.
    undoHistorySize: 10 # number of undoes to store per player for this wand, defaults to 10. shift left click to undo a placement, input - 1 for unlimited and 0 to disable undoing.
    canBreakBlocksWhileCrouched: false # whether you break blocks while crouching. defaults to false, preventing accidental sensitive block breaking.
    durability:
      amount: 100
      enabled: true
      text: "&3Durability: {durability}"
      breakSound: # whether to play a sound when the wand breaks.
        enabled: false
        sound: ENTITY_ITEM_BREAK # valid sounds can be found here: https://jd.papermc.io/paper/1.21.11/org/bukkit/Sound.html
        message: "&4Your wand broke!"
    previewParticle: # paper-only
      particle: "DUST" # valid particle names can be found here: https://jd.papermc.io/paper/1.21.11/org/bukkit/Particle.html
      options: # only required for certain particles.
        color:
          red: 0
          green: 0
          blue: 0
        size: 1.0
      count: 1 # number of particles to spawn per block in the preview.
      offset:
        x: 0
        y: 0
        z: 0
      speed: 0 # speed of the particles.
    cooldown: 2 # in seconds.
    craftable: false # whether this wand can be used in crafting recipes as an ingredient.
    blockedMaterials:
      - BEDROCK
      - BARRIER
    craftingRecipe:
      enabled: false
      shape: # if this is larger than 3x3, an error will be thrown.
        - " E "
        - " S "
        - " S "
      ingredients: # ensure the ingredients listed here are valid materials.
        E: EMERALD
        S: STICK

# BuildersWand Messages Configuration
# All messages sent to players by BuildersWand are defined here.
# You can customize any message by editing the values below.
# Supports color codes (&c, &a, etc.) and MiniMessage formatting

# DO NOT EDIT THIS LINE!!!
# IT IS USED TO CHECK IF THE FILE IS OUTDATED AND NEEDS TO BE UPDATED
config-version: 1.5.0

prefix: "&7[&bBuildersWand&7] &r"

command:
  usage: "&cUsage: /builderswand <reload|list|give> <id> [player]" # <-- id and player are only needed for the give command
  reload:
    success: "&aConfiguration has been reloaded."
  no-wands: "&cNo wands found."
  wand-not-found: "&cNo wand found with ID: {id}."
  wand-received: "&aYou received a {id} wand!"
  wand-given: "&aGave {id} to {player_name}."
  only-players: "&cOnly players can give wands to themselves."
  wand-list: "&eWands: "

wand:
  placing-blocks: "&7Placing blocks... &e{remaining} &7left"
  placement-complete: "&aBlock placement complete!"

  misconfigured: "&4The wand you had was misconfigured and has been removed. Please contact an administrator immediately."
  no-permission: "&4You do not have permission to use this wand."
  still-placing: "&4Wand is still placing blocks, please wait..."
  cooldown-active: "&4Please wait &c{seconds} &4seconds before using the wand again."
  insufficient-blocks: "&4You need &c{needed} &4more &c{material} &4blocks."
  placement-disallowed: "&4Disallowed."
  nothing-to-undo: "&cNothing to undo!"
  action-undone: "&aAction undone! &c{remaining} &aundoes remaining."

updater:
  available: "&aAn update for BuildersWand is available! Check console for more info."