Home

Timberella fells whole trees with one axe swing, cleans up their leaves and replants them, on Paper 26.3.x servers. This page is the complete guide for server admins: installation, upgrading from 1.x, every setting, commands and permissions, and troubleshooting. To build Timberella from source or contribute, see the Developer Guide.

1. Requirements Checklist

• Paper or compatible fork running 26.3.x (Spigot/vanilla are unsupported). Other versions trigger a console warning at startup, but the plugin still loads.
• Java 25 runtime.
• Ability to upload plugins and execute commands in console or in-game (recommended: operator permissions or LuckPerms).

2. Installation Flow

1. Download the latest timberella-paper-<version>.jar from Modrinth or Hangar.
2. Drop the JAR into plugins/.
3. Start the server once. Timberella creates:
   • plugins/Timberella/config.yml
   • plugins/Timberella/lang/<locale>.yml for all 14 bundled languages (the one set in language is active)
   • plugins/Timberella/leaf_mappings.yml
   • plugins/Timberella/toggles.yml appears later, the first time someone uses /timberella toggle.
4. Edit config.yml, leaf_mappings.yml and languages for your needs.
5. Run /timberella reload after any edits to apply the changes instantly (console or with permission timberella.admin).

Upgrading from 1.x

Timberella 2.0 needs Paper / Minecraft 26.3. Replace the old jar with the new one and start the server; the rest happens automatically on the first start:

• Your old plugins/Timberella/ files are moved to plugins/Timberella/backup-1.x/.
• Fresh config.yml, leaf_mappings.yml and lang/ files are created, so you get all new settings with their comments.
• Every setting you had changed from the 1.x default is carried over into the new config.yml. toggles.yml (players who switched Timberella off) is kept unchanged.
• The console lists what was carried over, what couldn't be (settings that no longer exist), new default list entries your own lists are missing (e.g. POPLAR_SAPLING in replant.saplings), and which customized files were replaced. Your versions of those files stay in the backup. Only files you actually edited are listed: an untouched file from any 1.x version, 1.0 to 1.2.2, isn't.
• Going back to 1.2.x for a while: 1.2.x doesn't read the new setting names and runs on its own defaults meanwhile. It doesn't change config.yml, so coming back to 2.0 doesn't run the upgrade again; it only adds its old message names to the lang files. Back on 2.0, the active language file is cleaned up quietly: an old name that still holds its 1.2.x text goes, one you changed meanwhile stays, and the console asks you once to keep one of the two. The other language files keep the old names until they become the active one. If you add old-style setting names to config.yml meanwhile, see the note on key naming below.
• Coming from 1.0 or 1.0.1: your files are moved to the same backup folder and fresh files are created, but no settings are carried over, because 1.0.x used a different format. The console says so and lists the files you had edited; re-apply your changes from the backup. toggles.yml is kept. This also applies if 1.1 or 1.2 later ran on the same files, since those versions didn't read the 1.0.x settings either. Only settings you had added in the 1.1+ format (e.g. sneak-mode) are carried over as usual; the unused 1.0.x settings next to them are skipped.

Two defaults changed in 2.0. If you prefer the 1.x behavior, set:

• require_natural_leaves: false to fell bare trunks and log builds again, not only trees with grown foliage.
• replant.sapling_source: "free" to always replant for free instead of only from saplings the leaves dropped.

3. Core Configuration

All configuration lives in plugins/Timberella/config.yml. Timberella merges new defaults automatically during reloads so you only maintain the values you change.

If config.yml isn't valid YAML (e.g. a wrong indentation or a missing quote), Timberella doesn't apply it and leaves the file exactly as it is; the console names the line and column of the error. On a reload (command or watcher), the previous settings stay active, and /timberella reload answers with the error instead of "Configuration reloaded". At startup, Timberella runs with the default settings instead, but keeps bStats and update checks off. Once the file is fixed, the next reload applies everything as usual.

Key naming: settings and language keys now use snake_case (e.g. chat_prefix_label), matching Minecraft's own naming. Upgrades from 1.x are handled as described in "Upgrading from 1.x" above; if you copy an old 1.x config.yml back from the backup, the next restart runs that upgrade again (new backup folder backup-1.x-2, your changed values carried over). So does a single old 1.x setting added by hand to a 2.0 config.yml (e.g. sneak-mode: 2 from an old guide): every changed 2.0 setting is carried over, and where the old name sits next to its 2.0 key, the 2.0 key wins and is the one reported. /timberella reload instead renames hyphenated keys (e.g. chat-prefix-label) in place, in your config.yml and active lang/<locale>.yml, with comments and formatting left as they were and a console line reporting how many keys were renamed. A handful of very old keys (e.g. species-limits.pale-oak → species_limits.pale_oak) are still recognized as a compatibility fallback if a rewrite couldn't happen for some reason (e.g. a read-only filesystem); check your console log if that ever applies to you.

General Section

Key	Default	What it controls
language	en_US	Locale file inside lang/. Missing keys are added from the bundled file of that language (English for a language without a bundled translation); invalid codes load en_US.
chat_prefix_label	Timberella	Text inside the colored [ ] prefix (<prefix_label> placeholder).
startup_banner_enabled	true	Prints the MiniMessage startup banner in console.
config_watch_enabled	true	Keeps the async watcher on config.yml running; a detected edit triggers a full reload, which the console announces before listing the changed settings. It doesn't watch lang/ or leaf_mappings.yml: run /timberella reload after editing those. An emptied or deleted config.yml (a file with only comments counts as empty) isn't reloaded: the settings in use stay, the console warns once, and /timberella reload or a restart writes the default settings. If the file comes back with its old content, nothing is reloaded.
config_watch_interval_seconds	5	Interval for the watcher (minimum 1 second); a new value applies from the next reload, no restart needed.
log_stats	true	Logs the module status line (Timber, Replant, Leaf decay) on startup and on reload.
log_detail	false	Also lists every enabled material per category, the leaf mappings, the allowed axes and the replant saplings, one per line.
update_check.enabled	true	Contacts Modrinth/Hangar for new releases.
update_check.provider	0	Source mode: 0 = Modrinth + Hangar, 1 = Modrinth only, 2 = Hangar only. Values below 0 count as 0, above 2 as 2.
update_check.interval_hours	24	Poll interval (minimum 1 hour).
update_check.include_prereleases	false	Whether beta/alpha builds qualify as latest.
update_check.filter_by_server_version	true	Only report builds made for the server's Minecraft version (its major.minor series); builds without version info count only if none matches.
update_check.notify_console / update_check.notify_op_join	true	Console summary (one line per provider) + join reminders for ops or players with timberella.update.notify (they point to the server log only while notify_console is on). An unreachable Modrinth or Hangar logs one warning with the reason, then stays quiet until it answers again or the plugin reloads.
update_check.notify_console_always_shown	false	When true, also logs the provider summary once after each start/reload if no update exists.
metrics_enabled	true	Opt-out switch for bStats telemetry.

Module Switches

Key	Default	Notes
enable_timber	true	Whole-tree felling. Disabled, only the hit block breaks (leaf cleanup still runs if enable_leaves_decay is on).
enable_leaves_decay	true	Flood-fill cleanup around felled logs (doesn't need timberella.use; players who toggled Timberella off get none).
enable_replant	true	Attempts to replant approved saplings where the felled tree's trunk stood.

Behaviour Knobs

• sneak_mode → 0 (only sneaking), 1 (only not sneaking), 2 (always). Choose when Timberella should activate. Unknown values behave like 0.
• include_diagonals → true/false for tree detection adjacency.
• require_natural_leaves → true (default) only fells logs that carry grown foliage and leaves log builds touching a tree standing; see "What Counts as a Tree" below. Set it to false to also fell bare trunks and stumps, and any log build touching the tree you fell.
• break_interval_ticks → delay between scheduled block breaks (default 2 ticks).
• max_blocks → hard cap per felling session (default 1024) to prevent mega grief incidents.

Tools Section (tools.*)

Key	Default	What it controls
tools.allowed_axes	STONE_AXE, COPPER_AXE, IRON_AXE, GOLDEN_AXE, DIAMOND_AXE, NETHERITE_AXE	Axes that may trigger felling. WOODEN_AXE is left out on purpose: it breaks quickly and is WorldEdit's default wand, so selecting a region can't fell a tree by accident. If the list is empty, every item in Minecraft's own axe tag qualifies (including wooden and copper axes).
tools.min_remaining_durability	10	Felling only starts if the axe has at least this much durability left.
tools.durability_mode	all	first = only the first block costs durability, all = every broken log counts.
tools.durability_multiplier	0.5	Used in all mode: total cost = round(broken logs × multiplier).

How felling uses the axe: Logs are felled one after another (break_interval_ticks apart).

• In all mode, each broken log is paid for right away on the axe that started the felling, wherever it is in your inventory (main hand, off hand, other slot). Switching hotbar slots doesn't interrupt anything, and the total cost is the same as if it were charged at the end. Logs that a protection plugin or spawn protection keeps standing cost nothing.
• The axe never drops below 1 durability; the tree is still felled completely.
• The extra wear goes through Minecraft's normal item damage: Unbreaking reduces it just like when chopping by hand, axes marked unbreakable never lose durability (and always pass min_remaining_durability), players in creative mode pay nothing, and other plugins see it as a regular item-damage event. As in vanilla, nothing drops in creative mode, the extra logs and leaves included.
• The felling stops early, in both modes, if that axe leaves your inventory (dropped, put in a chest or another container, lost on death) or you change worlds. An actionbar message says why. Logs already felled keep their leaf cleanup and replanting. Picking the axe up with the mouse while sorting your inventory, or placing it in your 2×2 crafting grid or an open crafting table, does not count as leaving: the felling continues and the cost still goes to that axe.
• If you log out mid-felling, it stops as well: logs already felled are paid for and their leaves are cleaned up, but nothing is replanted. An axe that is on the mouse cursor or in a crafting grid when you log out is dropped on the ground by the server itself.

Land Protection

Only the block you break yourself goes through vanilla's break check. Timberella therefore fires a regular block-break event for every additional log and leaf it removes, so protection plugins (WorldGuard, GriefPrevention, etc.) can deny individual blocks. Vanilla spawn protection (spawn-protection in server.properties) and the world border are checked the same way, block by block; the world border holds for ops too. Denied blocks simply stay in place, cost no axe durability, and the rest of the tree is still felled. The drops of each further log also go through the regular drop event, so auto-pickup, telekinesis and drop-bonus plugins handle them like the first block's, and the "blocks mined" statistic counts every log, adding to scoreboard objectives on it like a hand-broken log. Leaves drop like naturally decaying leaves, without that event.

Players in adventure mode don't fell trees: only the block they hit breaks, as in vanilla, with no leaf cleanup and no replanting.

Replanting is a separate placement: each replanted sapling goes through a regular block-place event for the player who felled the tree. Where that player may break but not build (e.g. WorldGuard block-break allow, block-place deny), nothing is replanted. Block loggers such as CoreProtect record replanted saplings as that player's placements.

Custom Blocks from Other Plugins

ItemsAdder, MMOItems, MythicCrucible and CraftEngine can place their own decorative blocks that look like mushroom blocks or logs to the server. When one of these plugins is installed, Timberella recognizes its blocks and leaves them alone: breaking one with an axe doesn't start a felling, they are never felled as part of a tree, don't count as a tree's foliage, are never removed by leaf cleanup, and no sapling is planted in their place. The console lists the plugins it hooked into at startup (Custom blocks protected from felling: ...). ItemsAdder blocks are recognized once ItemsAdder has finished loading its data.

What Counts as a Tree

Timberella only fells what looks like a grown tree, so log cabins and other builds stay intact:

• Only logs of the same species as the one you hit are collected (stripped logs and woods included). A birch touching a dark oak stays standing. Blocks from categories.additions and categories.fences join any tree. If you hit one of them, the tree takes the species of the log next to it, with that species' limits; with no log next to it, only that block breaks. A mushroom stem takes its species from the cap on its top, however tall it is.
• With require_natural_leaves: true (default), the collected logs need at least a few blocks of grown foliage next to them: naturally grown leaves of any kind, or other foliage listed for that log in leaf_mappings.yml (wart blocks, shroomlights, weeping vines). Leaves a player placed never count. Without enough foliage only the block you hit breaks, and nothing is replanted.
• Trunks whose leaves are already gone (stumps, fallen logs) therefore only break block by block while the setting is on.
• Builds touching a tree stay standing while the setting is on. The tree stands on its trunk, found straight down from the block you hit (from a branch, down along the branch); 2×2 trunks and thick nether fungus stems count as one trunk. Other logs of that species standing on the ground, such as a wall or a hut against the trunk, are a build and stay, together with everything that rests on them without ground of its own, like a roof reaching over to the trunk. Wood standing no higher than the trunk's foot always counts as a build. Higher up, on a slope or a pillar, a single log resting on the ground, or a stack of up to five logs with grown leaves right on top or holding up the rest of a branch that ends in leaves, is a branch of the tree and falls with it, even if you hit that branch; so do branches standing on a mangrove's roots beside its trunk. Mangrove roots always go with the trunk they carry, and roots nearer to a neighboring mangrove stay with that one; so does another mangrove's trunk. If you hit the build itself, nothing of the tree falls: a bare wall or post standing against a trunk that carries leaves on top is never taken for the trunk. Only where that trunk starts at the column's top and rests on grass, stone or the like is the column the tree's own base, as with an acacia or cherry bending over onto a slope: a grown tree always stands on dirt, podzol, moss or nylium, since growing turns the grass under it into dirt. Leaves touching the build or another trunk don't count as foliage, so usually only the block you hit breaks.
• Giant mushrooms have their own rule while the setting is on: one is felled only if its stem is a single straight column that touches no other stem, with its cap on top, the way vanilla grows every giant mushroom. You can hit the stem or the cap. The stem falls together with the cap on top of it and nothing more: a neighboring mushroom stays, even if the caps touch, and cap blocks two domes share stay with the one still standing. Mushroom blocks that vanilla couldn't have grown that way (stem walls, stems shorter than 4 blocks, several pillars under one roof, caps without a stem, extra cap blocks beyond the natural cap) count as a build, so only the block you hit breaks. Mushroom blocks are never cleaned up like leaves, not even after breaking a single block.
• Limitations: logs without ground of their own that touch only the tree, like a treehouse platform around the trunk without posts, count as part of the tree and fall with it. So do a single row of logs lying higher than the trunk's foot (a bench on a slope), a post standing higher up whose top reaches into the crown or holds up a branch ending in leaves, and a tree of the same species up to five logs tall standing higher up on a slope, if they touch the tree. The other way round, a branch that touches a build stays standing, and an acacia or cherry whose bent trunk rests on bare dirt beside its base can't be told apart from a tree of its own: hitting the base breaks only that block, and hitting the tree higher up leaves the base standing and replants the sapling where the resting part stands. The species radius limits keep all of these cases small.

Species Limits (species_limits.*)

Available species: mangrove, jungle, spruce, oak, pale_oak, dark_oak, birch, acacia, cherry, poplar, mushroom_brown, mushroom_red, warped, crimson. Each one exposes:

• enabled – toggle species-specific limits.
• max_blocks – override block count (set -1 to inherit global limit). Only values below the global max_blocks have an effect; the default is -1 for every species except mangrove (128).
• max_horizontal_radius / max_vertical_radius – Chebyshev radius that keeps the flood-fill from reaching into a neighboring tree of the same species (0 = no radius limit). Trees of other species are never collected anyway. For giant mushrooms (with require_natural_leaves: true) the stem is always felled whole, and max_horizontal_radius can only narrow the cap, which reaches 3 blocks around the stem for brown and 2 for red.

The defaults leave room for every tree vanilla grows. This table shows how far each species' largest trees reach, so you can see how far a limit can go down. Logs are measured from the log you hit while standing on the ground (a lowest log or one up to 3 above it): horizontally as the Chebyshev distance, vertically as the height difference. Leaves are measured as the 3D distance to the nearest wood block. Leaf cleanup reaches as far as the species' max_horizontal_radius, but at least 4 blocks and at most leaves_decay.max_distance, so lowering a radius below the leaf distance in the table (only oak, jungle, poplar and the fungi go beyond 4) leaves the outer ring of the crown standing. Measured on Minecraft 26.3 with 20,000 trees of each kind, matching the generator code.

Species	Largest vanilla tree	Logs: horizontal / vertical	Default limit: horizontal / vertical	Leaves: farthest from wood
oak	fancy oak	6 / 11	6 / 24	4.2 (swamp oak)
birch	tall birch	0 / 12	2 / 12	2.8
spruce	mega spruce	1 / 28	6 / 32	4.0
jungle	mega jungle tree	5 / 30	8 / 32	5.0
acacia	acacia	4 / 8	8 / 12	3.6
dark_oak	dark oak	4 / 8	6 / 12	3.6
pale_oak	pale oak	4 / 8	5 / 16	3.6
cherry	cherry	6 / 7	9 / 12	3.7
poplar	poplar	4 / 10	9 / 24	4.2
mangrove	tall mangrove	9 / 17, roots up to 13 lower, up to 106 blocks	9 / 36, max_blocks 128	3.5
mushroom_brown	huge brown mushroom	3 / 12	4 / 12	–
mushroom_red	huge red mushroom	2 / 12	2 / 12	–
crimson, warped	huge fungus	2 / 25	6 / 32	5.0 (wart blocks)

Fallen trees (a log lying on the ground) have no leaves, so with require_natural_leaves: true they aren't felled.

A species section you leave out keeps its built-in defaults, which match the bundled config.yml.

Categories and Materials

categories.logs, categories.stripped_logs, categories.woods, categories.stripped_woods, categories.fences, and categories.additions (bee nests, beehives, creaking hearts, shelf mushrooms) serve as boolean allowlists. A bee nest or beehive felled with a tree treats its bees like one broken by hand: without Silk Touch they fly out and turn on the player, with it they stay in the dropped nest, and in creative mode a nest holding bees or honey drops as an item with them. Unknown materials are ignored with a console warning, so you can share configs between versions. Keep only the materials your server wants to support. By default only regular logs/stems, mushroom blocks and additions are enabled; stripped logs, woods and fences start as false. You can switch a material off with false or delete its line: deleted materials stay deleted, while materials a later update adds show up once.

Replant Section

replant:
  sapling_source: "drops"
  saplings:
    - OAK_SAPLING
    - MANGROVE_PROPAGULE

• The replant module itself is switched on or off via enable_replant (see Module Switches above), not a key inside this section.
• Add or remove saplings to match your gameplay policy. Mangrove propagules automatically respect waterlogged soil.
• Replanting only happens after an actual multi-block felling, not after breaking a single log.
• Azalea trees grow oak logs under azalea leaves. Their leaves are cleaned up with them, and an azalea is replanted instead of an oak sapling: a flowering azalea if most of the leaves flower, and with sapling_source: drops whichever of the two the leaves dropped. Both are in the default replant.saplings list.
• The sapling goes where the trunk stood: in place of its lowest log, on all four spots of a 2×2 trunk, and in the middle of a thick nether fungus stem. A mangrove's propagule goes where the root under its trunk was, or onto the mud up to six blocks below it. A spot whose log wasn't felled, whose soil doesn't carry that sapling in vanilla, or where something else stands by now (a torch, a sign, a sapling you planted yourself) gets no sapling; grass and other plants that vanilla lets you place over are replaced.
• Into water, only a mangrove propagule is replanted, unless UnderwaterTrees is installed and enabled. Then other saplings are replanted into water too, wherever UnderwaterTrees would let the player who felled the tree plant them by hand: the sapling and the soil below must be enabled in its saplings and soils, a bubble column only counts while its require_water_above is off, and the player needs underwatertrees.place. UnderwaterTrees then looks after the sapling like one planted by hand. It only holds the water back from a sapling with water above it, and the leaves around a small trunk can keep that water off for a moment, so the replant waits up to three seconds for the water to close over the spot and plants it then anyway.
• A replanted sapling counts as a block placed by the player who felled the tree, so protection plugins can prevent it (see Land Protection). If that player is offline by the time the sapling would be planted, nothing is planted. A 2×2 tree is planted completely or not at all.
• sapling_source decides where the sapling comes from:
  • drops (default): only saplings that the felled tree's leaves drop during leaf cleanup are planted, once the cleanup is finished. The planted sapling is taken out of those drops, all other drops fall as usual. A 2×2 tree (e.g. dark oak) is only replanted when all four saplings dropped; otherwise, and if a spot is blocked or a protection plugin denies the placement, the collected saplings drop as items. This needs enable_leaves_decay: true; without leaf cleanup nothing is replanted. In creative mode nothing drops, so the sapling is planted for free there.
  • free: new saplings are always planted for free, independent of any drops.

Leaves Decay Section

leaves_decay:
  decay_radius: 5
  max_distance: 9
  batch_interval_ticks: 2
  batch_size: 20

• decay_radius controls how far the search spreads (minimum 0).
• max_distance is the safety bubble: leaves farther away (3D distance from every felled log) remain untouched (minimum 1). Below that cap, cleanup reaches as far as the felled species' max_horizontal_radius, but at least 4 blocks; with the default of 9 that is 4 for birch, 6 for oak and 9 for cherry, poplar and mangrove. Species with enabled: false in species_limits use the 4-block minimum.
• Batch settings keep TPS impact predictable (both minimum 1).
• Only leaves that would also decay in vanilla are removed: leaves placed by players stay, and so do leaves still held by another standing log (for example the crown of a neighboring tree). Builds next to the felled tree, of any wood, don't count as holding its leaves, so its crown is cleaned up there too. Any other log only holds leaves if hitting it would fell it as a tree of its own, with grown leaves on top of one of its logs and leaves of its own apart from the felled crown, like a neighboring tree of any species; a small tree whose few leaves all touch the felled crown or a build loses the leaves within reach. Wart blocks, shroomlights and weeping vines have no such marker, so each goes with the nearest stem that grows it: one that a standing stem is at least as near to stays, and the cleanup doesn't spread past it, so a neighboring fungus keeps its cap. Only builds beside the felled fungus don't count as such a stem. Parts of a huge fungus's cap can touch nothing else of it: on a short stem its edge hangs down beside the stem two blocks out, and the lowest rows of a tall hat reach three blocks out. Wart blocks of its kind and shroomlights there go with the felled stem too, but only level with it and in the rows where vanilla grows that part of a cap. Mushroom blocks are never part of the leaf cleanup (see What Counts as a Tree).
• Leaf cleanup is global: it runs even for players without timberella.use, as long as enable_leaves_decay is true, the log is broken with an allowed axe that has at least tools.min_remaining_durability left, in the matching sneak_mode, and the player hasn't toggled Timberella off.

Leaf Mappings (leaf_mappings.yml)

log_to_leaves maps each log/stem/wood material to the foliage blocks that belong to the same tree. Only blocks listed for the logs that were actually felled get removed, so neighboring trees of other species stay intact. Oak and jungle logs also list the leaves vanilla grows on them in other trees: azalea leaves on an azalea tree's oak logs, oak leaves on a jungle bush's jungle log. The same lists tell the "What Counts as a Tree" check which non-leaf foliage belongs to a tree. Entries may be any block, not just leaves (e.g. NETHER_WART_BLOCK, SHROOMLIGHT). Giant mushrooms need no entry, because their cap is found from the stem's shape; entries for MUSHROOM_STEM or mushroom blocks from older versions are ignored. Run /timberella reload after editing this file.

Entries you delete stay deleted, and a later update adds each new entry only once; a leaf added to a log entry you already have only reaches freshly created files. A log without an entry (or with an empty list) falls back to vanilla leaves (*_LEAVES). Because the same lists decide what counts as grown foliage, deleting the CRIMSON_STEM/WARPED_STEM entries (or their wart blocks) keeps wart blocks and shroomlights in place, but with require_natural_leaves: true those huge fungi are then no longer felled as a whole: only the block you hit breaks. Timberella remembers which default entries it has already offered in plugins/Timberella/.seen-defaults.yml; leave that file alone.

log_to_leaves:
  OAK_LOG:
    - OAK_LEAVES

If leaf_mappings.yml isn't valid YAML, Timberella leaves the file exactly as it is and the console names the line and column of the error. On a reload the previous mappings stay active; on a server start the default mappings are used until the file is fixed.

4. Localization

• Locale files live in plugins/Timberella/lang/<locale>.yml and use MiniMessage formatting.
• <prefix> and <prefix_label> work in every message. The other placeholders are filled only in the messages listed here; keep a message's placeholders when you edit its text, others stay literal:
  • Commands: <label> and <subcommands> (command.usage), <current_ver> (command.version), <error> (command.reload_failed), <player> (toggle.other_*), <code> (plugin.language_set).
  • Update notices: <current_ver> and <latest_ver> (update.available); in the console <current> (log.update_found) and <provider>, <version>, <url>, <error> (log.update_provider_*).
  • Console: <file>, <count>, <keys> (log.defaults_updated), <changes> and <file> (log.reload_changes_*), <timber>, <replant>, <leaves> (log.modules_summary), <category> (log.detail_category_header), <plugins> (log.custom_blocks_hooked), <error> (log.config_invalid_*, log.leaf_mappings_invalid_*).
  • Upgrade from 1.x: <plugin>, <backup>, <old>, <new>, <value>, <key>, <list>, <entries>, <file> (log.upgrade_*).
  • Unsupported server: <required_server>, <supported_versions>, <server_name>, <mc_version> (warn.unsupported_server_version).
• Bundled locales: en_US, de_DE, ar_SA, es_ES, fr_FR, it_IT, ja_JP, ko_KR, nl_NL, pl_PL, pt_PT, tr_TR, uk_UA, zh_CN.
• /timberella reload hot-reloads both config and locale changes (the config watcher only watches config.yml). Missing keys are filled in from the bundled defaults automatically.

Color Names 🎨

MiniMessage knows exactly these 16 named colors (plus the spellings grey and dark_grey). Any other name, e.g. <light_red>, is not a color and shows up as literal text in chat.

Tag	Hex	Legacy code
<black>	#000000	§0
<dark_blue>	#0000AA	§1
<dark_green>	#00AA00	§2
<dark_aqua>	#00AAAA	§3
<dark_red>	#AA0000	§4
<dark_purple>	#AA00AA	§5
<gold>	#FFAA00	§6
<gray>	#AAAAAA	§7
<dark_gray>	#555555	§8
<blue>	#5555FF	§9
<green>	#55FF55	§a
<aqua>	#55FFFF	§b
<red>	#FF5555	§c
<light_purple>	#FF55FF	§d
<yellow>	#FFFF55	§e
<white>	#FFFFFF	§f

• <red> is the bright red (often called "light red"); <dark_red> is the darker one.
• Any other shade works as a hex color: <#FF8800>text</#FF8800> or <color:#FF8800>text</color>.
• Formatting tags such as <bold>, <italic>, <underlined>, <gradient:…> and <rainbow> are described in the MiniMessage format reference.

5. Commands & Permissions

Command	Permission	Default	Description
/timberella reload	timberella.admin	op	Reloads config, locales, mappings, watchers, and update checker.
/timberella version	none	–	Shows current plugin version (console + player).
/timberella toggle	timberella.toggle	true	Player-only toggle that switches Timberella (felling, replant, leaf cleanup) off/on for yourself.
/timberella toggle <player>	timberella.admin	op	Toggle for another player, online or offline (the player must have joined the server before). Tab completion lists online players only.

/timberella without a subcommand (or with an unknown one) shows the usage line, listing only the subcommands you are allowed to use.

Toggle states are stored in toggles.yml and survive restarts. The file is replaced in one step, so a crash while saving can't cut it off. If it can't be read completely (e.g. after a hand edit), the console warns and keeps a copy as toggles.yml.broken; players listed only there have Timberella on again until they switch it off.

Permission	Default	Grants
timberella.use	true	Felling whole trees (without it, only the broken block goes).
timberella.toggle	true	/timberella toggle for yourself.
timberella.admin	op	/timberella reload and /timberella toggle <player>.
timberella.update.notify	op	Update reminders on join (ops always receive them).

Use LuckPerms (or equivalent) to delegate without giving full operator access.

6. Troubleshooting & FAQ

Symptom	Resolution
Trees aren’t falling	Ensure the player has timberella.use and hasn't toggled Timberella off, sneak_mode matches how they chop, the axe is listed in tools.allowed_axes with at least tools.min_remaining_durability left, and the log material is enabled in categories.*. Players in adventure mode never fell trees. With require_natural_leaves: true, the tree also needs grown foliage (see What Counts as a Tree).
Only parts of a tree fall	A protection plugin or vanilla spawn protection denied some blocks (see Land Protection), or a species radius / max_blocks limit was reached.
Saplings fail to replant	Confirm enable_replant is true, soil beneath the trunk's lowest log is valid, and the sapling type exists in replant.saplings. With replant.sapling_source: drops, the leaves must actually drop a sapling (and enable_leaves_decay must be on). Under water, saplings other than mangrove propagules are only replanted with UnderwaterTrees (see Replant Section).
Leaves stay behind	Increase leaves_decay.decay_radius and, if needed, leaves_decay.max_distance. Player-placed leaves and leaves still held by another standing log stay on purpose (see Leaves Decay Section).
Nothing happens after config edit	Run /timberella reload or wait for the watcher interval (watches config.yml only); if the console reports that config.yml isn't valid YAML, fix the line it names (until then the previous settings stay active).
Players get spammed with updates	Set update_check.notify_op_join to false or remove the permission from non-admin staff.

• What does the console report after a reload? After each reload (command or watcher) it lists what changed since the last start or reload: changed settings in config.yml and leaf_mappings.yml with their new values, and changed, added or removed files in lang/. Comment or formatting edits don't count, and a file that can't be read is reported as a warning and treated as unchanged. log_stats and log_detail add the module status line and the detailed material listing.
• Can I disable Timberella per-world? Use your permission manager to remove timberella.use in worlds where the plugin should stay off, or deny block breaking there with a region plugin (Timberella respects it block by block). Timberella itself runs server-wide. Removing timberella.use stops felling and replanting; leaf cleanup is global and keeps running while enable_leaves_decay is true.
• What happens if bStats is disabled globally? Timberella respects the global plugins/bStats/config.yml opt-out as well as metrics_enabled and simply skips initializing metrics; no separate log line is printed for it.