> For the complete documentation index, see [llms.txt](https://opuszek.gitbook.io/itemblocker/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://opuszek.gitbook.io/itemblocker/reference/rules-file.md).

# rules.yml

`plugins/ItemBlocker/rules.yml` holds every preset and rule. Commands and the menu write it, but you can also edit it by hand and run `/ib reload`.

{% hint style="info" %}
If `rules.yml` has a YAML error, the previous rules stay active and commands refuse to change them until the file is fixed and reloaded. A command can never overwrite your edits.
{% endhint %}

## Example

```yaml
config-version: 2
presets:
  default:
    description: ''
    reason: '&cThis item is disabled on this server'
    worlds: all
    regions: all
    items:
      tnt:
        actions:
        - place
        - crafting
        worlds: all
      elytra:
        actions:
        - armor
        worlds:
        - world_the_end
        bypass-permission: vip.elytra
      mace:
        actions: obtain
        worlds: all
    groups:
      '*_sword':
        actions:
        - use
        worlds: all
      '#logs':
        actions: all
        worlds: all
    allowed:
    - wooden_sword
    limits:
      ender_pearl:
        stack: 4
        inventory: 16
    filters:
      excalibur:
        type: diamond_sword
        name: Excalibur
        data: nexo:id=excalibur
        actions:
        - use
        - drop
        worlds: all
    enchantments:
      sharpness:
        level: 5
        mode: downgrade
      thorns: 1
    potions:
      strength: 2
  pvp:
    description: Arena rules
    reason: ''
    worlds:
    - arena
    regions: all
    items:
      ender_pearl:
        actions: all
        worlds: all
    groups: {}
    allowed: []
    limits: {}
    filters: {}
    enchantments: {}
    potions: {}
```

## Preset

| Key            | Description                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `description`  | Shown in preset listings                                                                                      |
| `reason`       | Added to messages about restrictions from this preset                                                         |
| `worlds`       | `all`, or a list of worlds the whole preset applies in                                                        |
| `regions`      | `all`, or a list of WorldGuard regions the whole preset applies in                                            |
| `items`        | [Item rules](/itemblocker/rules/items.md) by item key                                                         |
| `groups`       | [Item groups](/itemblocker/rules/groups-and-allowed.md) by pattern; quote patterns that start with `*` or `#` |
| `allowed`      | [Allowed items](/itemblocker/rules/groups-and-allowed.md)                                                     |
| `limits`       | [Limits](/itemblocker/rules/limits.md) by item key, with `stack` and `inventory`                              |
| `filters`      | [Filters](/itemblocker/rules/filters.md) by id                                                                |
| `enchantments` | [Enchantments](/itemblocker/rules/enchantments.md): a level, or a section with `level` and `mode`             |
| `potions`      | [Potion effects](/itemblocker/rules/potion-effects.md) by key, with the lowest blocked level                  |

## Rules

Item rules, groups and filters share these keys:

| Key                 | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| `actions`           | `all`, `obtain`, or a list of [actions](/itemblocker/rules/actions.md) |
| `worlds`            | `all`, or a list of worlds the rule applies in                         |
| `bypass-permission` | Optional; a permission that ignores just this rule                     |

Filters add `type`, `name`, `lore`, `model`, `data` (a key or `key=value`) and `enchantment`; at least one is needed.

## Mistakes

Entries ItemBlocker cannot read, such as unknown items or actions, are skipped with a warning in the console. The rest of the file still loads.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://opuszek.gitbook.io/itemblocker/reference/rules-file.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.