Advanced TreeCapitator

Version: 1.4.0 | API: Paper 1.20.4+ | Author: Duong2012G
License: Apache-2.0 | Link: Modrinth

Fell an entire tree with a single axe swing — Fortune, Silk Touch, and realistic tool durability fully supported.

---

Features

Feature	Description
BFS tree felling	Finds and breaks all connected logs using a 26-direction breadth-first search (handles Big Oak, Acacia, Dark Oak diagonal logs)
Horizontal BFS cap	Limits horizontal spread to 8 blocks from the origin — two nearby trees are never merged into one fell (added v1.4.0)
require-leaves guard	Checks for adjacent leaves before felling — prevents accidental activation on player-built log walls and cabins
Protection plugin support	Fires BlockBreakEvent for each extra block — WorldGuard, GriefPrevention, Lands, Residence can cancel individual blocks (fix v1.4.0)
Anti-recursion guard	breakingTrees set prevents the plugin from re-triggering itself when it fires protection events (fix v1.4.0)
Fortune & Silk Touch	Work automatically on every block via breakNaturally(tool), no extra configuration needed
Durability pre-check	Calculates max breakable logs before breaking any — axe can never fell more than its remaining durability allows
Config validation	All numeric values are clamped to a valid range — a malformed config can no longer crash or break the plugin (added v1.4.0)
Configurable leaf cost	leaf-durability-ratio controls how many leaves equal one durability hit (default: 10)
Partial chop	Trees larger than max-blocks are chopped up to the limit; remaining logs can be harvested with additional swings
Per-player toggle	Each player can enable/disable tree felling with /atc toggle without affecting others
Plugin API	TreeCapitatorEvent lets other plugins cancel felling or grant custom rewards based on tree size
World whitelist/blacklist	Restrict which worlds allow tree felling
Nether & Bamboo support	Crimson Stem, Warped Stem, and Bamboo Block all supported; require-leaves is automatically bypassed for these
Particle & sound effects	Configurable visual feedback on each fell
Hot reload	Apply config changes with /atc reload, no restart needed

---

Installation

1. Download AdvancedTreeCapitator-1.4.0.jar
2. Place it in your server's plugins/ folder
3. Restart or reload the server
4. Edit plugins/AdvancedTreeCapitator/config.yml as needed
5. Run /atc reload to apply changes without restarting

Requirements: Paper (or any Paper fork) 1.20.4+, Java 17+ (was Java 21 in v1.3.0)

---

Permissions

Permission	Description	Default
advancedtreecapitator.use	Use tree felling + /atc toggle	true (all players)
advancedtreecapitator.admin	Reload config with /atc reload	op

---

Commands

Command	Description	Permission
/atc toggle	Enable or disable tree felling for yourself	advancedtreecapitator.use
/atc reload	Reload the configuration file	advancedtreecapitator.admin

---

How to Use

1. Hold an axe listed in tool-whitelist
2. Sneak (Shift) if require-sneak: true
3. Break the base log of a tree — the entire connected tree drops at once

Fortune: All logs and leaves receive Fortune bonus drops automatically.
Silk Touch: Logs and leaves drop as their block form instead of items.

---

Configuration Reference

# ── Activation ──────────────────────────────────────────────
enabled: true
require-axe: true          # must hold an axe from tool-whitelist
require-sneak: true        # must be sneaking (Shift)
require-leaves: true       # at least 1 adjacent leaf required — prevents structure damage

# ── Mining ──────────────────────────────────────────────────
max-blocks: 100            # max logs per fell (partial chop above limit)
cooldown-ms: 200           # per-player cooldown in milliseconds
break-leaves: false        # also break adjacent leaves

# ── Durability ──────────────────────────────────────────────
damage-axe: true           # apply durability loss proportional to blocks broken
damage-multiplier: 1.0     # durability cost per log block (Unbreaking respected)
leaf-durability-ratio: 10  # how many leaves = 1 durability hit (when break-leaves: true)

# ── Effects ─────────────────────────────────────────────────
particle-effect: true
sound-effect: true

# ── World Restrictions ───────────────────────────────────────
whitelist-worlds: []       # only these worlds (empty = all)
blacklist-worlds: []       # block these worlds (empty = none)

World Restrictions

# Allow only specific worlds:
whitelist-worlds:
  - world
  - world_nether

# Or block specific worlds:
blacklist-worlds:
  - creative_world

Adding Custom Log Types

Add any Material enum name (case-insensitive) to log-types:

log-types:
  - OAK_LOG
  - MUSHROOM_STEM   # enables huge mushroom felling
  # add more as needed...

---

Plugin API — TreeCapitatorEvent

Other plugins can hook into tree felling via the TreeCapitatorEvent:

import dev.duong2012g.atc.TreeCapitatorEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public class MyListener implements Listener {

    @EventHandler
    public void onTreeFell(TreeCapitatorEvent event) {
        Player player   = event.getPlayer();
        int    logCount = event.getLogs().size();

        // Example: cancel felling in a specific region
        if (isProtectedRegion(player.getLocation())) {
            event.setCancelled(true);
            return;
        }

        // Example: reward economy based on tree size
        economy.depositPlayer(player, logCount * 0.5);
    }
}

Event fields:

Method	Returns	Description
getPlayer()	Player	The player who triggered the fell
getLogs()	Set<Block> (unmodifiable)	Log blocks scheduled to break (origin excluded)
getLeaves()	Set<Block> (unmodifiable)	Leaf blocks scheduled to break (empty if break-leaves: false)
setCancelled(true)	—	Cancels the entire tree felling

---

Changelog

See CHANGELOG.md

---

Bug Fixes in v1.4.0

#	Bug	Status
1	Forced Java 21 → UnsupportedClassVersionError on Java 17 servers	✅ Fixed — compile target lowered to Java 17
2	Double durability damage	✅ Clarified — not a bug: breakNaturally(tool) does not touch inventory durability; it only uses the tool for drop calculation
3	Accidentally felling player-built log structures	✅ Already covered by require-leaves guard since v1.2.3; v1.4.0 adds horizontal BFS cap as a second layer
4	26-direction BFS merging two nearby trees	✅ Fixed — added MAX_HORIZONTAL_DISTANCE = 8
5	Bypassing protection plugins (WorldGuard, Lands…)	✅ Fixed — BlockBreakEvent fired for every extra block
6	No anti-recursion guard	✅ Fixed — breakingTrees set prevents the listener from looping when it fires protection events
7	Config accepts invalid values (max-blocks: -1)	✅ Fixed — all numeric values are clamped on load
8	Folia incompatibility	⚠️ Not yet fixed — requires migration to RegionScheduler (planned v1.5.0)

---

License

Apache-2.0 © Duong2012G