## Drop Tables

**The filename is the ID.** A drop table is looked up by its filename stem
(`gem_table.yaml` → `gem_table`); reference it from behaviors/mobs by that name. Do not put
an `id:` field in the file — it is ignored.

### Shared drop table entries

Shared drop tables in `data/drops/` are pure weighted pools of items. Each entry supports
only three fields (four with `table`):

```yaml
# data/drops/gem_table.yaml
drops:
  - item_id: uncut_sapphire
    weight: 47
  - item_id: uncut_emerald
    weight: 16
  - item_id: uncut_ruby
    weight: 4
  - item_id: uncut_diamond
    weight: 1
```

| Field | Required | Description |
|-------|----------|-------------|
| `item_id` | XOR with `table` | Item ID to drop |
| `table` | XOR with `item_id` | Reference to another shared drop table (can nest) |
| `weight` | yes | Relative drop weight |
| `quantity` | no | Amount to drop (default 1) |

**`item_id` and `table` are mutually exclusive per entry.** The entry drops *either* the named
item *or* rolls on the referenced sub-table; never both.

### What does NOT belong on a shared drop table

The following fields are **meaningless on shared drop table entries** and are ignored by the
engine — they belong on the *referencing* gather entry in the object config instead:

- `depletes` — controls whether the gatherable node depletes (per-drop; ore vs gem). Set on
  the `gather.drops[]` entry in the object YAML that references this table.
- `level` — skill-level gate on a drop. Only meaningful on the outer gather entry.
- `xp` — skill XP for this drop. Only meaningful on the outer gather entry.
- `tool` — tool-type filter. Only meaningful on the outer gather entry.
- `success_message` — per-drop message. Overridden by the outer entry when referenced via
  `table:`.

The admin Drop Table editor intentionally shows only `item_id`/`table` (toggle), `weight`,
and `quantity`. Edit the raw YAML if you need niche overrides.

### Examples

Bird's nest drop table:
```yaml
# data/drops/birds_nest_drop.yaml
drops:
  - item_id: credits
    weight: 50
    quantity: 200
  - item_id: credits
    weight: 30
    quantity: 500
  - item_id: credits
    weight: 15
    quantity: 1000
  - item_id: credits
    weight: 4
    quantity: 3000
  - item_id: credits
    weight: 1
    quantity: 10000
```

Referenced from a gather behavior (note `depletes` lives on the **outer** entries here,
not inside `gem_table`):
```yaml
gather:
  drops:
    - item_id: copper_ore
      weight: 90
      level: 1
      xp: 17
      depletes: true
      success_message: "You manage to mine some copper ore."
    - table: gem_table          # pulls from data/drops/gem_table.yaml
      weight: 10
      depletes: false           # gem drops don't deplete the rock
      success_message: "You spot a glint of something valuable!"
```

---