# Task progression filters

> Restrict when a task counts: worlds, regions, biomes, Y-level, held item, requirements

Every task can have an optional `filters:` section that restricts **when progression is counted**. For example, only count blocks broken in a certain world, below a certain Y level, or while holding a specific pickaxe. Filters live inside a task, next to `args`:

```yaml
tasks:
  mine_deep:
    task: BLOCK_BREAK
    display: "{status} &fMine {required} deepslate &b{current}&f/&b{required}"
    args:
      amount: 100
      types:
        - "minecraft:deepslate"
    filters:
      worlds:
        type: whitelist
        value: [ "world" ]
      max-ylevel: 0
```

:::callout{type="neutral"}
All filters are optional — include only the ones you need, or omit the whole `filters` section. When several filters are present, a task only progresses when **all** of them pass.
:::

# worlds

Restrict progression to (or away from) specific worlds. `type` is `whitelist` (only these worlds count) or `blacklist` (these worlds never count).

```yaml
    filters:
      worlds:
        type: whitelist
        value: [ "world", "world_nether" ]
```

# regions

Restrict progression to specific WorldGuard regions. Same `whitelist` / `blacklist` `type`. Requires [WorldGuard](../auroraquests/compatible-plugins.md) — if WorldGuard isn't installed, this filter is simply ignored. Use `/rg info` in-game to find region names.

```yaml
    filters:
      regions:
        type: blacklist
        value: [ "spawn", "safezone" ]
```

# biomes

Restrict progression to specific biomes. Use namespaced biome keys. Same `whitelist` / `blacklist` `type`.

```yaml
    filters:
      biomes:
        type: whitelist
        value: [ "minecraft:plains", "minecraft:forest" ]
```

# min-ylevel / max-ylevel

Restrict progression by the Y coordinate where the action happens. You can use either bound on its own or both together to define a band.

```yaml
    filters:
      min-ylevel: -64
      max-ylevel: 16
```

# hand

Only count progression while the player is holding a matching item. List one or more items — **only one needs to match**. Supports vanilla materials and the custom-item formats of supported plugins (see [Item config](../aurora/item-config.md)).

```yaml
    filters:
      hand:
        items:
          - "minecraft:diamond_pickaxe"
          - "minecraft:netherite_pickaxe"
          - "nexo:mythril_pickaxe"
```

# requirements

A general-purpose gate using the Aurora requirement system — the same requirements available for custom menu items. Progression is only counted when **all** listed requirements are met. Handy for things like "only count while the player has a permission", "only during a certain time", etc. You can use `{player}` as a placeholder.

```yaml
    filters:
      requirements:
        - "[permission] your.permission"
        - "[placeholder] %some_placeholder% == value"
```

Each entry uses the `[prefix] args` format. See [Custom menus requirements](../aurora/custom-menus-requirements.md) for the full list of available requirement types (`[permission]`, `[money]`, `[has-items]`, `[placeholder]`, …) and their syntax.

# Full example

```yaml
tasks:
  farm_wheat:
    task: FARM
    display: "{status} &fHarvest {required} wheat &b{current}&f/&b{required}"
    args:
      amount: 64
      types:
        - "minecraft:wheat"
    filters:
      worlds:
        type: whitelist
        value: [ "farmworld" ]
      regions:
        type: blacklist
        value: [ "spawn" ]
      biomes:
        type: whitelist
        value: [ "minecraft:plains" ]
      min-ylevel: 60
      max-ylevel: 120
      hand:
        items:
          - "minecraft:golden_hoe"
      requirements:
        - "[permission] farming.quests"
```