spigot-tree-feller/design/log.md

Tree Feller Design Log

2026-08-11

US-003 animated tree felling completed

• Added eligibility-aware automatic felling for unlocked species with sneaking, saved preference, and administrative-lock bypasses.
• Added deterministic bottom-to-top scheduling at the configured interval, per-player and per-block overlap claims, and exact runtime snapshots of successfully removed blocks.
• Routed each additional trunk through Player.breakBlock so Spigot protection cancellation, drops, experience, enchantments, axe durability, and tool breakage remain authoritative.
• Felling now stops on cancellation, tool loss, state invalidation, logout, world unload, plugin disablement, changed blocks, or unloaded chunks and releases every runtime claim.
• Verified ordering, delay, overlap rejection, cancellation, eligibility, lifecycle safety, and the complete build with ./gradlew clean check jar.

US-002 progress visibility completed

• Added /treefeller unlocked with every species' durable unlocked state or current count and live threshold.
• Added one configurable boss bar per player with species and numeric progress, live threshold evaluation, timeout replacement, and five-second default cleanup.
• Suppressed progress presentation for all ineligible events and removed it immediately when a species unlocks.
• Verified command output, player-only completion, boss-bar presentation and timeout, cleanup, and the complete build with ./gradlew clean check jar.

US-004 personal controls completed

• Added /treefeller enabled [on|off] with durable, idempotent preference changes and administrative-override reporting.
• Added player-only usage and positional completion for enabled, unlocked, undo, and boolean values without exposing the administrative command tree.
• Registered configurable player messages and kept treefeller.command separate from treefeller.admin.
• Verified state preservation, reporting, autocomplete, metadata, and the complete build with ./gradlew clean check jar.

US-001 species unlock progression completed

• Added stable taxonomy for all approved overworld trees, Nether fungi, and giant mushrooms while excluding bamboo and treating azalea logs as oak.
• Replaced the old recursive search with a deterministic, bounded, iterative scanner that follows connected trunk blocks laterally and upward but never downward and requires matching foliage or caps.
• Added Survival-and-axe eligibility, automatic-break suppression, durable one-point increments, saturating counters, permanent unlocks, and next-qualifying-block threshold evaluation.
• Registered progress handling through the Spigot block-break lifecycle and persisted every accepted update before notifying observers.
• Verified taxonomy, detection, tools, eligibility, progression, persistence, and the complete build with ./gradlew clean check jar.

US-008 configuration and persistence completed

• Added validated settings for all supported species, search safety, animation, progress presentation, undo, titles, and messages.
• Added persistence-before-activation threshold changes and failure-safe active settings.
• Added UUID-keyed immutable player state with retained names, saturating progress, unlocks, preferences, locks, defensive reads, forward-field retention, and atomic YAML replacement.
• Invalid required configuration now disables partial plugin startup with a focused log message.
• Verified settings, persistence, corruption handling, atomic replacement, and the complete build with ./gradlew clean check jar.

Build foundation checkpoint

• Added the Java 17 Gradle project, Spigot 26.2 dependency, strict compilation, JUnit lifecycle, plugin metadata, wrapper, and Gitea CI and semantic-release workflows.
• Verified separate player and administrative command metadata through a failing-then-passing test.
• Verified the local foundation with ./gradlew clean check jar; remote workflow and release criteria remain pending final delivery verification.

Implementation started

• Began US-009 by establishing the test-first Gradle and plugin-metadata foundation.
• US-009 remains in progress until all stories and final delivery behavior have been verified.

Initial tree-felling design

• Players earn automatic felling separately for each supported tree species by manually mining qualifying tree blocks in Survival with an axe.
• Each species defaults to a 100-block unlock threshold; lowered thresholds are evaluated on the player's next qualifying block, while earned unlocks are permanent unless an administrator resets them.
• Supported species cover Spigot 26.2 overworld trees, crimson and warped fungi, and giant red and brown mushrooms; bamboo is excluded.
• The prior ../yetanothertreefeller/ search strategy informs detection: connected trunk blocks are searched laterally and upward, never downward, and associated foliage or caps establish that the structure is a tree. The new implementation will use bounded iteration rather than unbounded recursion.
• Unlocked trees break from bottom to top, one trunk block every two ticks by default. Leaves and caps are not automatically removed.
• Sneaking bypasses automatic felling. Players may also persistently enable or disable it with /treefeller enabled <on|off>.
• The player's latest felling may be undone for six minutes by default. Undo preflights the complete operation, reclaims all required replacement materials from inventory, and reports shortages without making partial changes.
• Unlock progress is shown through /treefeller unlocked and a temporary boss bar. Unlocks produce a title and a chat explanation of sneaking and undo.
• Player commands use /treefeller; administration uses the separate /treefelleradmin command and treefeller.admin permission.
• Administrators can inspect players, grant or reset species, lock all automatic felling for a player, and persistently change species thresholds. Administrative locking does not stop manual progress.
• Build and release conventions follow ../spigot-getgud/, including Spigot API 26.2-R0.1-SNAPSHOT, Java 17, Gradle, strict compilation, tests, and Gitea automation.