Advanced TreeCapitator

🌐 English

Version: 1.5.3 | API: Paper 26.1 – 26.3 (Java 25) | 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, so diagonal logs (Big Oak, Acacia, Dark Oak, 2x2 Jungle and Spruce trunks) are handled correctly. The block you break is the origin; at most max-blocks logs are felled per swing.
Poplar & future wood types	Logs are selected through vanilla block tags (overworld_natural_logs by default), so Poplar (Minecraft 26.3) works out of the box, and a wood added later will too as soon as Mojang puts it in that tag. Individual materials can be added with log-types or removed with log-exclude.
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	Requires at least one adjacent natural leaf block before felling — prevents accidental activation on player-built log walls and cabins. Leaves placed by players (persistent leaves) do not count (v1.5.3). Also covers stripped-log variants when you add them to log-types (fixed v1.5.1). The check is skipped for blocks whose name does not end in _LOG or _WOOD — i.e. Nether stems and Bamboo blocks.
Durability-aware	Tool damage is proportional to the blocks broken (damage-multiplier), with a per-hit Unbreaking roll like vanilla (v1.5.0). If the tool cannot afford the whole tree, only as many logs as its remaining durability allows are felled, and the leaves are skipped. With Unbreaking the limit is based on the expected cost, so an unlucky roll can still use the tool up. Unbreakable tools, tools with a custom max durability and Creative mode are handled correctly (v1.5.3). Damage goes through the server's item-damage API, so item-damage / item-break events and the break animation behave like vanilla.
Fortune & Silk Touch	Every extra block is broken with your actual tool, so its enchantments apply wherever vanilla applies them — mainly leaf drops (saplings, sticks, apples, Silk Touch leaves) when break-leaves is on. Logs themselves are not affected by these enchantments in vanilla.
Optional leaf breaking	break-leaves also removes the natural leaves touching the felled logs (skipped when the tree was cut short by durability). leaf-durability-ratio controls how many leaves cost one durability hit (partial hits are rolled proportionally, fixed v1.5.1). Player-placed leaves are never touched (v1.5.3).
Lag-friendly	Big trees are broken over several ticks (blocks-per-tick, default 50) instead of in one long tick (v1.5.3). The search never loads unloaded chunks.
Protection plugin support	Fires a normal BlockBreakEvent for each extra block, so protection plugins that work through that event can cancel individual blocks (cancelled blocks are skipped, the rest of the tree still falls). Felling only starts when the player's own break was not cancelled (v1.5.3).
Drop-plugin friendly	If another plugin sets setDropItems(false) on one of those events (custom drops, auto-pickup...), the block is removed without vanilla drops instead of dropping twice (v1.5.3).
Anti-recursion guard	While a felling batch runs, the player is held in an internal, private breakingTrees set so the plugin ignores the BlockBreakEvents it fires itself.
Effects	Block-crack particles and the log's own break sound (cherry, pale oak, poplar, stems, bamboo... each sounds right) play once at the base of the tree as soon as at least one extra block has been broken (sound position fixed v1.5.0).
Per-player toggle & cooldown	/atc toggle switches felling off/on for yourself; cooldown-ms (default 200) prevents accidental double-triggers.
World restrictions	whitelist-worlds / blacklist-worlds, by world name or world key (minecraft:overworld).
Developer API	Cancellable TreeCapitatorEvent fired right before the tree is felled.

---

Requirements

• A Paper server on Minecraft 26.3 (compiled against the 26.3 API). plugin.yml declares api-version: 26.1, so 26.1 and 26.2 are allowed to load it, but only 26.3 has been targeted.
• Java 25 (required by Minecraft 26.x itself)
• Servers on 1.21.x must stay on AdvancedTreeCapitator 1.5.2.
• Paper API only: Spigot is not supported (the plugin uses Paper-specific methods), and Folia is not declared supported.

Installation

1. Put AdvancedTreeCapitator-1.5.3.jar into your server's plugins/ folder.
2. Start the server once; plugins/AdvancedTreeCapitator/config.yml is created.
3. Edit it and apply changes with /atc reload (no restart needed).

Upgrading from an older version keeps your config.yml. Keys that are missing fall back to the new defaults automatically, so Poplar works immediately (and the Copper Axe too, as long as the vanilla axes tag contains it; otherwise add COPPER_AXE to tool-whitelist).

---

How to use

By default you must sneak (Shift), hold an axe, and break a log that is part of a natural tree. The whole tree falls with that single swing, subject to the limits below.

Felling triggers only when all of these hold:

• enabled: true and the player has advancedtreecapitator.use and has not used /atc toggle to switch it off
• the world is allowed (whitelist / blacklist)
• the player is sneaking (when require-sneak: true) and holds a configured tool (when require-axe: true)
• the broken block is an enabled log type
• the player's own break was not cancelled and their cooldown has expired
• with require-leaves: true: natural leaves touch the tree (not required for Nether stems / Bamboo blocks)

In Creative mode trees are felled too, but nothing drops and the tool takes no damage.

Commands & permissions

Command	Permission	Description
/atc toggle	advancedtreecapitator.use (default: everyone)	Turn tree felling on/off for yourself. The setting is not saved — it resets when you log out.
/atc reload	advancedtreecapitator.admin (default: op)	Reload config.yml. The /atc command itself also requires advancedtreecapitator.use, which everyone has by default.

---

Configuration

Everything lives in plugins/AdvancedTreeCapitator/config.yml. Out-of-range numbers are clamped.

Key	Default	Range	Description
enabled	true		Master switch.
require-axe	true		Player must hold a tool from the tool list.
require-sneak	true		Player must be sneaking.
require-leaves	true		Require adjacent natural leaves (see above).
max-blocks	100	1 – 1000	Max logs per fell, origin included. Bigger trees are felled partially; swing again for the rest.
max-horizontal-distance	8	1 – 64	Max horizontal (X+Z) Manhattan distance from the origin.
max-distance	50	10 – 200	Max 3-D (X+Y+Z) Manhattan distance from the origin.
cooldown-ms	200	0 – 60000	Per-player cooldown between fells.
blocks-per-tick	50	1 – 1000	Blocks (logs + leaves) processed per tick. Lower = smoother, higher = faster.
break-leaves	false		Also break natural leaves next to the felled logs.
damage-axe	true		Apply durability loss.
damage-multiplier	1.0	0.1 – 10.0	Durability cost per log (0.5 = half a point on average).
leaf-durability-ratio	10	1 – 1000	Leaves per durability hit (only with break-leaves).
particle-effect	true		Block-crack particles at the tree base.
sound-effect	true		The log's own break sound at the tree base.
whitelist-worlds	[]		If non-empty, only these worlds (name or key). Takes precedence.
blacklist-worlds	[]		Worlds where felling is disabled (checked only when the whitelist is empty).
log-tags	[overworld_natural_logs]		Vanilla/datapack block tags (without #).
log-types	CRIMSON_STEM, WARPED_STEM, BAMBOO_BLOCK		Single materials added on top of the tags.
log-exclude	[]		Materials removed again.
tool-tags	[axes]		Vanilla/datapack item tags (without #). axes is the vanilla axe tag.
tool-whitelist	[]		Single materials added on top of the tags.
tool-exclude	[]		Materials removed again.

Log set = log-tags + log-types − log-exclude; tool set = tool-tags + tool-whitelist − tool-exclude.

Examples:

# Keep cherry trees unfellable
log-exclude:
  - CHERRY_LOG

# Allow ONLY diamond and netherite axes
tool-tags: []
tool-whitelist:
  - DIAMOND_AXE
  - NETHERITE_AXE

# Also fell stripped logs (they require leaves like any other log)
log-types:
  - CRIMSON_STEM
  - WARPED_STEM
  - BAMBOO_BLOCK
  - STRIPPED_OAK_LOG

If an entry is unknown (a typo, or a tag that does not exist on your server version), a warning is printed to the console on startup and on /atc reload.

---

Developer API

TreeCapitatorEvent is fired on the main thread, one tick after the player's own break, right before the extra blocks are felled. Cancel it to stop the felling (the player's cooldown is reset). It is not fired when the tree is rejected earlier (e.g. require-leaves finds no natural leaves, or the player swapped the tool).

@EventHandler
public void onTreeFell(TreeCapitatorEvent event) {
    Player player = event.getPlayer();
    Set<Block> logs = event.getLogs();     // unmodifiable; includes the already-broken origin block;
                                           // already limited by the tool's durability
    Set<Block> leaves = event.getLeaves(); // unmodifiable; empty unless break-leaves is on
                                           // and the tree was not cut short by durability
    if (logs.size() > 50 && !player.hasPermission("myplugin.bigtrees")) {
        event.setCancelled(true);
    }
}

Every extra block is then broken through a regular BlockBreakEvent fired for the player.

---

Changelog

See CHANGELOG.md.