# Tree Feller Design Log

## 2026-08-11

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

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

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

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