Stash Buster

# Stash Buster

Creepers stop chasing you and start **hunting your storage**. A creeper scans the containers
*you* placed around it, picks the one holding the most items, walks over, and blows it open.

## What it does

- **Targets storage, not people.** Chests, trapped chests, barrels, shulker boxes, hoppers,
  dispensers, droppers, crafters, the whole furnace family, brewing stands, decorated pots,
  chiseled bookshelves - and **any container from any other mod** that implements the standard
  `Container` interface. Ender chests are excluded.
- **Picks the fullest container.** Score is `itemCount - 1.5 * distance`, so by default a full
  chest outweighs roughly 10 blocks of distance. It will ignore the empty chest beside it and
  cross the room for the loaded one.
- **Player-placed only.** Natural chests in villages, dungeons and ruins are untouched, loot or
  not. Placement is recorded per dimension and persisted in the save.
- **Players still come first.** The moment a creeper locks onto you it abandons the chest.
  Creative and spectator players are never targeted (vanilla behaviour) - but a creative player
  within 24 blocks *does* activate the behaviour.
- **Only within 24 blocks of a player.** No non-spectator player nearby, no raid. Walk out of
  range mid-approach and it gives up.
- **It is afraid of cats.** A cat or ocelot nearby makes it break off and flee - so a cat by
  your storage room actually protects it.
- **Contents still scatter.** Blowing up a container drops its contents; that is vanilla
  behaviour and this mod deliberately does not reimplement it.

## Configuration

Generated at `config/stashbuster-common.toml`:

| Key | Default | Description |
|---|---|---|
| `enabled` | `true` | Master switch |
| `searchRadius` | `24` | Search radius, also used as the "player within N blocks" activation radius |
| `requireNearbyPlayer` | `true` | Require a nearby player (only spectators are excluded) |
| `minimumItemCount` | `1` | Containers below this item count are ignored; `0` lets it blow up empty ones |
| `scoreUpdateIntervalTicks` | `20` | Minimum interval between target re-evaluations |
| `excludedBlocks` | `["minecraft:ender_chest"]` | Block IDs that never get raided |
| `distancePenalty` | `1.5` | Score penalty per block of distance |
| `countMode` | `TOTAL_ITEMS` | Count stacked items, or occupied slots |

## Compatibility and performance

- **Server-side only.** No rendering, UI, keybinds or packets. Install on the server; for
  singleplayer nothing extra is needed.
- **No world scanning.** It only iterates the set of positions where a player placed a
  container, filters by distance arithmetically first, and only then reads container contents.
- **No custom explosions.** It just lights the vanilla fuse - blast radius, damage, sound and
  the creeper's own death all stay vanilla.
- **No duplicated logic.** Container loot dropping is left to vanilla.

## Requirements

- Minecraft **1.21.1**
- **NeoForge 21.1.x**
- Singleplayer or dedicated server

## How is this different from other "smart creeper" mods?

- It only ever targets containers a player actually placed - tracked on placement and persisted
  per dimension. Natural village and dungeon loot is untouched.
- It ranks targets by item count, not by block type. The fullest container wins.
- It respects vanilla: creepers still flee from cats and ocelots, and survival players still
  take priority over any chest.
- Server-side only - players do not need to install anything.

## Known limitations

- Entity containers (chest minecarts, chest boats, hopper minecarts) are not handled - they are
  not blocks, so there is no placement event to hook.
- Containers in unloaded chunks cannot be read, so the effective range is bounded by chunk loading.
- A cat tethered next to your storage room will keep it safe. Feature, not a bug.