Main Configuration (config.yml)

Configuration File (config.yml)

The config.yml file is the main configuration file for BuildersWand that controls all aspects of the plugin's behavior, permissions, performance, and integrations.

File Location

plugins/BuildersWand/config.yml

General Settings

Plugin Version

general:
  config-version: 1.0.0 # DO NOT CHANGE THIS VALUE

• Purpose: Used for automatic configuration migration

• Important: Never manually change this value

Debug Mode

general:
  debug: false

• Purpose: Enables detailed logging for troubleshooting

• Values: true or false

• Use Case: Enable when experiencing issues or need detailed logs

Language

general:
  language: "en"

• Purpose: Sets the language for all plugin messages

• Supported: en (English), de (German), es (Spanish)

• Default: en

Wand Settings

Rendering

wand:
  rendering:
    render-interval: 3

• Purpose: Controls how often the block preview updates

• Values: 1-20 (ticks, where 20 ticks = 1 second)

• Lower values: Smoother preview but higher CPU usage

• Higher values: Better performance but less smooth preview

Physics

wand:
  physics:
    break-enabled: true
    place-enabled: true
    update-delay: 1
    max-blocks-per-update: 50

• break-enabled: Whether blocks break with physics (sand falling, etc.)

• place-enabled: Whether blocks place with physics (water flow, etc.)

• update-delay: Delay between physics updates in ticks

• max-blocks-per-update: Maximum blocks processed per physics update

Undo System

wand:
  undo:
    enabled: true
    max-actions: 3

• enabled: Whether the undo feature is active

• max-actions: Maximum number of actions to remember per player

Usage Restrictions

Limits

restrictions:
  limits:
    max-blocks-per-use: 10000
    max-blocks-per-second: 100

• max-blocks-per-use: Maximum blocks that can be placed/broken in a single action

• max-blocks-per-second: Anti-lag protection - maximum blocks per second

Permission-Based Restrictions

restrictions:
  permissions:
    require-wand-permissions: true
    require-world-permissions: false
    require-region-permissions: false
    allow-bypass-permission: true

• require-wand-permissions: Whether each wand type requires specific permissions

• require-world-permissions: Whether players need permissions for each world

• require-region-permissions: Whether players need permissions for each WorldGuard region

• allow-bypass-permission: Whether bypass permissions are allowed

World Restrictions

restrictions:
  worlds:
    disabled-worlds:
      - "world_nether"
      - "world_the_end"
    restricted-worlds:
      - "world"
    creative-only: false
    survival-only: false
    prevent-placement-near-entities: false
    prevent-placement-near-players: false
    entity-block-radius: 1.0
    player-block-radius: 2.0

• disabled-worlds: Worlds where wands are completely disabled

• restricted-worlds: Worlds where wands only work in specific regions

• creative-only: Whether wands only work in creative mode

• survival-only: Whether wands only work in survival mode

• prevent-placement-near-entities: Prevent block placement near entities

• prevent-placement-near-players: Prevent block placement near players

• entity-block-radius: Radius in blocks to check for nearby entities

• player-block-radius: Radius in blocks to check for nearby players

Block Restrictions

Global Block Restrictions

blocks:
  global:
    blacklisted-blocks:
      - "BEDROCK"
      - "COMMAND_BLOCK"
      - "BARRIER"
      - "STRUCTURE_BLOCK"
    place-only-blocks:
      - "OBSIDIAN"
      - "CRYING_OBSIDIAN"
    break-only-blocks:
      - "DIAMOND_ORE"
      - "EMERALD_ORE"

• blacklisted-blocks: Blocks that cannot be placed or broken by any wand

• place-only-blocks: Blocks that can only be placed (not broken)

• break-only-blocks: Blocks that can only be broken (not placed)

Material-Specific Restrictions

blocks:
  materials:
    max-per-material:
      diamond_ore: 10
      emerald_ore: 10
      ancient_debris: 5
    permission-required:
      diamond_ore: "builderswand.break.diamond"
      emerald_ore: "builderswand.break.emerald"
      ancient_debris: "builderswand.break.ancient_debris"

• max-per-material: Maximum blocks of each material per use

• permission-required: Specific permissions required for certain materials

Performance & Anti-Lag

Anti-Lag Settings

performance:
  anti-lag:
    enabled: true
    max-blocks-per-tick: 100
    max-processing-time: 10
    operation-delay: 2
    spread-operations: true

• enabled: Whether anti-lag features are active

• max-blocks-per-tick: Maximum blocks processed per server tick

• max-processing-time: Maximum time spent processing per tick (milliseconds)

• operation-delay: Delay between large operations (ticks)

• spread-operations: Whether to spread operations across multiple ticks

Memory Management

performance:
  memory:
    max-cached-selections: 10
    cache-cleanup-interval: 600
    max-memory-usage: 100

• max-cached-selections: Maximum cached selections per player

• cache-cleanup-interval: How often to clean up cache (ticks)

• max-memory-usage: Maximum memory usage for selections (MB)

Optimization

performance:
  optimization:
    async-processing: true
    batch-updates: true
    chunk-based-processing: true
    max-chunks-per-operation: 4

• async-processing: Use async processing where possible

• batch-updates: Batch block updates for better performance

• chunk-based-processing: Use chunk-based processing for large operations

• max-chunks-per-operation: Maximum chunks to process per operation

User Interface & Feedback

Messages

ui:
  messages:
    enabled: true
    prefix: "&8[&bBuildersWand&8] "
    show-wand-mode: true
    show-durability: true

• enabled: Whether messages are shown to players

• prefix: Prefix for all plugin messages

• show-wand-mode: Show current wand mode in action bar

• show-durability: Show current durability in action bar

Sound Effects

ui:
  sounds:
    enabled: true
    wand-break-sound: "ENTITY_ITEM_BREAK"
    block-place-sound: "BLOCK_STONE_PLACE"
    block-break-sound: "BLOCK_STONE_BREAK"
    mode-change-sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
    storage-open-sound: "BLOCK_CHEST_OPEN"
    permission-denied-sound: "ENTITY_VILLAGER_NO"
    volume: 1.0
    pitch: 1.0

• enabled: Whether sound effects are played

• volume: Sound volume (0.0 to 1.0)

• pitch: Sound pitch (0.0 to 2.0)

Administrative Features

Logging

admin:
  logging:
    enabled: false
    log-usage: true
    log-placement: true
    log-breaking: true
    log-permissions: true
    log-errors: true
    log-to-console: true
    log-to-file: true
    log-file: "builderswand.log"
    max-log-size: 10

• enabled: Whether logging is active

• log-usage: Log wand usage

• log-placement: Log block placement

• log-breaking: Log block breaking

• log-permissions: Log permission denials

• log-errors: Log errors and exceptions

• log-to-console: Log to server console

• log-to-file: Log to file

• log-file: Log file name

• max-log-size: Maximum log file size (MB)

Monitoring

admin:
  monitoring:
    enabled: false
    track-player-usage: true
    track-wand-usage: true
    track-block-stats: true
    save-stats: true
    stats-file: "builderswand-stats.json"
    stats-save-interval: 30

• enabled: Whether usage statistics are tracked

• track-player-usage: Track wand usage per player

• track-wand-usage: Track wand usage per wand type

• track-block-stats: Track block placement statistics

• save-stats: Save statistics to file

• stats-file: Statistics file name

• stats-save-interval: How often to save statistics (minutes)

Advanced Options

Plugin Integrations

WorldGuard Integration

advanced:
  integrations:
    worldguard:
      enabled: true
      check-regions: true
      allow-bypass: true

• enabled: Whether WorldGuard integration is active

• check-regions: Check WorldGuard regions for permissions

• allow-bypass: Allow bypass permission for WorldGuard

WorldGuard Permissions:

• builderswand.bypass.worldguard - Bypass all WorldGuard restrictions

• builderswand.use.region.<region_name> - Use wands in specific regions

• builderswand.use.world.<world_name> - Use wands in specific worlds

WorldGuard Region Setup:

1. Create regions in WorldGuard

2. Set appropriate flags for the regions

3. Grant players region-specific permissions

4. Configure require-region-permissions: true in config

CoreProtect Integration

advanced:
  integrations:
    coreprotect:
      enabled: true
      log-operations: true
      log-rollback: true

• enabled: Whether CoreProtect integration is active

• log-operations: Log all block operations

• log-rollback: Log rollback data for undo system

ItemsAdder Integration

advanced:
  integrations:
    itemsadder:
      enabled: true
      support-custom-blocks: true
      support-custom-items: true

• enabled: Whether ItemsAdder integration is active

• support-custom-blocks: Support custom blocks from ItemsAdder

• support-custom-items: Support custom items from ItemsAdder

Migration Settings

migration:
  auto-migrate: true
  backup-old-config: true
  backup-location: "backups/"
  backup-retention: 30

• auto-migrate: Automatically migrate old config formats

• backup-old-config: Backup old config before migration

• backup-location: Where to store backup files

• backup-retention: How long to keep backup files (days)

Permission Hierarchy

The permission system follows this hierarchy:

1. Global Bypass: builderswand.bypass - Bypass all restrictions

2. World Bypass: builderswand.bypass.worldguard - Bypass WorldGuard

3. World Permissions: builderswand.use.world.<world_name> - World-specific

4. Region Permissions: builderswand.use.region.<region_name> - Region-specific

5. Wand Permissions: builderswand.use.<wand_type> - Wand-specific

6. Material Permissions: builderswand.break.<material> - Material-specific

WorldGuard Integration Details

Region-Based Permissions

When require-region-permissions: true is enabled:

1. Region Detection: The plugin automatically detects which WorldGuard regions a player is in

2. Permission Check: For each region, it checks builderswand.use.region.<region_name>

3. Bypass Option: Players with builderswand.bypass.worldguard can bypass all region checks

4. Multiple Regions: If a player is in multiple regions, they need permission for at least one

World-Based Permissions

When require-world-permissions: true is enabled:

1. World Check: Checks if player has builderswand.use.world.<world_name>

2. Bypass Option: Players with builderswand.bypass.worldguard can bypass world checks

3. Integration: Works alongside region permissions

Example WorldGuard Setup

# In config.yml
restrictions:
  permissions:
    require-world-permissions: true
    require-region-permissions: true
    allow-bypass-permission: true

advanced:
  integrations:
    worldguard:
      enabled: true
      check-regions: true
      allow-bypass: true

Permission Examples:

• builderswand.use.world.spawn - Use wands in spawn world

• builderswand.use.region.build_zone - Use wands in build_zone region

• builderswand.bypass.worldguard - Bypass all WorldGuard restrictions

Troubleshooting

Common Issues

1. Wands not working in regions: Check if require-region-permissions: true and ensure players have region permissions

2. Performance issues: Increase render-interval or reduce max-blocks-per-tick

3. Permission errors: Verify permission hierarchy and bypass permissions

4. WorldGuard not working: Ensure WorldGuard plugin is installed and worldguard.enabled: true

Debug Mode

Enable debug mode to get detailed logs:

general:
  debug: true

Log Files

Check log files for detailed error information:

• Console logs: Server console

• File logs: plugins/BuildersWand/builderswand.log

• Statistics: plugins/BuildersWand/builderswand-stats.json