---
type: User Story
title: "US-008: Configure and persist Tree Feller"
description: Provide validated configuration and durable player state for predictable tree-felling behavior.
status: backlog
---

# US-008: Configure and persist Tree Feller

As a **server operator**, I want Tree Feller's behavior and player progression stored safely so that upgrades and restarts do not cause surprises or lost progress.

## Acceptance criteria

- [ ] Configuration defines supported species and their thresholds, each defaulting to 100 qualifying blocks.
- [ ] Configuration defines an animation delay defaulting to two server ticks per felled block.
- [ ] Configuration defines a progress boss-bar timeout defaulting to five seconds and an undo window defaulting to six minutes.
- [ ] Configuration includes bounded tree-search limits, boss-bar presentation, title timing, and all player-facing messages.
- [ ] Numeric settings reject zero, negative, overflowing, or operationally unsafe values using documented bounds.
- [ ] Invalid required configuration prevents partial plugin initialization and produces a clear server log message identifying the setting.
- [ ] Runtime threshold changes made through `/treefelleradmin` are persisted before becoming active and survive restart.
- [ ] A failed runtime configuration write leaves the active threshold unchanged.
- [ ] UUID-keyed player state persists latest known name, enabled preference, administrative lock, per-species progress, and earned unlocks.
- [ ] Player identity resolution safely retains previously known names while UUID remains authoritative.
- [ ] Player state is written atomically where supported so that a failed write does not replace valid state with a partial document.
- [ ] Corrupt or invalid player records are handled defensively and cannot silently grant unlocks or administrative privileges.
- [ ] Progress that exceeds a currently configured threshold is retained, and counters cannot overflow.
- [ ] Unknown forward-compatible configuration and player-state fields are preserved where practical.
- [ ] Undo records are runtime safety records and do not survive a server restart unless a later approved design explicitly adds durable undo.

## Related

- [US-001: Earn tree-type unlocks](us-001-earn-tree-type-unlocks.md)
- [US-002: View tree progress](us-002-view-tree-progress.md)
- [US-003: Fell unlocked trees](us-003-fell-unlocked-trees.md)
- [US-005: Undo the last felled tree](us-005-undo-the-last-felled-tree.md)
- [US-007: Administer Tree Feller](us-007-administer-tree-feller.md)
- [US-009: Build and release Tree Feller](us-009-build-and-release-tree-feller.md)