# Sprout — Admin Setup Guide
*A lightweight utility pack for survival/semivanilla servers. This guide shows how to install, configure, and run Sprout features like VeinMiner and Graves. All examples use Paper 1.20.x, LuckPerms, and (optionally) PlaceholderAPI.*
---
## 🔧 Installation
1. **Drop the jar**
- Put `sprout-<version>.jar` into `/plugins/`.
2. **Start the server once**
- Sprout will generate `/plugins/Sprout/config.yml` and data files.
3. **(Optional) Hook-ins**
- **LuckPerms** for permissions.
- **PlaceholderAPI** if you want scoreboard/menu placeholders.
4. **Reload/Restart**
- Use `/sprout reload` after editing config files.
---
## 📦 File Layout
```
plugins/
└─ Sprout/
├─ config.yml # Global settings (see below)
├─ veinminer-players.yml # Per-player VeinMiner toggles/mode/depth + debug list
└─ logs/ # Your standard server logs show Sprout debug/info
```
> **Persistence:** Player VeinMiner state (enabled/disabled, mode, depth, and debug on/off) is stored in **`veinminer-players.yml`** and survives restarts. If this file is deleted, defaults are used until players change settings again.
---
## 🛡️ Permissions (LuckPerms)
Grant these to the groups that need them:
```bash
# Core
lp group default permission set sprout.veinmine.use true # allow using VeinMiner
lp group default permission set sprout.veinmine.toggle true # allow /vm toggle
lp group default permission set sprout.veinmine.command true # general /vm access
lp group admin permission set sprout.veinmine.debug true # allow /vm debug
lp group admin permission set sprout.admin true # Sprout admin (reload)
lp group admin permission set sprout.graves.admin true # graves admin tools
```
> If you run a very locked-down server, also give players the specific tools they can use (see `veinminer.tools.restrict` below).
---
## ⚙️ `config.yml` (key options)
```yml
veinminer:
enabled: true # master switch for the feature
applyPhysics: true
extrasPerTickBase: 80 # performance budget; scaled per-tick
batchXp: true # combine XP orbs
debug: false # also toggle per-player with /vm debug
maxBlocks: 64
requireSneak: true
requirePermission: true
damageToolPerExtra: true
respectOtherCancels: true # honor other plugins' BlockBreakEvent cancels
dropAtPlayerFront: false
tools:
restrict: false # if true, only allow tools below
allow:
- DIAMOND_PICKAXE
- NETHERITE_AXE
# ...
include: # what blocks/groups can be vein-mined
- "#LOGS"
- "#ORES"
- "#CROPS"
- "#COLUMNS"
exclude: [] # black-list materials/tags here
hunger:
enabled: true
perBlock: 0.05 # food points per block (1.0 = one drumstick)
mode: EXHAUSTION # EXHAUSTION | FOOD_LEVEL
minFoodToUse: 0
message:
tooHungry: "&cYou're too hungry to veinmine."
search:
mode: CONNECTED # CONNECTED | RADIUS (for non-shape mode)
diagonals: true
radius: 5
graves:
enabled: true # Graves feature master switch (if included in your build)
# (your graves-specific settings live in this section if present)
message:
toggleOn: "&aVeinMiner enabled."
toggleOff: "&7VeinMiner disabled."
```
**Notes**
- `include`/`exclude` accepts material names or category tags like `#LOGS`, `#ORES`, `#LEAVES`, etc.
- `hunger.mode = FOOD_LEVEL` subtracts whole food points smoothly and keeps fractional cost across uses.
- Per-player **mode** and **depth** are stored in `veinminer-players.yml` and persist across restarts.
---
## 🧰 Commands
### Core
```
/sprout reload # reloads Sprout config
```
### VeinMiner
```
/vm # toggle on/off (per player)
/vm toggle # alias
/vm mode # show current mode + depth
/vm mode <2x2|3x3|4x4|layer|connected|radius> [depth]
/vm debug # (admin) toggles rich debug for *you* + logs
```
- **Depth** works as “forward layers” from the block face you broke.
- **Odd sizes** (3x3) are perfectly centered. **Even sizes** (2x2, 4x4) are visually centered against the broken face.
### Graves (Admin)
> Only if the Graves module is present in your build.
```
/grave tp <player> [index] # teleport to a player's grave; if multiple, pick the index
/grave list <player> # show indexed graves for that player
/grave purgeempty # remove empty/invalid graves (safe operation)
/grave purge all # hard purge (be careful)
```
---
## 🔎 VeinMiner Modes (quick reference)
- **connected** – classic flood-fill vein mining (can include diagonals).
- **radius** – grabs closest blocks of the same type inside a cubic radius.
- **2x2 / 3x3 / 4x4** – breaks a prism aligned to the **face you actually mined**.
- Depth = number of layers forward from the hit face.
- Only blocks of the **same type** as the origin are included.
- **layer** – contiguous region on the same Y level as the origin block.
---
## 🧪 Debugging VeinMiner
Enable per-player debug to see exactly which coordinates are tried/accepted:
```
/vm debug
```
Debug messages show:
- Face and axes chosen for your hit (`f`, `u`, `v`)
- Every attempted coordinate with ACCEPT/skip + material
- What actually breaks and drops
- Final hunger cost calculation
Disable it with `/vm debug` again.
> There is also a **global** toggle via `veinminer.debug: true` in `config.yml`.
---
## 👤 Player Experience & Tips
- Players can keep VeinMiner **enabled** but require **sneak** to trigger (configurable).
- If a tool breaks too quickly, either raise durability or set `damageToolPerExtra: false`.
- Use `dropAtPlayerFront: true` to funnel all extra drops to a clean spot in front of the player.
---
## 🧽 Maintenance
- Back up `veinminer-players.yml` if you care about modes/toggles persisting.
- If something seems off after a config change: `/sprout reload` and test with `/vm debug`.
- Conflicts: If another plugin cancels block break events, set `respectOtherCancels: false` (not recommended), or whitelist Sprout in that plugin.
---
## ❓ FAQ
**Q: My 3x3x3 sometimes becomes 3x3x1.**
A: Shape depth is taken **forward from the face you hit**. If you mine the top/bottom face, your forward axis is up/down; mine a side face for forward = north/south/east/west. Debug shows the chosen face.
**Q: Do players keep their mode/depth across restarts?**
A: Yes. It’s saved in `veinminer-players.yml`.
**Q: I don’t want logs/leaves in connected mode.**
A: Add a tag or material to `exclude:` or remove the tag from `include:` and reload.
**Q: Can I restrict VeinMiner to specific tools?**
A: Set `veinminer.tools.restrict: true` and list allowed tool materials under `allow:`.
---
### Changelog Hints (for admins writing patch notes)
- ✅ Added: `/vm debug` per-player toggle; also persists in `veinminer-players.yml`.
- ✅ Shape mining now uses **hit face** + integer axes for consistent 2x2/3x3/4x4 prisms.
- ✅ Player mode/depth/toggle **persist across restarts**.
- ✅ Rich debug messages for attempts, accepts, drops, and hunger math.