> For the complete documentation index, see [llms.txt](https://zentrix.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zentrix.gitbook.io/docs/core-mechanics/cornucopia/loot.md).
# Cornucopia Loot
Cornucopia loot is a server-wide pool stored in `plugins/Zentrix/loot_pool.yml`. Each ready runtime Cornucopia gets a new randomized generation across its supported containers.
{% hint style="info" %}
Use `/zx loot` as a player to manage this file safely. The menu preserves the complete item, including its name, lore, enchantments, attributes, custom model data, and supported custom-item identity.
{% endhint %}
### Editor workflow
{% stepper %}
{% step %}
## Open the pool
```
/zx loot
```
The main menu lists every entry, its enabled state, validation result, weight, limits, quantity range, and allowed containers.
{% endstep %}
{% step %}
## Add or import items
Choose **Add Item** and drag the desired stack into the picker, or use **Import Loot Table** to browse local and built-in Minecraft chest loot tables.
{% endstep %}
{% step %}
## Tune each entry
Set its selection weight, total appearance range, per-container limit, generated stack size, and allowed container families.
{% endstep %}
{% step %}
## Resolve validation issues
The pool menu reports invalid entries. Correct the first reported issue and repeat until the configuration shows as valid.
{% endstep %}
{% step %}
## Simulate before a match
Choose **Simulate Loot** to run the real random selection against simulated containers. Reroll several times to judge variety and identify space-limited entries.
{% endstep %}
{% endstepper %}
### Entry controls
| Control | What it means |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Enabled | Disabled entries stay saved but cannot generate. |
| Selection weight | Relative chance during optional selection; it is not a percentage. A weight of `20` is selected roughly twice as often as `10` when both entries are otherwise eligible. |
| Minimum total appearances | Guaranteed attempts across the complete Cornucopia. Use `0` for purely optional loot. |
| Maximum total appearances | Hard cap across all containers in one generation. |
| Maximum per container | Hard cap for this entry inside one container. |
| Minimum / maximum quantity | Inclusive stack-size range created for each appearance. |
| Allowed containers | Limits the entry to chests, trapped chests, barrels, and/or shulker boxes. |
{% hint style="warning" %}
An **appearance** is one generated stack, not one item. An entry with `minimum quantity: 3` and `minimum total appearances: 2` guarantees attempts to place two stacks of at least three items each.
{% endhint %}
### How generation balances loot
{% tabs %}
{% tab title="Required loot" %}
Minimum appearances are placed first. Zentrix spreads these attempts across the least-filled compatible containers while respecting total, per-container, type, and slot limits.
{% endtab %}
{% tab title="Optional loot" %}
After required appearances, weighted selection fills more slots. Containers receive rolls in rounds so one chest is less likely to consume the entire pool before distant containers are considered.
{% endtab %}
{% tab title="Container fill" %}
Each container receives a randomized target based on its slot count. The actual result can be lower when entries are disabled, incompatible, at their caps, invalid, weightless, or unable to fit.
{% endtab %}
{% endtabs %}
Why a minimum appearance may still be reported as unplaced
A minimum is a required placement attempt, but physical and configured limits still apply. It can remain unplaced when there is no compatible container, no eligible empty slot, the per-container or total cap blocks it, or the stored item cannot be created.
The simulation lists required appearances that could not fit. Adjust container types, limits, or the schematic's available container space, then reroll.
## Add complete items
{% columns %}
{% column %}
#### Copied items
Place any normal Paper `ItemStack` in the picker. Zentrix stores a complete serialized copy, not only the material name.
{% endcolumn %}
{% column %}
#### Custom items
ItemsAdder and Nexo items retain their source identifier when recognized. Keep the corresponding plugin and item definition installed so the entry remains valid.
{% endcolumn %}
{% endcolumns %}
{% hint style="danger" %}
Do not hand-edit the Base64 `item` value. Paper or custom-item updates can change serialized item data. Keep backups and re-add an item through `/zx loot` if an upgrade reports it as missing or corrupted.
{% endhint %}
## Import loot tables
{% tabs %}
{% tab title="Minecraft tables" %}
Choose **Import Loot Table → Minecraft** to browse the server's built-in chest loot tables. Preview the generated candidates, then import the displayed set into the Cornucopia pool.
{% endtab %}
{% tab title="Local JSON tables" %}
Place vanilla-format chest loot-table JSON files under:
```
plugins/Zentrix/loot_tables/
```
Open **Import Loot Table → Local**, select a table, review its generated preview, and confirm the import.
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Importing adds new editable entries; it does not keep a live link to the source loot table. Re-importing the same table adds another generated set rather than updating earlier entries.
{% endhint %}
## Validation and activation
The editor saves changes to disk even when an entry is invalid, but only a fully valid pool becomes active. Common checks include:
* A readable, non-air item is stored.
* Weight is zero or greater.
* At least one container type is allowed.
* Minimum appearances are not negative and do not exceed the maximum.
* Per-container maximum is at least `1`.
* Quantities start at `1`, stay ordered, and do not exceed the item's stack limit.
* Recognized ItemsAdder or Nexo items still exist.
{% hint style="success" %}
Zentrix retains the last-known-good active pool. A broken manual edit or failed `/zx reload loot` does not replace working runtime loot with an invalid configuration.
{% endhint %}
For the on-disk schema and backup behavior, see [`loot_pool.yml`](/docs/core-mechanics/configurations/loot_pool.yml.md). For command and permission details, see [Loot Commands](/docs/commands/commands/admin-commands/loot-commands.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://zentrix.gitbook.io/docs/core-mechanics/cornucopia/loot.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.