ChestRefiller

# ChestRefiller

ChestRefiller is a loot refill and randomization plugin for Minecraft servers (Arclight/Bukkit).  
It refills nearby **chests** and **barrels** with configurable **probabilities**, **random slot placement**, strict per-container limits, and support for **modded items** plus **exact chest item copy**.

Compatible with:
- Arclight 1.21.1 (Bukkit/Spigot API)

## What it does
- Scans **loaded blocks only** around the player in a range.
- Finds containers:
- Chests (single + double)
- Trapped chests
- Barrels
- Refills each container from a config loot pool:
- Weighted chance per entry (`chancePercent`)
- Random slot placement (not sequential)
- Supports:
- `itemsPerContainer` (separate chest/barrel)
- `maxPerItemPerContainer` (default + overrides)
- `allowDuplicates`
- `clearBeforeRefill` (fresh refill) or fill only empty slots
- Optional random amount per stack (`amountMin/amountMax` or global min/max)

## New features
- **Modded item support**:
- Use namespaced ids like `modid:item_name` in `loot` and `lootMap`.
- Unknown/invalid ids are skipped safely with console warnings.
- **Exact chest item copy (`/savechest`)**:
- Command: `/savechest `
- Reads that container and saves non-empty slots into `savedItems` in config.
- Preserves exact `ItemStack` data (meta/lore/enchants/custom NBT data carried by stack serialization).
- Slot index is **1-based** (first slot = 1, fourth slot = 4).
- You can reference saved slots directly in loot:
- `item: 4`
- `savedSlot: 32`
- `item: saved:32`
- Also supported in `lootMap`:
- `4: 25`
- `saved:32: 10`

## Commands
- `/chestrefill `: Refill nearby containers in range.
- `/chestrefill reload`: Reload config safely.
- `/savechest `: Save exact container contents by slot into `savedItems`.

## Permissions
- `chestrefill.use`: use `/chestrefill `
- `chestrefill.admin`: use `/chestrefill reload` and `/savechest`

## Important limits
- Does not scan the whole world.
- Does not force-load chunks.
- Scans only loaded chunks to reduce lag.
- Runs in batched scheduled ticks to avoid freezing.
- Loot output varies per run due to weighted random + limits.

## Requirements
- Arclight server with Bukkit/Spigot plugin support.
- Java 21.
- No client mod required.

---

# ChestRefiler

ChestRefiller es un plugin de refill de loot y aleatorización para servidores Minecraft (Arclight/Bukkit).  
Rellena **cofres** y **barriles** cercanos con **probabilidades configurables**, **slots aleatorios**, límites estrictos por contenedor, y soporte para **ítems de mods** + **copiado exacto de cofre**.

Compatible con:
- Arclight 1.21.1 (API Bukkit/Spigot)

## ¿Qué hace?
- Escanea solo **bloques cargados** alrededor del jugador.
- Encuentra contenedores:
- Cofres (simples + dobles)
- Cofres trampa
- Barriles
- Rellena cada contenedor desde un loot pool en config:
- Probabilidad ponderada por entrada (`chancePercent`)
- Colocación en slots aleatorios (no secuencial)
- Soporta:
- `itemsPerContainer` (separado cofre/barril)
- `maxPerItemPerContainer` (default + overrides)
- `allowDuplicates`
- `clearBeforeRefill` (vaciar y refill fresh) o solo slots vacíos
- Cantidades aleatorias por stack (`amountMin/amountMax` o min/max global)

## Novedades
- **Soporte de ítems modded**:
- Puedes usar ids con namespace como `modid:item_name` en `loot` y `lootMap`.
- Si un id no existe, se ignora sin crashear y se muestra warning en consola.
- **Copia exacta de ítems de cofre (`/savechest`)**:
- Comando: `/savechest `
- Lee el contenedor y guarda los slots no vacíos en `savedItems` dentro de la config.
- Conserva el `ItemStack` exacto (meta/lore/enchants/NBT personalizado serializable).
- Los slots son **1-based** (primer slot = 1, cuarto slot = 4).
- Puedes referenciar esos slots guardados en loot:
- `item: 4`
- `savedSlot: 32`
- `item: saved:32`
- También en `lootMap`:
- `4: 25`
- `saved:32: 10`

## Comandos
- `/chestrefill `: rellena contenedores cercanos.
- `/chestrefill reload`: recarga config de forma segura.
- `/savechest `: guarda el contenido exacto del contenedor por slot en `savedItems`.

## Permisos
- `chestrefill.use`: usar `/chestrefill `
- `chestrefill.admin`: usar `/chestrefill reload` y `/savechest`

## Límites importantes
- No escanea el mundo completo.
- No fuerza carga de chunks.
- Solo escanea chunks ya cargados para minimizar lag.
- Usa escaneo por lotes por tick para evitar congelar el servidor.
- El loot varía según probabilidad ponderada y límites configurados.

## Requisitos
- Servidor Arclight con soporte Bukkit/Spigot.
- Java 21.
- No requiere mod en cliente.