Advanced TreeCapitator

Version: 1.5.3 | API: Paper 1.21+ | 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, and Dark Oak diagonal logs correctly.
Configurable horizontal cap	Limits horizontal BFS spread — keeps nearby trees from being merged into one fell. Default: 8 blocks. Configurable via max-horizontal-distance (added v1.5.0).
Configurable 3-D distance cap	max-distance limits total BFS depth in all three axes. Default: 50 — accommodates Jungle trees up to 30+ blocks tall. Configurable via max-distance (added v1.5.1; was hardcoded 30).
require-leaves guard	Checks for adjacent leaves before felling — prevents accidental activation on player-built log walls and cabins. Now correctly covers stripped-log variants (fixed v1.5.1).
Protection plugin support	Fires BlockBreakEvent for each extra block — WorldGuard, GriefPrevention, Lands, and Residence can cancel individual blocks.
Anti-recursion guard	breakingTrees set prevents the plugin from re-triggering itself when it fires protection events. Mutable-set exposure removed (fixed v1.5.1).
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 — the axe can never fell more than its remaining durability allows.
Vanilla Unbreaking rolls	Durability loss uses per-hit random rolls matching Minecraft's actual Unbreaking formula (fixed v1.5.0).
Config validation	All numeric values are clamped to a valid range — a malformed config cannot crash or break the plugin.
Configurable leaf cost	leaf-durability-ratio controls how many leaves equal one durability hit (default: 10). Partial hits resolved probabilistically (fixed v1.5.1).
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. Toggle state resets on disconnect.
Plugin API	TreeCapitatorEvent lets other plugins cancel felling or grant custom rewards. All API methods annotated @NotNull (added v1.5.1).
World whitelist/blacklist	Restrict which worlds allow tree felling.
Nether & Bamboo support	Crimson Stem, Warped Stem, and Bamboo Block are supported. require-leaves is automatically bypassed for these types.
Particle & sound effects	Visual feedback on each fell. Sound plays at the tree base so nearby players hear it correctly (fixed v1.5.0).
Hot reload	Apply config changes with /atc reload, no restart needed.
Realistic break time	Optional realistic-break-time spreads the fell out over real mining time instead of breaking every log instantly — closes the "instant wood farm" exploit. Default: off (added v1.5.3).

---

Installation

1. Download AdvancedTreeCapitator-1.5.3.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.21+, Java 17+

---

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
                           # covers stripped-log variants since v1.5.1

# ── Tree detection ───────────────────────────────────────────────
max-blocks: 100            # max logs per fell (partial chop above limit)
max-horizontal-distance: 8 # BFS horizontal spread cap (added v1.5.0, was hardcoded before)
max-distance: 50           # BFS 3-D Manhattan cap — increase for tall Jungle trees
                           # (added v1.5.1, was hardcoded 30 in v1.5.0)

# ── Timing ──────────────────────────────────────────────────────
cooldown-ms: 200           # per-player cooldown in milliseconds
realistic-break-time: false # spread the fell over real mining time instead of
                             # breaking every log/leaf in the same tick (added v1.5.3)

# ── Leaves ──────────────────────────────────────────────────────
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)
                           # partial hits now use probabilistic roll (fixed v1.5.1)

# ── Effects ─────────────────────────────────────────────────────
particle-effect: true
sound-effect: true         # sound plays at the tree base (fixed v1.5.0)

# ── 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
  - STRIPPED_OAK_LOG    # stripped variants are now subject to require-leaves (v1.5.1)
  - 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(); // includes the origin block

        // Example: cancel felling in a protected 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()	@NotNull Player	The player who triggered the fell
getLogs()	@NotNull Set<Block> (unmodifiable)	All log blocks scheduled to break, including the origin block. Size = full tree size.
getLeaves()	@NotNull Set<Block> (unmodifiable)	Leaf blocks scheduled to break (empty if break-leaves: false or set was trimmed)
setCancelled(true)	—	Cancels the entire tree felling; cooldown is refunded (fixed v1.5.0)

Note (fixed v1.5.0): In v1.4.0 and earlier, the Javadoc incorrectly stated that getLogs() excluded the origin block. It has always included it. If your plugin subtracted 1 from getLogs().size() as a workaround, remove that adjustment when upgrading to v1.5.0+.

---

What's New in v1.5.3

#	Feature	Impact
1	New realistic-break-time option (default: false)	When enabled, a felled tree is broken one log/leaf at a time instead of all at once, with each delay equal to that block's real vanilla mining time for the player's current tool. Closes the "swing once, get an entire tree instantly" wood-farming exploit while keeping one-swing auto-felling.

---

What's New in v1.5.2

#	Fix	Impact
1	api-version raised from '1.20' to '1.21'	Plugin no longer loads on 1.20.x servers where Particle.BLOCK doesn't exist — prevents NoSuchFieldError on enable
2	Correct break sound for Nether stems and Bamboo	CRIMSON_STEM/WARPED_STEM now play BLOCK_NETHER_WOOD_BREAK; BAMBOO_BLOCK plays BLOCK_BAMBOO_WOOD_BREAK
3	cfg fetched fresh in task execution, not at construction	A /atc reload in the one-tick window between event and task now always takes effect

---

What's New in v1.5.1

#	Fix	Impact
1	BFS distance check moved before logsToBreak.add()	max-horizontal-distance now works correctly at the boundary — blocks just beyond the limit are no longer included in the fell
2	cooldown-ms overflow on extreme YAML values	Values > Integer.MAX_VALUE no longer silently disable the cooldown
3	max-distance is now configurable (default 50, was hardcoded 30)	Tall Jungle trees no longer get truncated mid-trunk
4	getBreakingTrees() public getter removed	Anti-recursion guard can no longer be corrupted by external plugins
5	isOverworldLog() covers stripped-log variants	STRIPPED_OAK_LOG etc. in log-types now correctly honour require-leaves
6	Leaf durability partial hits resolved probabilistically	Breaking fewer leaves than leaf-durability-ratio no longer silently discards the hit
7	@NotNull on TreeCapitatorEvent public API	IDE and static analysis support for third-party integrations

---

What's New in v1.5.0

#	Fix	Impact
1	Enchantment.UNBREAKING constant replaces deprecated getByKey()	Unbreaking now works correctly on Paper 1.21+
2	isOnline() guard before task execution	No more unsafe calls when player disconnects in 1-tick window
3	PlayerQuitEvent clears all per-player state	Toggle state and cooldown reset correctly on disconnect
4	Cooldown refunded when TreeCapitatorEvent is cancelled	Players aren't penalised when another plugin blocks a fell
5	TreeCapitatorEvent Javadoc corrected ("includes origin")	Third-party plugins now get accurate tree size from getLogs().size()
6	Unbreaking uses per-hit random rolls (vanilla-accurate)	Durability loss now feels natural and varies like vanilla
7	Sound plays at tree base, not the player	Nearby players hear the fell; audio matches the visual
8	max-horizontal-distance is now configurable	Modpack trees with wide canopies no longer need a code change

---

Known Issues

• Folia incompatibility — Folia's RegionScheduler API is not yet used. Planned for v1.6.0.

---

Changelog

See CHANGELOG.md

---

License

Apache-2.0 © Duong2012G