Essential Utils

A Folia-optimized survival convenience plugin for Paper/Folia 1.21.8.
Adds smooth, lag-free mechanics like tree chopping, vein mining, and auto-farming.

---

✨ Features

• 🌲 Tree Assist (axe)

  • Incrementally chops connected logs with per-block delay (smooth, no spikes).
  • Leaf checks to avoid cutting adjacent trees.
  • Optional auto-replant (saplings/propagules), retries with cooldown until successful.
  • Durability decreases once per N blocks, not per block.

• ⛏ Vein Mine (pickaxe)

  • Incrementally mines connected ore veins.
  • Enforces Minecraft tool tier rules:
    • If tier too low → no break, alert shown (rate-limited).
  • Delay per block scales with vein size.
  • Durability decreases once per N blocks.

• 🌾 Auto Farm (hoe)

  • Harvests only mature crops in a radius.
  • No auto-replant (intentional).
  • Optimized for local chunk scans.

• ⚙ Activation

  • Hold Shift for 5 seconds → arms tool (progress bar shown).
  • Once armed, stays armed even after releasing Shift.
  • Deactivates only when item is changed or player quits.

• 🛡 Safety

  • Respects protections (future: WorldGuard/GriefDefender hooks).
  • Requires loaded chunks.
  • Folia region-safe scheduling only (no async hacks).

• 📊 Performance

  • Centralized per-player tick budget.
  • Strict per-feature caps.
  • Smooth staggered breaking.

---

📂 Project Structure

src/main/java/net/ppekkungz/essentialUtils/
├── EssentialUtils.java
├── config/PluginConfig.java
├── state/StateManager.java
├── listener/ActivationListener.java
├── work/
│   ├── WorkService.java
│   ├── WorkItem.java
│   └── WorkQueue.java
├── features/
│   ├── Feature.java
│   ├── tree/TreeAssistFeature.java
│   ├── vein/VeinMineFeature.java
│   └── farm/AutoFarmFeature.java
├── util/
│   ├── HarvestUtil.java
│   ├── Materials.java
│   └── Ores.java
└── indicator/
    ├── BossBarIndicator.java
    └── ActionBarIndicator.java

---

⚡ Usage

1. Drop EssentialUtils-x.x.x.jar into your plugins/ folder.
2. Run with Paper 1.21.8+ and Folia.
3. Config (config.yml) is generated on first run.

Commands

/eutils reload   # reloads config.yml

Permission

essentialutils.admin   # required for /eutils reload (default: op)

---

⚙ Config Highlights

activation:
  holdSneakSeconds: 5
  requireToolWhileHold: true

features:
  treeAssist:
    breakDelayTicks: 2
    durabilityPerNBlocks: 8
    replant:
      enabled: true
      retryCooldownTicks: 5
      maxRetries: 10

  veinMine:
    breakDelayBaseTicks: 1
    breakDelayExtraPer16: 1
    durabilityPerNBlocks: 10
    alertOnInsufficientTier: true

  autoFarm:
    replant: false

---

🛠 Build

Requires:

• JDK 21
• Gradle (wrapper included)

Build with:

./gradlew build

Jar output:

build/libs/essential-utils-<version>.jar

---

✅ TODO / Roadmap

• Tree Assist (incremental, replant, durability-per-N)
• Vein Mine (incremental, tier alerts, delay scaling, durability-per-N)
• Auto Farm (mature crops only, no replant)
• Activation (Shift-hold progress, persists armed, deactivates on item change)
• Config reload (/eutils reload)
• Folia-safe scheduling
• Strict per-feature caps
• Protection hooks (WorldGuard/GriefDefender)
• BossBar indicators during ACTIVE
• Configurable durability rules per tool type
• Additional auto-farm crops (bamboo, sugarcane, kelp)
• Multi-language messages
• Metrics toggle (bStats)
• Per-player toggle commands (enable/disable features individually)

---

📜 License

MIT © 2025 ppekkungz