Fill Loot

Overview

Fill Loot fundamentally changes how exploration works on your Minecraft server by giving you absolute, granular control over the loot that spawns in naturally generated structures. Instead of relying on the boring, predictable Vanilla loot tables (like finding rotten flesh and bones in a dungeon), you can inject your own custom economy vouchers, rare server gear, custom model data items, and lore books into dungeons, strongholds, villages, and custom structures.

Key Features

• Structure-Specific Injection: Set entirely different loot tables based on the structure type. You can ensure that End City chests generate god-tier loot while Igloo chests only generate basic survival supplies.
• Complete NBT & Custom Item Support: Fill Loot fully supports item names, lore, enchantments, and custom model data. It also supports running console commands upon chest generation, allowing seamless integration with custom item plugins like ItemsAdder or MMOItems.
• Global Restock Timers: Optionally allow chests to automatically restock themselves after a defined period (e.g., 24 hours). This breathes life into old chunks and ensures that new players joining your server months later still find valuable loot when exploring.
• Per-Player Instancing (Anti-Loot Goblin): An incredibly powerful optional feature that makes chest loot unique to every single player who opens it. Player A can loot a chest, and Player B can walk up to the exact same chest and get their own completely separate loot roll, effectively ending loot-stealing toxicity on SMPs.
• Extreme Performance Optimization: Unlike other plugins that scan chunks and place items during terrain generation (causing massive lag spikes), Fill Loot is completely lazy. It simply flags chests during generation. The heavy lifting of calculating weights and populating items only happens exactly at the millisecond a player right-clicks the chest.

Step-by-Step Setup Guide

Follow these instructions to inject custom items into vanilla structures and set up manual custom chests.

1. Defining a Loot Table:

   Open config.yml and locate the structures section. Each key here matches a vanilla structure namespace, like minecraft:simple_dungeon or minecraft:village_blacksmith. Define the items and their weights (chances to spawn) under that section.

2. Adding Custom Items In-Game:

   If you don't want to mess with YAML configuration, you can hold an item in your hand and type /fillloot additem minecraft:simple_dungeon 50 (where 50 is the weight). The plugin will read the exact NBT data of the item in your hand and save it to the config.

3. Applying Changes:

   Run /fillloot reload. The next time a player explores a newly generated chunk and opens a chest in that structure, it will populate with your custom table instead of vanilla loot.

4. Creating Custom Dungeon Chests:

   If you build a custom dungeon for your players and want to use the restocking features of Fill Loot, place a normal chest down. Type /fillloot wand to receive the linking tool. Left-click the chest with the wand, and it will prompt you to type the name of the loot table in chat to link it. This chest is now managed by Fill Loot and will restock on the global timer!

Deep Dive Mechanics

Lazy Generation Workflow

When PaperMC generates a chunk, Fill Loot listens to the ChunkLoadEvent async. It checks if the chunk contains parts of a bounding box for known structures. If it does, it silently marks the block coordinates of any containers. Absolutely zero item calculation happens here, ensuring chunk generation speed remains identical to vanilla.

The Restocking Engine

If auto-restock is enabled, Fill Loot stores the coordinates and the timestamp of when a chest was first opened in a highly efficient flatfile database (or MySQL). A background task checks these timestamps periodically. When the cooldown expires, the chest is purged from the "opened" database. The next time someone clicks it, the plugin acts as if it's a brand new chest and re-rolls the loot.

Weight Calculation

The plugin uses a weighted randomizer. If you have a Diamond with weight 10, and Dirt with weight 90, the total weight pool is 100. The Diamond has a 10% chance to roll, and the Dirt has a 90% chance. You can configure max-items to determine how many times the plugin pulls from the weight pool per chest.

Real-World Use Cases

Fill Loot is highly versatile. Here is how top servers utilize it:

• Economy Integration (Vouchers): Inject physical "Gold Coins" or "Bank Notes" into Mineshaft and Dungeon chests. This creates a viable playstyle where players can earn server economy balance purely through exploration and caving, rather than just building mob farms.
• Server Lore & Secrets: Create custom written books detailing the history of your server or clues to hidden admin bases. Add them to Stronghold library loot tables with an extremely low weight (e.g., weight 1 out of 10000). Finding one becomes a massive server-wide event.
• Custom Daily Dungeons: Using the wand tool, builders can construct a massive castle at spawn, place chests throughout, and link them to high-tier loot tables. With restocking set to 24 hours, players have a daily activity of running the castle to get their daily loot.
• Anarchy/Survival Instancing: On highly populated SMPs, all structures within 10,000 blocks of spawn are looted within the first week. By enabling instanced-loot, a player joining 3 months later can still walk into a looted Desert Temple and find loot generated exclusively for them.

Integrations

Custom Item Plugins (ItemsAdder, Oraxen, MMOItems)

Fill Loot has first-class support for custom item frameworks. Because relying on NBT parsing can sometimes break between version updates, the safest way to inject these items is via the command execution feature. In your config, you can set an item to execute a console command like mmoitems give SWORD STEEL_BLADE %player% when the chest is opened, ensuring perfect compatibility.

PlaceholderAPI

Track restock timers and stats.

Vault

You can define an item in the config with the type: money and amount: 500. Instead of dropping a physical item, it will instantly deposit $500 into the player's balance and send them a chat message when they open the chest.

Commands

Fill Loot provides extensive in-game management tools.

Permissions

Players require absolutely no permissions to open chests and receive loot. These are admin-only nodes.

Configuration Line-by-Line Breakdown

Mastering the config.yml allows you to create incredible exploration rewards.

# ==================================================== #
#                 FILL LOOT MAIN CONFIG                #
# ==================================================== #

# Control how restocking behaves globally.
auto-restock:
  enabled: true
  # Time in seconds until an emptied chest refills itself. (86400 = 24 hours)
  cooldown-seconds: 86400
  # Should we broadcast a server-wide message when a restock wave happens?
  announce-restock: true

# If true, loot is generated specifically for the player opening it.
# Player A takes everything. Player B walks up, opens it, and gets their own loot.
instanced-loot: false

# Enable visual indicators for special chests.
visuals:
  particle-effects: true
  # Only plays when the chest is ready to be looted.
  particle-type: "VILLAGER_HAPPY"
  holograms:
    enabled: true
    text: "<#ffaa00>Rare Loot Box\n<white>Right-click to open!"

# Define your loot tables here. Keys must perfectly match Bukkit structure types 
# OR your custom table names (for wand-linked chests).
structures:
  minecraft:end_city_treasure:
    # The absolute maximum number of slots to fill in the chest.
    max-items: 5
    # If true, it will clear any vanilla loot before adding ours.
    clear-vanilla-loot: true
    items:
      - id: "DIAMOND"
        amount: "1-3"  # Will randomly give between 1 and 3 diamonds.
        weight: 50
      - id: "ELYTRA"
        amount: "1"
        weight: 5
      - type: "command"
        command: "eco give %player% 1000"
        name: "&a$1000 Cash Stash"
        weight: 15

messages:
  restocked: "<#55EFC4>All structure chests have been restocked globally!"
  linked: "<#a8ffaa>Chest successfully linked to custom table: %table%"
  cooldown: "<#ff5555>This chest has already been looted. It will restock in %time%."

Detailed Explanations

auto-restock.cooldown-seconds: This defines the global lifecycle. When a chest is looted, its coordinates are logged with a timestamp. When this timer expires, it is removed from the log. A 24-hour timer (86400) is highly recommended for survival servers to give daily incentives.

instanced-loot: This is a game-changer for large SMPs. When enabled, the plugin intercepts the inventory open event, creates a virtual inventory UI, generates the loot for that specific UUID, and shows it to them. The actual chest block remains completely empty. Once they close it, their state is saved. This means 100 players can loot the same desert temple. However, it requires more database storage.

clear-vanilla-loot: If set to false, Fill Loot will generate its custom items and place them alongside the vanilla items (like bones and string) in the empty slots. If true, it wipes the chest clean before injecting your custom table, ensuring absolute control over the economy.

type: "command": Instead of dropping an item, the chest will execute a console command when opened, replacing %player% with the looter's name. It will place a dummy item in the chest UI (using the name provided) that disappears and runs the command when clicked.

Configuration Templates

The God-Tier Stronghold Table

Copy this into your structures section to make strongholds extremely rewarding, featuring custom names, lore, and heavy enchantments.

  minecraft:stronghold_corridor:
    max-items: 4
    clear-vanilla-loot: true
    items:
      - id: "DIAMOND_SWORD"
        amount: "1"
        weight: 5
        name: "&4&lBlade of the Abyss"
        lore:
          - "&7A sword lost to time."
          - "&7Forged in the darkest depths."
          - ""
          - "&cUnbreakable"
        enchants:
          - "DAMAGE_ALL:6"
          - "FIRE_ASPECT:2"
        unbreakable: true
      - id: "ENCHANTED_GOLDEN_APPLE"
        amount: "1-2"
        weight: 15
      - id: "EXPERIENCE_BOTTLE"
        amount: "16-64"
        weight: 40
      - id: "IRON_INGOT"
        amount: "8-32"
        weight: 100

Troubleshooting & FAQ

Having issues getting your loot to spawn? Check these common pitfalls.

• "Vanilla loot is still spawning instead of my custom items!"

  Ensure that the structure name in config.yml perfectly matches the exact Minecraft namespace. For example, it must be minecraft:igloo_chest, not just igloo. Also, make sure clear-vanilla-loot is set to true. Note that chunks generated BEFORE you installed the plugin might have already cached their loot, you must test in newly generated chunks.

• "My command items aren't running the command."

  Command items place a physical icon in the chest UI to represent the reward. The command is only executed when the player actually clicks that item to take it. If they leave it in the chest, the command won't run. Ensure your command syntax is correct and does not include a leading slash (e.g., use eco give %player% 100, not /eco give %player% 100).

• "Chests instantly restock when I close them."

  Check if your cooldown-seconds is set too low (e.g., set to 10 instead of 86400). Also, if you have aggressive chunk-clearing plugins or aggressive database cleaning scripts, the plugin might be losing the timestamp data, causing it to assume the chest is new. Check your console for database write errors.