Advanced TreeCapitator

Version: 1.5.1 | 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, 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.

---

Installation

1. Download AdvancedTreeCapitator-1.5.1.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+

---

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

# ── 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.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