# 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

```yaml
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

```yaml
general:
  debug: false
```

* **Purpose**: Enables detailed logging for troubleshooting
* **Values**: `true` or `false`
* **Use Case**: Enable when experiencing issues or need detailed logs

#### Language

```yaml
general:
  language: "en"
```

* **Purpose**: Sets the language for all plugin messages
* **Supported**: `en` (English), `de` (German), `es` (Spanish)
* **Default**: `en`

### Wand Settings

#### Rendering

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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**

```yaml
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**

```yaml
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**

```yaml
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

```yaml
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

```yaml
# 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:

```yaml
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`
