113 lines
10 KiB
Markdown
113 lines
10 KiB
Markdown
# Tree Feller Design Log
|
|
|
|
## 2026-08-11
|
|
|
|
### US-010 local Docker test server completed
|
|
|
|
- Added a repository-local Docker Compose harness using `itzg/minecraft-server:java25` with Spigot 26.2, persistent ignored state, offline local testing, and loopback-only port binding.
|
|
- Added one executable script that runs the strict Gradle build, recreates the isolated container with the latest JAR, waits for health, verifies Tree Feller through RCON, and confirms `WindMagi` as an operator.
|
|
- Documented start, log, stop, persistent-state reset, timeout, and RCON-password controls.
|
|
- Live verification completed in 23 seconds: the container was healthy, RCON reported `TreeFeller`, `ops.json` contained `WindMagi` at level 4, and port 25565 was bound only to `127.0.0.1`.
|
|
- The test server remains running at `localhost:25565` for gameplay testing.
|
|
|
|
### US-009 build and release completed
|
|
|
|
- Added maintainer documentation for requirements, builds, commands, configuration, supported species, persistence, safety, compatibility, and releases.
|
|
- Verified workflow YAML, pull-request conventional-commit validation, development artifacts, semantic versioning, and Gitea release attachment configuration against `../spigot-getgud/`.
|
|
- Verified the complete strict test lifecycle and a release-version build with `./gradlew clean check jar -PreleaseVersion=1.2.3`, producing `build/libs/tree-feller-1.2.3.jar`.
|
|
- Verified every user story is done, the OKF bundle conforms, the repository has no remote, and no push or release was attempted.
|
|
|
|
### US-006 unlock announcements completed
|
|
|
|
- Verified that earned unlocks alone produce the configurable achievement title and safety guidance exactly once per earned cycle.
|
|
- Administrative grants now send a distinct online chat notification without presenting a mined-block achievement or title.
|
|
- Verified reset-and-reearn behavior, invalid-event suppression, administrative distinction, and the complete build with `./gradlew clean check jar`.
|
|
|
|
### US-007 administration completed
|
|
|
|
- Added the dedicated permission-gated `/treefelleradmin` tree for player status, species grants and resets, global player felling locks, and persistent per-species thresholds.
|
|
- Added exact live-name, durable-alias, and UUID target resolution with ambiguity rejection and UUID authority.
|
|
- Added positional, permission-aware completion for roots, known players, properties, species identifiers, actions, and boolean values.
|
|
- Administrative mutations are idempotent, persist before reporting success, preserve unrelated state, and notify online targets without using earned-achievement titles.
|
|
- Administratively locked players continue manual progress, receive a configurable explanation when felling is suppressed, and retain their preference and unlocks.
|
|
- Verified grants, resets, locks, thresholds, identity safety, online messaging, autocomplete, authorization, and the complete build with `./gradlew clean check jar`.
|
|
|
|
### US-006 unlock announcement checkpoint
|
|
|
|
- Added configurable, placeholder-aware titles, subtitles, timing, and chat guidance for newly earned species.
|
|
- Progress presentation now removes the completed boss bar before showing the one-time achievement and guidance about sneaking and undo.
|
|
- Verified earned and ordinary progress paths plus the complete build with `./gradlew clean check jar`.
|
|
- US-006 remains in progress until US-007 verifies distinct online messaging for administrative grants.
|
|
|
|
### US-005 safe undo completed
|
|
|
|
- Added one runtime-only latest-felling record per player with original world, coordinates, material, block-data string, and completion time.
|
|
- Added `/treefeller undo` behind the separate `treefeller.undo` permission and the configurable six-minute default window.
|
|
- Undo now preflights worlds, loaded chunks, empty target positions, exact block data, and aggregate inventory materials before making any change.
|
|
- Missing-material failures report every material and quantity; successful undo withdraws materials once, restores orientation-aware block data without physics, and consumes the record.
|
|
- Unexpected inventory or world failures roll back changed blocks and inventory where possible and preserve the record while logging suppressed recovery failures for administrators.
|
|
- Verified shortages, occupied locations, expiration, successful restoration, command reporting, permissions, and the complete build with `./gradlew clean check jar`.
|
|
|
|
### 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.
|