> ## Documentation Index
> Fetch the complete documentation index at: https://perplayerkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Item filtering

> Control kit materials, unbreakable items, enchantments, and potion effects with shared rules and material overrides.

Item filtering applies server-controlled rules to kit items. You can limit materials, enchantments, unbreakable items, attributes, and potion effects independently.

## Enable the checks you need

This uses normal enchantment limits, blocks unbreakable items, and caps potion effects at level II and three minutes:

```yaml config.yml theme={null}
item-filter:
  enabled: true
  kit-room-only: false
  filter-imports: true
  filter-saves: true
  allow-unbreakable: false
  enchantments:
    allow-over-levelled: false
    allow-incompatible: false
  potions:
    max-level: 2
    max-duration-seconds: 180
```

Restart to apply changes. Filtering is off by default.

`kit-room-only: false` lets you limit enchantments and potions without stocking every allowed material in the kit room.

## Where rules apply

| Action                                                  | Behavior when filtering is enabled |
| ------------------------------------------------------- | ---------------------------------- |
| Loading personal, public, or enderchest kits            | Filters the items being delivered  |
| Regear and accepting shared items                       | Uses the same rules                |
| Browsing the kit room as a player                       | Shows filtered contents            |
| Public kit previews                                     | Shows filtered contents            |
| Copying an inventory into a personal editor             | Controlled by `filter-imports`     |
| Saving personal or enderchest kits, including transfers | Controlled by `filter-saves`       |

Public kit and kit room administration, and `/kitdata` imports, preserve source definitions. Admins editing the kit room can see its raw contents.

The filter covers PerPlayerKit workflows. It does not remove items from world pickups or inventories managed by other plugins.

### What happens to rejected items?

Rejected items are removed from the filtered copy. A rejected item inside a shulker or bundle is removed from that container's copy.

If a filter removes every item from a kit, loading or importing that kit leaves the destination inventory or editor unchanged. New saves containing no allowed items are rejected.

Existing stored definitions are preserved when viewed or loaded. Closing an unchanged filtered editor does not rewrite its original definition. Saving changes with `filter-saves` enabled stores the filtered result.

Containers and bundles are checked recursively. Items nested more than 16 container levels are removed.

## Use different rules for a material

Keys inside `overrides` are Bukkit material names. This permits Protection V on diamond chestplates and sets stricter limits on Strength splash potions:

```yaml config.yml theme={null}
item-filter:
  enabled: true
  overrides:
    DIAMOND_CHESTPLATE:
      enchantments:
        max-levels:
          protection: 5
    SPLASH_POTION:
      potions:
        effects:
          strength:
            max-level: 1
            max-duration-seconds: 60
```

Merge this into your existing `item-filter` block. Material overrides replace the specified rule values; omitted values inherit the defaults above them. Limit maps merge by enchantment or effect ID. An empty override map changes nothing.

These rules match the material, regardless of the item's display name. Use Minecraft IDs such as `protection` and `strength` inside limit maps. Custom namespaces use `namespace:id`.

## Settings

| Setting under `item-filter` | Default | Meaning                                                           |
| --------------------------- | ------- | ----------------------------------------------------------------- |
| `enabled`                   | `false` | Enables item filtering                                            |
| `kit-room-only`             | `false` | Requires each material to appear in an enabled kit room page      |
| `filter-imports`            | `true`  | Filters inventory copies placed into personal editors             |
| `filter-saves`              | `true`  | Filters new personal and enderchest kit saves                     |
| `allow-unbreakable`         | `false` | Allows the unbreakable item property                              |
| `allow-custom-attributes`   | `false` | Allows explicit attribute modifiers, such as custom attack damage |
| `allow-item-flags`          | `true`  | Allows tooltip visibility flags, such as hiding enchantments      |
| `overrides`                 | `{}`    | Rule overrides by material                                        |

Material overrides can contain the three `allow-*` settings above, `enchantments`, and `potions`. The workflow switches stay at the top level.

With `kit-room-only` enabled, an empty kit room blocks kit loading rather than replacing inventories with empty copies. Hidden pages do not supply allowed materials. Stack amounts must be positive and within the item's maximum stack size.

### Enchantments

| Setting under `enchantments` | Default | Meaning                                                                           |
| ---------------------------- | ------- | --------------------------------------------------------------------------------- |
| `allow-over-levelled`        | `false` | Allows levels above the normal maximum for enchantments without an explicit limit |
| `allow-incompatible`         | `false` | Allows invalid item/enchantment combinations and conflicting enchantments         |
| `max-levels`                 | `{}`    | Explicit limits by enchantment ID; `0` removes that enchantment's level cap       |

Explicit limits take precedence over the normal maximum and `allow-over-levelled`. Applied enchantments and enchantments stored in books are both checked. Stored book enchantments do not need to be applicable to the book itself.

For example, Protection X is rejected by the normal level-IV limit. A material override setting `protection: 10` allows it on that material.

### Potions and tipped arrows

| Setting under `potions` | Default | Meaning                                                                |
| ----------------------- | ------- | ---------------------------------------------------------------------- |
| `max-level`             | `0`     | Maximum displayed effect level; `0` leaves this cap disabled           |
| `max-duration-seconds`  | `0`     | Maximum stored effect duration; `0` leaves this cap disabled           |
| `effects`               | `{}`    | Additional `max-level` and/or `max-duration-seconds` caps by effect ID |

Level `1` means level I, and level `2` means level II. A positive duration cap rejects infinite effects too.

Base potion effects and custom effects are both checked. Duration limits use the stored duration, before splash or lingering-potion adjustments.

An effect must pass both the general potion caps and its effect-specific caps. A specific cap cannot increase the general cap. Set the relevant general cap higher, or to `0`, if you want a larger effect-specific limit.

## Upgrading existing filter settings

The old `anti-exploit.only-allow-kitroom-items` and `anti-exploit.import-filter` settings are converted automatically, with a config backup.

Migrated configs retain their existing switches, including filtering on use rather than on save. Enable `item-filter.filter-saves` to filter new saves too. Review `allow-unbreakable`, `allow-item-flags`, and `allow-incompatible` to opt into stricter checks.

Enchanted books and nested items receive the same checks as ordinary kit items. Existing definitions are not automatically rewritten.

## Other exploit settings

| Setting under `anti-exploit`      | Default | Meaning                                             |
| --------------------------------- | ------- | --------------------------------------------------- |
| `block-spaces-in-commands`        | `false` | Blocks unusual command spacing                      |
| `prevent-shulkers-dropping-items` | `false` | Removes dropped shulker boxes when they take damage |

Use [Purge items](/data/purge-items) to permanently remove a material from stored kits. See [Kit room setup](/kit-room) for stocking allowed materials.