99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
# 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](design/index.md).
|
|
|
|
## Requirements
|
|
|
|
- Spigot 26.2
|
|
- Java 17 or newer
|
|
|
|
## Build
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
TREE_FELLER_START_TIMEOUT=1200 \
|
|
TREE_FELLER_RCON_PASSWORD='local-secret' \
|
|
./scripts/start-test-server.sh
|
|
```
|
|
|
|
Common lifecycle commands:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```text
|
|
/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
|
|
|
|
```text
|
|
/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. Unlock progress counts unstripped natural log and Nether stem materials even after the surrounding tree has been disrupted; wood, hyphae, stripped variants, and bamboo do not count. Player-placed qualifying materials are indistinguishable from generated materials in Spigot and therefore also count. Giant mushroom stems require enough cap context to identify their species.
|
|
|
|
## 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.
|
|
|
|
Automatic felling supports Spigot 26.2 wooden, stone, copper, iron, golden, diamond, and netherite axes. 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`.
|