Filters

A filter is a yes-or-no question the game asks about a mob. "Is the attacker a player?" "Is it daytime?" "Is this mob in water?" If the answer is yes, the filter passes and whatever it guards is allowed to happen.

Filters show up all over a mob's files: in events, in components like damage sensors and targeting, and in spawn rules. Learn them once and you can use them everywhere.

The files

Filters are not a file of their own. They sit inside other files, under keys called filters (or biome_filter in spawn rules).

BP/
  entities/
    ruby_golem.json      <- in events and many components
  spawn_rules/
    ruby_golem.json      <- minecraft:biome_filter

One test

The smallest filter is a single test:

{ "test": "is_family", "subject": "other", "operator": "==", "value": "player" }

Read it as a sentence: "Is the other entity's family equal to player?"

Thanks to the defaults, short filters are common:

{ "test": "is_daytime" }
{ "test": "in_water", "value": false }
{ "test": "has_tag", "value": "wiki:tamed" }

The first one asks "is it daytime?". The second asks "is this mob not in water?".

Subjects: who is being tested

Which subjects make sense depends on where the filter is. In a damage sensor, other and damager are the attacker. In a targeting behavior, other is the mob being considered as a target.

Operators: how to compare

The greater/less operators only make sense for number tests like actor_health or distance_to_nearest_player.

Combining tests

Put several tests together with a group:

Groups can hold other groups, so you can build any rule you need. This one passes for a player who is not sneaking, at night or in a thunderstorm:

"filters": {
  "all_of": [
    { "test": "is_family", "subject": "other", "value": "player" },
    { "test": "is_sneaking", "subject": "other", "value": false },
    {
      "any_of": [
        { "test": "is_daytime", "value": false },
        { "test": "weather_at_position", "value": "thunderstorm" }
      ]
    }
  ]
}

Where filters are used

Damage sensor: react to who hit you

"minecraft:damage_sensor": {
  "triggers": [
    {
      "on_damage": {
        "filters": { "test": "is_family", "subject": "other", "value": "player" },
        "event": "wiki:become_angry"
      }
    }
  ]
}

Only players make the golem angry. Damage from mobs, falls or fire does nothing special. See minecraft:damage_sensor.

Targeting: who to attack

"minecraft:behavior.nearest_attackable_target": {
  "priority": 2,
  "entity_types": [
    {
      "filters": {
        "all_of": [
          { "test": "is_family", "subject": "other", "value": "monster" },
          { "test": "is_family", "subject": "other", "operator": "not", "value": "creeper" }
        ]
      },
      "max_dist": 16
    }
  ]
}

The golem hunts monsters, but leaves creepers alone. See behavior.nearest_attackable_target.

Environment sensor: react to the world

"minecraft:environment_sensor": {
  "triggers": [
    {
      "filters": { "test": "in_water" },
      "event": "wiki:start_rusting"
    }
  ]
}

The environment sensor checks its filters all the time and fires the event while they pass.

Events and spawn rules

Inside events, filters decide whether an entry runs (see Entity events). In spawn rules, minecraft:biome_filter uses the same tests to pick biomes (see Spawn rules).

The most useful tests

There are over a hundred tests. These are the ones you will reach for most often, grouped by what they check.

Who is it?

Health and state

Items

Where it is

Distance

Time, weather and the world

Entity properties

These read the properties declared in the mob's description. The property name goes in domain:

{ "test": "enum_property", "domain": "wiki:mood", "value": "angry" }

When something goes wrong

More help is in Troubleshooting.