4.0 KiB
Tree Feller
Tree Feller is a Spigot 26.2 plugin that lets Survival players earn animated automatic felling independently for each vanilla tree family.
The approved behavior and implementation record are in the OKF design bundle.
Requirements
- Spigot 26.2
- Java 17 or newer
Build
./gradlew clean check jar
The plugin JAR is written to build/libs/.
Local Docker test server
Build the current plugin and start it on an isolated Spigot 26.2 server:
./scripts/start-test-server.sh
Connect to localhost:25565 as WindMagi, which the harness configures as a level-4 operator using its deterministic offline-mode UUID. The committed docker/test-ops.json fixture replaces local operator state on every startup so the offline UUID remains deterministic. The server uses offline mode for local convenience and binds only to the loopback interface.
The first startup may take several minutes while the image downloads and Spigot is prepared. Override the 15-minute wait or local RCON password when needed:
TREE_FELLER_START_TIMEOUT=1200 \
TREE_FELLER_RCON_PASSWORD='local-secret' \
./scripts/start-test-server.sh
Common lifecycle commands:
# Follow server logs
docker compose -f compose.test.yml logs -f minecraft
# Stop while preserving the world and server configuration
docker compose -f compose.test.yml down
# Stop and permanently reset all generated local test state
docker compose -f compose.test.yml down
rm -rf .docker/minecraft
Re-run the start script after code changes to rebuild the JAR and recreate the test container. Generated server state remains under .docker/minecraft/ and is ignored by Git.
Player commands
/treefeller enabled [on|off]
/treefeller unlocked
/treefeller undo
Sneaking while breaking the initiating trunk block bypasses automatic felling. Undo restores only the latest eligible felling, requires all replacement trunk materials in the player's inventory, and defaults to a six-minute window.
Administrative commands
/treefelleradmin player <name|uuid> status
/treefelleradmin player <name|uuid> tree <type> <grant|reset>
/treefelleradmin player <name|uuid> locked <on|off>
/treefelleradmin threshold <type> <blocks>
Administrative commands require treefeller.admin, granted to server operators by default. Player commands and undo use separate non-administrative permissions.
Supported species
- Oak, spruce, birch, jungle, acacia, and dark oak
- Mangrove, cherry, and pale oak
- Crimson and warped fungi
- Giant red and brown mushrooms
Azalea-grown logs count as oak. Bamboo is not treated as a tree.
Configuration and state
config.yml controls per-species thresholds, animation delay, bounded search limits, boss-bar presentation, undo duration, unlock titles, and messages. Defaults include 100 manually mined qualifying blocks per species, two ticks between animated blocks, five seconds of progress visibility, and six minutes for undo.
Player preferences, administrative locks, progress, unlocks, and known names are stored by UUID in players.yml. Undo records are intentionally runtime-only and do not survive restart.
Safety and compatibility
Tree detection searches matching natural trunk blocks laterally and upward, never below the initiating chop, and requires corresponding foliage or caps. Search bounds prevent unbounded traversal. Leaves, caps, roots, vines, and decorations are not automatically broken.
Additional trunk blocks use Spigot's Player.breakBlock path so block-break cancellation, drops, experience, enchantments, and axe durability remain authoritative. Protection plugins should cancel BlockBreakEvent normally. A cancelled additional break stops the remaining felling.
Releases
Gitea Actions checks pushes and pull requests, validates pull-request conventional commits, and stores development JARs. Conventional commits on main drive semantic releases after the repository defines a contents-write RELEASE_TOKEN.