# Loot Configuration Guide

This guide is for players who only want to change monster-bag loot.

Edit `loot_config.lua` in the `BagLootFramework` root folder. Use `item_catalogue.md` to find item IDs. You do not need to open `Scripts` or edit any other file.

## What a configured bag means

Every bag listed in `loot_config.lua` has this shape:

```lua
ITEM_Consumable_SomeBag = {
    Loot = {
        -- Item blocks go here.
    }
},
```

The `Loot` list completely replaces that bag's original drops. Bags not listed in the configuration keep their normal game loot.

## Complete example

This configuration makes the bags roll the following drops:

Bird Nest:

- 1 Iron Sword, 100% chance
- 10 to 20 Rune Essence, 100% chance

Goblin Pack:

- 1 to 2 Burnt Shrimp, 20% chance

```lua
return {

--------------------------------------------------------------------------------
-- Bird Nest
--------------------------------------------------------------------------------

ITEM_Consumable_BirdNest = {
    Loot = {
        -- Guaranteed example drops.
        { Item = "ITEM_Sword_Iron",  DropRate = 1.0, Min = 1,  Max = 1  },
        { Item = "ITEM_Rune_Essence", DropRate = 1.0, Min = 10, Max = 20 },
    }
},

--------------------------------------------------------------------------------
-- Goblin Pack
--------------------------------------------------------------------------------

ITEM_Consumable_GoblinPack = {
    Loot = {
        -- Occasional burnt lunch.
        {
            Item = "ITEM_Consumable_Fish_Shrimp_Burnt",
            DropRate = 0.2,
            Min = 1,
            Max = 2
        },
    }
},

}
```

Short item blocks can stay on one line. Longer item blocks can be expanded across several lines. Both formats work exactly the same.

To add an item, copy one complete `{ ... },` item block, paste it inside the bag's `Loot` block, and change its four values. A trailing comma after the final block—or after a field such as `Max = 20,`—is valid Lua and makes copying safer.

Keep quotation marks, braces, commas, and field names intact. Broken item blocks or bags are ignored, and the problem is printed to `UE4SS.log`.

## Item block fields

### `Item`

Use an exact ID from `item_catalogue.md`:

```lua
Item = "ITEM_Resources_Diamond",
```

Names shown to players, such as `Diamond`, will not work here.

### `DropRate`

The chance that this item block drops, or "triggers":

```lua
DropRate = 0.05,
```

`0.05` means 5%, `0.5` means 50%, and `1.0` means 100%. Use a number from `0` to `1`.

Every item block rolls independently. You can use multiple similar or overlapping item blocks to create more advanced drop statistics.

### `Min` and `Max`

The number of items dropped after a successful roll:

```lua
Min = 0,
Max = 3,
```

A successful roll in this example drops 0, 1, 2, or 3 items. This means a triggered block does not necessarily produce loot. Combined with multiple item blocks, this can be used to create more advanced drop statistics.

Both values must be whole numbers of zero or more, and `Min` cannot be greater than `Max`. `Min` and `Max` may be the same value—for example, both may be for example `1` to drop a fixed amount.

## Known monster-bag IDs

These are the bag IDs the mod is designed to edit. They must be written exactly as shown:

```text
ITEM_Consumable_BirdNest
ITEM_Consumable_GoblinPack
ITEM_Consumable_GarouPack
ITEM_Consumable_SkeletonPack
ITEM_Consumable_ZombiePack
ITEM_Consumable_ZogrePack
ITEM_Consumable_Pack_Zamorak_Mage
ITEM_Consumable_Pack_Zamorak_Warrior
ITEM_Consumable_Pack_Ashes_Demonic_Small
ITEM_Consumable_Pack_Ashes_Demonic_Lesser
ITEM_Consumable_KutPack <-- Note misspelling of "KotPack"
```

These use the game's Consumable Item Emitters: inventory items that are consumed to produce loot. Other quest-reward bags may also work, but have not been tested.

## If the mod reports a warning or error

Search `UE4SS.log` for `[BagLootFramework]`:

- `CONFIG ERROR` means `loot_config.lua` could not be loaded at all. Nothing is changed.
- `CONFIG WARNING` means one bag or drop block is malformed. That block is ignored while other valid configuration continues.
- `RESOLVER WARNING` means an item ID is unknown, its object was unavailable, or Unreal could not convert it to the required pointer. That drop is ignored.
- `BUILDER WARNING` means a bag did not match a loaded emitter or the expected loot structure was unavailable. The affected bag or emitter is left alone when possible.
- Any `ERROR` line names the startup or runtime stage that stopped safely.

An unresolved drop does not block the other valid drops in the same bag. If a non-empty bag configuration has no usable drops, the framework preserves that bag's complete original loot rather than clearing it. An explicitly empty `Loot = {}` still means "clear this bag."
