Donut SpawnStash Free v1.0

# SpawnStash
SpawnStash is a Paper plugin for Minecraft 1.21.x that places a fake stash at a player's location with a spawner, chest, and shulker box. The stash can overwrite normal blocks in its footprint, the loot is configurable, and staff can receive alerts when players mine near or break a tracked stash.
## Features

• Spawns a 3-block fake stash with /spawnstash
• Replaces most blocks in the way instead of failing on occupied space
• Protects special blocks like BEDROCK, portal blocks, barriers, and command blocks from being overwritten
• Lets you customize the chest loot
• Lets you customize the shulker box type and shulker loot
• Lets you customize the spawned mob type in the spawner
• Tracks placed stashes across restarts in stashes.yml
• Sends alerts when players mine near a tracked stash or break part of one

## Dependencies

• Java 21
• Maven 3.9+ recommended for local builds
• A Paper server compatible with 1.21.x
• Paper API dependency used by this project:

- io.papermc.paper:paper-api:1.21.1-R0.1-SNAPSHOT
## Build
Build the plugin jar with:
The built jar is created at:
target/SpawnStash-1.0.0.jar
## Installation
1. Build the jar with Maven, or use the jar from target/.
2. Stop your Paper server.
3. Put SpawnStash-1.0.0.jar into your server's plugins folder.
4. Start the server.
5. Edit plugins/SpawnStash/config.yml if you want to change loot, alerts, or the spawner mob.
6. Restart the server or reload the plugin through your normal server-management workflow.
## Command
- /spawnstash
- Spawns one fake stash centered on the block at the player's feet.
## Permissions
- spawnstash.use
- Allows a player to use /spawnstash
- Default: true
- spawnstash.alerts
- Receives mining and grief alerts for tracked stashes
- Default: op
## How It Works
When a player runs /spawnstash, the plugin places:

• A spawner at the player's current block
• A chest one block to the east
• A shulker box two blocks to the east

If normal blocks are in the way, they are replaced. If protected blocks are in the way, the stash will not spawn.
Each placed stash is tracked in plugins/SpawnStash/stashes.yml. That tracking is used for alerts:

• nearby alert: a player breaks a block near a tracked stash
• grief alert: a player breaks one of the stash's tracked blocks directly

## Config Reference
Default config:
### Config Options
- stash.spawner-entity
- The mob type used for the spawner
- Example: ZOMBIE, SKELETON, SPIDER
- stash.shulker-material
- The shulker box block type to place
- Example: SHULKER_BOX, RED_SHULKER_BOX, BLACK_SHULKER_BOX
- stash.chest-items
- A list of items for the chest
- Format: MATERIAL:AMOUNT
- stash.shulker-items
- A list of items for the shulker
- Format: MATERIAL:AMOUNT
- alerts.enabled
- Turns stash alerts on or off
- alerts.notify-console
- Sends alerts to the server console
- alerts.permission
- Permission node used to receive player-facing alerts
- alerts.near-stash-radius
- How close a broken block must be to count as "mining near" a stash
- alerts.cooldown-seconds
- Per-player, per-stash cooldown to prevent alert spam
- alerts.messages.nearby
- MiniMessage alert format for nearby mining
- alerts.messages.grief
- MiniMessage alert format for directly breaking a tracked stash block
## Example Config 1: Rich PvP Bait
## Example Config 2: Quiet Admin Honeypot
## Tutorial
### Create a fake stash
1. Join the server with permission to use /spawnstash.
2. Stand where you want the stash to appear.
3. Run /spawnstash.
4. Check the placed spawner, chest, and shulker box.
### Customize the loot
1. Open plugins/SpawnStash/config.yml.
2. Edit stash.chest-items and stash.shulker-items.
3. Use MATERIAL:AMOUNT values such as DIAMOND:12.
4. Save the file and restart the plugin or server.
### Change the shulker box color
1. Open config.yml.
2. Set stash.shulker-material to a valid shulker material like BLUE_SHULKER_BOX.
3. Restart and spawn a new stash.
### Turn alerts up or down
1. Set alerts.enabled to true or false.
2. Change alerts.near-stash-radius to decide how close mining has to be.
3. Change alerts.cooldown-seconds if alerts are too noisy.
4. Give trusted staff the spawnstash.alerts permission.
## Troubleshooting
- The command works but loot is wrong
- Check that item names are valid Bukkit Material names
- Example: use GOLD_INGOT, not gold_ingot with spaces or display names
- The stash does not spawn
- Make sure the footprint is not blocked by protected blocks like BEDROCK or portal blocks
- There are no alerts
- Make sure alerts.enabled is true
- Make sure the receiving staff member has spawnstash.alerts
- Make sure the broken block is either part of the stash or within the configured nearby radius
- A stash stops alerting after it is griefed
- Directly broken stash blocks are removed from tracking once destroyed
## Notes

• Current stash layout is fixed to a straight 3-block line.
• Alerts track spawned stashes by saved block positions, not by chest contents or metadata.
• Existing tracked stashes are stored in stashes.yml inside the plugin data folder.